Create or update agent (upsert)
PUT /v1/agents/{agent_id}
If agent with this ID exists, update it. If not, create it. Returns 201 on create, 200 on update.
Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Agent ID (format: agent_{32-hex})
Request Body required
Section titled “Request Body required ”Request to create a new agent
object
Capabilities to enable for this agent with per-agent configuration.
Each capability has a ref (capability ID) and optional config.
Per-agent capability configuration
Associates a capability with an agent, including optional per-agent configuration. The config field allows the same capability to behave differently per-agent.
object
Per-agent configuration for this capability (capability-specific)
Reference to the capability ID
Example
[ { "config": {}, "ref": "current_time" }, { "config": {}, "ref": "web_fetch" }]The ID of the default LLM model to use for this agent. If not specified, the system default model will be used.
Example
model_01933b5a00007000800000000000001A human-readable description of what the agent does.
Example
Handles customer inquiries and support ticketsClient-supplied agent ID (format: agent_{32-hex}). If not provided, one is auto-generated.
Example
agent_01933b5a00007000800000000000001The name of the agent. Used for display purposes.
Example
Customer Support AgentThe system prompt that defines the agent’s behavior and capabilities. This is sent as the first message in every conversation.
Example
You are a helpful customer support agent. Be polite and professional.Tags for organizing and filtering agents.
Example
[ "support", "customer-facing"]Client-side tools for this agent. These tools are sent to the LLM but executed by the client, not the server.
Built-in tool - executed by the worker via ToolRegistry
object
Tool description for LLM
Human-readable display name for UI rendering (e.g., “Get Current Time” for get_current_time)
Tool name (used by LLM and for registry lookup)
JSON schema for tool parameters
Tool policy (auto or requires_approval)
Client-side tool - executed by the client, not the server
object
Tool description for LLM
Human-readable display name for UI rendering
Tool name (used by LLM and for correlation)
JSON schema for tool parameters
Responses
Section titled “ Responses ”Agent updated
Agent configuration for agentic loop. An agent defines the behavior and capabilities of an AI assistant.
object
Capabilities enabled for this agent with per-agent configuration. Capabilities add tools and system prompt modifications.
Per-agent capability configuration
Associates a capability with an agent, including optional per-agent configuration. The config field allows the same capability to behave differently per-agent.
object
Per-agent configuration for this capability (capability-specific)
Reference to the capability ID
Timestamp when the agent was created.
Default LLM model ID for this agent. Can be overridden at the session level.
Example
model_01933b5a00007000800000000000001Human-readable description of what the agent does.
External identifier (agent_<32-hex>). Shown as “id” in API. Client-supplied or auto-generated.
Example
agent_01933b5a000070008000000000000001Display name of the agent.
Current lifecycle status of the agent.
System prompt that defines the agent’s behavior. Sent as the first message in every conversation.
Tags for organizing and filtering agents.
Client-side tools registered for this agent. These tools are executed by the client, not the server.
Built-in tool - executed by the worker via ToolRegistry
object
Tool description for LLM
Human-readable display name for UI rendering (e.g., “Get Current Time” for get_current_time)
Tool name (used by LLM and for registry lookup)
JSON schema for tool parameters
Tool policy (auto or requires_approval)
Client-side tool - executed by the client, not the server
object
Tool description for LLM
Human-readable display name for UI rendering
Tool name (used by LLM and for correlation)
JSON schema for tool parameters
Timestamp when the agent was last updated.
Cumulative token usage across all sessions for this agent.
object
Number of tokens written to cache (Anthropic-specific)
Number of tokens read from cache (reduces cost)
Number of input/prompt tokens
Number of output/completion tokens
Agent created
Agent configuration for agentic loop. An agent defines the behavior and capabilities of an AI assistant.
object
Capabilities enabled for this agent with per-agent configuration. Capabilities add tools and system prompt modifications.
Per-agent capability configuration
Associates a capability with an agent, including optional per-agent configuration. The config field allows the same capability to behave differently per-agent.
object
Per-agent configuration for this capability (capability-specific)
Reference to the capability ID
Timestamp when the agent was created.
Default LLM model ID for this agent. Can be overridden at the session level.
Example
model_01933b5a00007000800000000000001Human-readable description of what the agent does.
External identifier (agent_<32-hex>). Shown as “id” in API. Client-supplied or auto-generated.
Example
agent_01933b5a000070008000000000000001Display name of the agent.
Current lifecycle status of the agent.
System prompt that defines the agent’s behavior. Sent as the first message in every conversation.
Tags for organizing and filtering agents.
Client-side tools registered for this agent. These tools are executed by the client, not the server.
Built-in tool - executed by the worker via ToolRegistry
object
Tool description for LLM
Human-readable display name for UI rendering (e.g., “Get Current Time” for get_current_time)
Tool name (used by LLM and for registry lookup)
JSON schema for tool parameters
Tool policy (auto or requires_approval)
Client-side tool - executed by the client, not the server
object
Tool description for LLM
Human-readable display name for UI rendering
Tool name (used by LLM and for correlation)
JSON schema for tool parameters
Timestamp when the agent was last updated.
Cumulative token usage across all sessions for this agent.
object
Number of tokens written to cache (Anthropic-specific)
Number of tokens read from cache (reduces cost)
Number of input/prompt tokens
Number of output/completion tokens
Invalid agent ID or input exceeds allowed limits
Standard error response for API endpoints.
object
Error message describing what went wrong.
Internal server error
Standard error response for API endpoints.
object
Error message describing what went wrong.