Create Agent

Request body

• namestring必填

  Human-readable agent name, 1-255 characters, unique within the workspace.

• modelstring | object必填

  The model powering the agent: a model name string (e.g. claude-opus-5) or an object for extra configuration (see subfields).

  ▸ 展开子字段（4）

  • idstring必填

    The model name string, e.g. claude-opus-5.

  • effortstring | object可选

    How hard the model works per inference: a bare level string (e.g. high) or a {type: high} object. On create, omitted resolves the per-model default; on update, omitting preserves it.

  • inference_geostring可选

    Geographic region for inference; unset falls through to the workspace default. model is replaced wholesale — omitting the subfield on update clears it.

  • speedstring可选

    Inference speed mode: fast generates output notably quicker at premium pricing. Not all models support it; invalid combinations are rejected at create time.

• systemstring可选

  The agent's system prompt.

• descriptionstring可选

  What the agent does.

• mcp_serversarray可选○ 未支持

  MCP servers the agent connects to; up to 20 with unique names. Every server must be referenced by an mcp_toolset in tools, or the request is rejected.

  ▸ 展开子字段（3）

  • namestring必填

    Name unique within this list, 1-255 characters, referenced by mcp_toolset configurations.

  • typestring必填

    Server type; only url is supported today.

    取值 url
  • urlstring必填

    The MCP server's endpoint URL.

• metadataobject可选

  Custom metadata key-value pairs; up to 16 keys of at most 512 characters each.

• multiagentobject可选

  Multiagent topology: the session's primary thread orchestrates work by spawning session threads drawn from the agents roster.

  ▸ 展开子字段（2）

  • agentsarray必填

    A roster of 1-20 agent IDs, {type: agent, id, version?} references or at most one {type: self}. Versions are pinned on create/update. Members must be distinct, exist, be unarchived and have no multiagent topology. Each coordinator permits at most one advisor whose model must be available and differ from the agent model; only the primary session can consult it, each consultation uses a separate advisor thread, and advice returns via agent.thread_message_received.

  • typestring必填

    Topology type; only coordinator today.

    取值 coordinator
• skillsarray可选○ 未支持

  Skills available to the agent.

• toolsarray可选

  Tool configurations for the agent; up to 128 tools across all toolsets.

Returns

200

Supports text prompts, models, metadata and built-in tools. MCP, skills and additional model controls are not supported and return 400. multiagent accepts null or a coordinator roster of 1–20 agent IDs, {type:"agent",id,version?} references or at most one {type:"self"}. Versions are pinned on create/update. Members must be distinct, exist, be unarchived and have no multiagent topology. The compatibility API provides only the eight official tools: bash, edit, glob, grep, read, write, web_search and web_fetch. configs rejects other tool names. Sessions created here do not provide background tasks, Monitor or subagents. Use /agent/v1 for all native tools. Each coordinator permits at most one advisor whose model must be available and differ from the agent model; only the primary session can consult it, each consultation uses a separate advisor thread, and advice returns via agent.thread_message_received.

Errors follow the Claude Managed Agents format — see error codes