Create a new immutable agent version
Creates a new immutable agent version from a full definition and moves the agent’s latest pointer to it, in one atomic operation. base_agent_version_id must be the agent’s current latest_agent_version_id or the request is rejected with 409 revision_conflict, so the caller can re-read and retry rather than silently racing another writer. Every field is full content, there is no partial-update or omit-to-inherit semantics, so an omitted field is cleared rather than carried over from the base version. Tags are changed only through the dedicated agent tag routes. Invalid model_config and unsupported reasoning_effort values return 400, including when the model catalog lists no exact options for the selected model; a model catalog that cannot be read to verify them returns 503. Of the response, only latest_agent_version_id is guaranteed to name the version this call minted: the other fields come from a read taken after the commit, so a concurrent writer’s content can appear beneath that id. Read the version back with getAgentVersion when the exact published content matters.
Authorizations
A Recursion API key, created in the console under API keys.
Path Parameters
Agent id (UUID) as returned by createAgent or listAgents.
Body
Request body for creating a new immutable agent version. Every field means what it means on createAgent -- full content is always required, there is no partial update -- except disabled_integration_mcp_providers, whose omission means none here rather than the new-agent default. base_agent_version_id must be the agent's current version or the request is rejected with revision_conflict so the caller can re-read and retry.
The agent's current latest_agent_version_id, as returned by getAgent. Rejected with 409 revision_conflict if the agent has moved past this version.
Model id, copied verbatim from the models catalog, GET /v1/models (e.g. anthropic/claude-sonnet-4-5). Reads return the stored form, which adds a provider prefix before that id. An id the catalog does not list is rejected with the list of ids that it does.
Human-readable label for the agent. Required.
System prompt for the agent.
Built-in integrations this agent may use, each naming an active organization connection an admin added on the Integrations page. Sessions receive short-lived access restricted to exactly those apps and each connection's tool allow-list; nothing is granted through a vault. Omit or send [] for none. Carried in full on every version write.
25Individual default items within default_vault_ids. The list is a whitelist across every default vault, not a filter within one, so it must name every item the agent should receive. Omit to select every current item; [] alongside a non-empty default_vault_ids is rejected because it would select none.
Markdown rubric that sessions started from this agent are graded against when their create request omits an outcome. Must contain at least one gradeable criterion, written as markdown list items. A session that supplies its own outcome ignores this entirely.
Vaults granted by default when a session create request omits vault_ids. default_credential_refs may narrow their items.
Optional free-text note about what the agent is for. Not sent to the model.
Native integration providers whose MCP tools sessions of this agent do not receive even though the grant is present. The grant still authenticates the provider's sandbox tools where it has any (git and gh for GitHub); the agent's own mcp_servers are never affected. Omission differs by operation: on createAgent it defaults to ["github"] (new agents use gh and git in the sandbox); on createAgentVersion it means none, as for every other field there; send [] to receive every provider's MCP tools.
Maximum number of this agent's root sessions that may run or wait on compute at once. Omit for unlimited. Sessions beyond the cap are accepted with execution_state=queued and wait until a slot frees.
1 <= x <= 10000Remote MCP servers whose tools are added to the agent's tool surface. Each entry is an object with name and url, e.g. {"name": "docs", "url": "https://example.com/mcp"}. Credentials come from the vaults granted to the session, and the discovered tool list is snapshotted at session start, so a later edit here does not change a running session.
Free-form caller-owned JSON stored with the agent and returned on reads. Not interpreted by the service and never sent to the model.
Default inference config applied to sessions started from this agent. Omit model_config or send {} to use provider defaults; null is invalid. reasoning_effort is normalized and validated for direct providers, and must exactly match the selected catalog model's supportedReasoningEfforts. An unsupported value, including any value for a catalog model that lists no exact options, returns 400; a model catalog that cannot be read to verify it returns 503.
Multiagent roster: the delegation targets this agent may hand work to, an optional advisor entry, and the interventionist posture. Snapshotted at session start; a child roster may tighten the recursion depth ceiling, never widen it.
Native connections this agent may use, with provider-enforced permission and resource restrictions. Omit or send [] for none. Stored in full on each agent version; secrets remain on the connection.
25Skill declarations made available to the agent, passed through as given and snapshotted into the session at start. Capped at the 100 skills a session can carry.
100Deprecated alias for toolsets; accepts only the bare evaluation marker.
1Only the bare {type: evaluation} marker is supported, for evaluator agents. Omit or send [] for ordinary agents; built-in sandbox tools, MCP servers, and skills do not require a toolset. The tools field is a deprecated alias.
1Whether sessions started from this agent may use the native web_search tool. Omit to enable it. The setting is snapshotted when a session starts.
Response
A configured agent: its versioned execution definition plus current mutable classification tags. Publishing the execution definition mints a new immutable AgentVersion; applying tags does not. A session records the version it ran and never snapshots tags.
A configured agent: its versioned execution definition plus current mutable classification tags. Publishing the execution definition mints a new immutable AgentVersion; applying tags does not. A session records the version it ran and never snapshots tags.
Server-assigned id of the agent, used in the agent, agent-version, and session routes.
Server-assigned RFC 3339 timestamp of when the agent was created.
Narrows the default vaults to individual credentials. Every credential is selected when a vault is first added, and may then be unchecked.
Vaults whose credentials are copied into a new session when its create request omits vault_ids. Sending an explicit empty list on the session still overrides these.
Native integration providers whose MCP tools new sessions of this agent do not receive, even though the grant is present. The grant still authenticates the provider's sandbox tools where it has any (git and gh for GitHub). Suppresses integration-derived servers only, never the agent's own mcp_servers. New agents decline github by default when the field is omitted on create (JSON null counts as omitted); send an explicit [] on create to receive every provider's MCP tools. A version write carries the list in full: omitting it publishes a version with none.
Remote MCP servers to attach. Each entry is an object with name (the label the server's tools are grouped under) and url (its http/https endpoint); any further keys are passed to the runtime unchanged. Credentials come from the vaults granted to the session, not from this entry. Tools are discovered and snapshotted at session start.
Model the agent runs on. Pass a model id exactly as the models catalog (GET /v1/models) lists it, e.g. anthropic/claude-sonnet-4-5; reads return the stored form, which adds a provider prefix before that id. An explicitly provider-qualified string such as anthropic:claude-sonnet-4-5 selects that provider directly and is left as written. An id the catalog does not list is rejected here, not at the session's first turn.
Default inference settings applied to every turn unless a session overrides them.
Human-readable label shown wherever agents are listed. Not required to be unique.
Organization that owns the agent. Server-assigned from the caller's credentials; a value sent in a request body is ignored.
Skill packages loaded into the agent's runtime, each an entry with the skill reference and its metadata.
System prompt prepended to every conversation this agent runs.
Current organization-scoped classification tags applied to this agent. Always an array. Tags are mutable catalog metadata and are deliberately absent from AgentVersion and session runtime snapshots.
The bare evaluation marker, when this is an evaluator agent. Historical stored agents may contain ignored declarations, omitted from current API responses. Built-in sandbox tools need no marker.
1Server-assigned RFC 3339 timestamp of the most recent update to the agent.
Built-in integrations this agent may use, each naming an active organization connection an admin added on the Integrations page. Sessions receive short-lived access restricted to exactly those apps and each connection's tool allow-list. Not a vault grant: nothing about these appears under credential access. A version write carries the list in full: omitting it publishes a version with none.
Markdown rubric that sessions started from this agent are graded against when their create request omits an outcome. A session that supplies its own outcome ignores this entirely. Carried in full on every version write: omitting it publishes a version with no rubric.
Free-text note about what this agent is for.
Server-maintained id of the newest version of this agent; sessions started without an explicit version use it.
Maximum number of this agent's root sessions that may run or wait on compute at once. Omit for unlimited. Sessions beyond the cap are accepted with execution_state=queued and wait until a slot frees; child/subagent sessions do not count. Carried in full on every version write: omitting it publishes a version with no cap.
1 <= x <= 10000Caller-owned key/value data stored with the agent and returned unchanged.
Multi-agent orchestration settings, such as subagent definitions and delegation limits.
Native connections this agent may use, with provider-enforced permission and resource restrictions. Omit or send [] for none. Stored in full on each agent version; secrets remain on the connection.
25Whether new sessions may use the native web_search tool. Omitted on legacy agents and interpreted as enabled.