Skip to main content
GET
Get one agent

Authorizations

Authorization
string
header
required

A Recursion API key, created in the console under API keys.

Path Parameters

agent_id
string<uuid>
required

Agent id (UUID) as returned by createAgent or listAgents.

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.

agent_id
string
required

Server-assigned id of the agent, used in the agent, agent-version, and session routes.

created_at
string<date-time>
required

Server-assigned RFC 3339 timestamp of when the agent was created.

default_credential_refs
object[] | null
required

Narrows the default vaults to individual credentials. Every credential is selected when a vault is first added, and may then be unchecked.

default_vault_ids
string[] | null
required

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.

disabled_integration_mcp_providers
string[] | null
required

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.

mcp_servers
object[] | null
required

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
string
required

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.

model_config
object
required

Default inference settings applied to every turn unless a session overrides them.

Example:
name
string
required

Human-readable label shown wherever agents are listed. Not required to be unique.

organization_id
string
required

Organization that owns the agent. Server-assigned from the caller's credentials; a value sent in a request body is ignored.

skills
object[] | null
required

Skill packages loaded into the agent's runtime, each an entry with the skill reference and its metadata.

system
string
required

System prompt prepended to every conversation this agent runs.

tags
object[]
required

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.

toolsets
object[] | null
required

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.

Maximum array length: 1
updated_at
string<date-time>
required

Server-assigned RFC 3339 timestamp of the most recent update to the agent.

built_in_integrations
object[]

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.

default_rubric
string

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.

description
string

Free-text note about what this agent is for.

latest_agent_version_id
string

Server-maintained id of the newest version of this agent; sessions started without an explicit version use it.

max_concurrent_sessions
integer

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.

Required range: 1 <= x <= 10000
metadata
object

Caller-owned key/value data stored with the agent and returned unchanged.

multiagent
object

Multi-agent orchestration settings, such as subagent definitions and delegation limits.

nativeIntegrations
object[]

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.

Maximum array length: 25
web_search_enabled
boolean
default:true

Whether new sessions may use the native web_search tool. Omitted on legacy agents and interpreted as enabled.