---
title: "Create an autonomous AI agent on the user's Fine Structure account: a standing worker, not a chat session"
method: POST
path: "/api/mcp/tools/create_agent"
tags: ["tools"]
---

# Create an autonomous AI agent on the user's Fine Structure account: a standing worker, not a chat session

`POST /api/mcp/tools/create_agent`

## Request

- Base URL: `https://finestructure.ai`
- URL: `https://finestructure.ai/api/mcp/tools/create_agent`
- Auth: HTTP bearer

Create an autonomous AI agent on the user's Fine Structure account: a standing worker, not a chat session. It gets the platform's default safe tool policy and its own email address, it can read and write the app database, and once the owner phone is verified (see get_agent_whatsapp) it can message its owner on WhatsApp and by email through the platform system channels. Pair it with schedule_agent_task for recurring work such as following up new leads on WhatsApp each morning, watching an app for runtime errors, or sending a weekly summary. Messaging anyone other than the verified owner requires a channel the owner connects in the Fine Structure Studio.

## Request body

- object
  - `name` string: Agent display name (e.g. 'Lead Follow-up'). Auto-derived from role when omitted.
  - `role` string, required: Short role label (e.g. 'sales assistant')
  - `description` string, required: What this agent is responsible for, one or two sentences
  - `persona` string: Optional working style and tone instructions for the agent
  - `app_id` string: Optional app to attach the agent to; account-level when omitted

## Response `200`

Tool executed successfully

- ToolResult
  - `ok` boolean, required
  - `tool` string, required
  - `result` object, required

## Other responses

- `400`: Invalid arguments for this tool
- `401`: Missing or invalid bearer token
- `402`: Not enough credits on the account
- `403`: Token scope does not permit this tool
- `404`: Unknown tool name
- `429`: Rate limit exceeded, retry after the indicated delay
- `500`: Internal error while executing the tool

---

[API](https://skmtc.dev/finestructure/apis/fine-structure-api.md) · [All operations](https://skmtc.dev/finestructure/apis/fine-structure-api/llms.txt) · [OpenAPI document](https://skmtc.dev/finestructure/apis/fine-structure-api/revisions/02c50ed5fd70?raw)