Create Agent

POST /agent/v1/agents◐ Partial

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).
▸ 展开子字段（5）
- 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.
- settingsobject可选
  Platform model settings. Only reasoning is supported; other model controls return 400.
systemstring可选
The agent's system prompt.
metadataobject可选
Custom metadata key-value pairs; up to 16 keys of at most 512 characters each.
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）
- typestring必填
  Server type; only url is supported today.
  取值 url
- namestring必填
  Name unique within this list, 1-255 characters, referenced by mcp_toolset configurations.
- urlstring必填
  The MCP server's endpoint URL.
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.
computer_idstring可选
Praxis extension: MA only has session-scoped temporary containers and memory_stores, not durable browsable computers. computer_id selects a tenant-owned active computer. Session selection overrides the agent default; a sandbox environment_id and computer_id cannot be combined.
▸ 更多参数（2）
- subagent_modelstring可选
  Own-face extension: revision-pinned default subagent model ID. Omit to preserve; null clears it. Priority: call model, this field, then the roster member model or the parent model for built-ins. Not accepted or returned on the compatibility face.
- modelsobject可选
  Extension: selectable models, available only on /agent/v1.
  ▸ 展开子字段（1）
  - allowedarray必填
    Must include the default model. Omit on creation to allow only the default; omit on update to preserve the list. Sessions use their pinned version’s list.

Returns

200

agent_toolset_20260401 is the native toolset: bash, edit, glob, grep, read, write, web_search, web_fetch, TaskOutput, TaskStop, Monitor, Agent and SendMessage. New agents enable all tools by default. Configure each tool through name, enabled and permission_policy in configs; omitted tools follow default_config (enabled by default). Background tasks, Monitor and subagents require bash. Enabling any background tool exposes bash run_in_background. The /anthropic compatibility API accepts and returns only the eight official tools, and sessions created there receive only those tools. Supports text prompts, models, metadata and built-in tools. Optional model.settings.reasoning accepts low, medium, high, xhigh or none as the session default. Explicit session thinking takes precedence; unsupported agent defaults fall back to the model default_effort. Example model: {id: "deepseek-v4-flash", settings: {reasoning: "high"}}. Skills and other additional model controls are not supported and return 400. Set up to 100 allow, ask and deny rules in toolset permissions for future conversations. 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. A roster can enable Agent while bash is enabled; SendMessage follows its tool configuration. 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. The /agent/v1 top-level subagent_model is a nullable model ID stored in each revision: omit to preserve, null to clear. The model must exist. Priority: call model > subagent_model > roster member model (parent session model for built-ins). /anthropic neither accepts nor returns this field.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Response

HTTP 200

Successful response

application/json

Name	Type	Description
id	string	Agent id (agent_...). Pass it as agent when creating a session and as agent_id in agent calls.
archived_at	null \| string	A timestamp in RFC 3339 format
created_at	string	A timestamp in RFC 3339 format
description	null \| string	Free-text description of what the agent is for; null when none was set.
mcp_servers	array<object>	URL MCP servers the agent can call, paired one-to-one with mcp_toolset entries in tools and saved with the agent version. No credentials are stored here.
mcp_servers[].type	string	Always `url`. An MCP server reached over a URL.
mcp_servers[].name	string	Name of the MCP server; the mcp_toolset entry that refers to it uses the same name in mcp_server_name.
mcp_servers[].url	string	http(s) endpoint of the MCP server, at most 2048 characters.
metadata	object	Free-form string key/value pairs stored with the agent for your own bookkeeping.
model	object	Model identifier and configuration.
model.id	string	The model that will power your agent. See models for additional details and options.
model.effort	object	How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
model.inference_geo	string	Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
model.speed	string	Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.
model.settings	object	Platform model settings. Only reasoning is supported; other model controls return 400.
multiagent	null \| object	Resolved coordinator topology with a concrete agent roster.
multiagent.agents	array<object>	Agents the coordinator may spawn as session threads, each resolved to a specific version.
multiagent.type	string	Always `coordinator`. The agent coordinates the roster in agents and can delegate to its members.
name	string	Display name of the agent, as set on create or update. It is a label, not a unique key.
skills	array<object>	Skill attachments are not supported: a nonempty skills array returns 400. Omit this field or send an empty array. The native Skill tool loads available runtime skills independently of this field.
skills[].skill_id	string	Id of the skill to attach.
skills[].type	string	Always `anthropic`. A skill provided by Anthropic, identified by skill_id. / Always `custom`. A skill created by you, identified by skill_id.
skills[].version	string	Version of the skill; a string.
system	null \| string	System prompt given to the model at the start of every session of this agent; null when none was set.
tools	array<object>	Tools of the agent: one agent_toolset_20260401 entry for the native tools (all resolved settings are returned, ready to send back on update), plus mcp_toolset entries; custom tool definitions are rejected with 400. Keep bash enabled to use codemode, Skill and subagents.
tools[].configs	array<object> \| array \| null	Per-tool settings that override default_config. Tools that are not listed follow default_config.
tools[].default_config	object \| object \| null	Resolved default configuration for agent tools. / Settings applied to every tool of this toolset that configs does not name. When omitted, tools are enabled with the always_allow policy.
tools[].type	string	Always `agent_toolset_20260401`. The native toolset entry (bash, edit, glob, grep, read, write, web_search, web_fetch, TaskOutput, TaskStop, Monitor, Agent, SendMessage). / Always `mcp_toolset`. An entry that exposes the tools of one MCP server from mcp_servers. / Always `custom`. A custom tool defined by name, description and input_schema; its calls are answered by the client with user.custom_tool_result.
tools[].mcp_server_name	string	Name of the MCP server in mcp_servers whose tools this entry exposes.
tools[].description	string	What the custom tool does and when the model should call it.
tools[].input_schema	object	JSON Schema for custom tool input parameters.
tools[].name	string	Name of the custom tool, as the model sees and calls it.
type	string	Always `agent`. An agent definition.
updated_at	string	A timestamp in RFC 3339 format
version	number	The agent's current version. Starts at 1 and increments when the agent is modified.
computer_id	string	Praxis extension: MA only has session-scoped temporary containers and memory_stores, not durable browsable computers. computer_id selects a tenant-owned active computer. Session selection overrides the agent default; a sandbox environment_id and computer_id cannot be combined. Omitted when no computer is selected.
subagent_model	string \| null	Praxis extension: default subagent model ID, pinned in the agent revision. Call model overrides this; otherwise it overrides the roster member model or the parent model for built-ins. Null clears the default. /agent/v1 only.
models	object	Praxis extension: switchable model ids on /agent/v1 only. The default model must be included. When omitted, only the default model is selectable.
models.allowed	array<string>	Model ids a session may select with its model field; it must be non-empty and must contain the agent's default model.