Skip to main content
An agent is a reusable definition of how a model works: the model, the system prompt, the tools, the skills, and the credentials it can use. You create an agent once and start any number of sessions from it. Every change to an agent’s definition creates a new agent version. A version is immutable, and a session keeps its version until you move it to another, so an edit alone never changes a session that is already running.
Creating, changing, or deleting agents needs the organization developer or admin role. The organization user role can view agents. See Organizations and roles. For the API, create a key on API keys and export it as RECURSION_API_KEY. Pick a model id from listModels: your organization can use only the models that list returns. In the API examples, replace <model-id> with a modelId returned by listModels.

​
Create an agent

One request saves the agent and its first version. Start with a short prompt and only the tools the task needs. You can add more in a later version.
  1. In the sidebar, click Agents.
  2. Click Create agent.
  3. Under Choose a starting point, click Blank, or pick a template to start from its definition.
  4. Under General, fill in Name, Model, and System prompt.
  5. Click Create agent.
Some fields, such as metadata, have no control in the console form. Set them with the API.
A 200 response is the agent, resolved to its first version. Some fields are left out here.
Keep agent_id to start sessions and latest_agent_version_id to update the agent.
You send these fields when you create an agent and when you create a new version.The API sets agent_id, latest_agent_version_id, organization_id, tags, created_at, and updated_at. Tags live outside versions, so a tag change never creates a version.
If a create request times out, you cannot tell whether the agent exists. To make the retry safe, send an Idempotency-Key header with 1 to 256 visible ASCII characters. The console adds a key to every Create agent click, so a double click or a retried save creates one agent.
The API compares the exact method, escaped path, raw query, and raw body bytes, so keep the request target and body bytes unchanged. A completed response is kept for about 24 hours. Your organization shares one key namespace across all keyed requests, so put the resource name in the key. See Idempotent mutations for the complete retry contract.

​
Update an agent

You cannot edit an agent’s definition in place. To change it, create a new version with createAgentVersion. New sessions use the new version. Running sessions keep theirs until you move them: select them on the agent’s Sessions tab in the console, or send one request for each session.
  1. Open the agent and stay on the Configuration tab.
  2. Change the fields.
  3. Click Save new version.
  4. If someone else saved first, the console shows a conflict notice. Click Load the newer version, then make your change again.
A 201 response is the agent with a new latest_agent_version_id. Use that id as base_agent_version_id in your next update. Only latest_agent_version_id is guaranteed to point at the version you just wrote, so read that version back, as in Review earlier versions, when you need its exact content.

​
Update rules

  • Send the full definition. A version is complete in itself. A field you leave out is cleared, not copied from the earlier version. This covers skills, mcp_servers, built_in_integrations, default_vault_ids, and every other field. The console sends the full definition for you.
  • Send disabled_integration_mcp_providers again. Leaving it out means an empty list, which turns every service’s MCP tools on.
  • Set base_agent_version_id to the version you read. It must equal the agent’s current latest_agent_version_id. If another writer created a version first, the API returns 409 revision_conflict and saves nothing, so you cannot overwrite a change you have not seen.
After a revision_conflict, get the agent again, apply your change to the new definition, and send the request with the new latest_agent_version_id. Branch on code, because the message text can change.

​
Find an agent

List the agents in your organization, or get one by id. The list returns every agent in one response, newest first, without pages. To filter, pass tag_ids.
  1. In the sidebar, click Agents.
  2. To narrow the list, type a name, id, model, or tag in the search box, or pick tags in the Tags filter.
  3. Click an agent. The Configuration tab shows the current version.
Each entry is a full agent. The sample shows a few fields. A get returns one agent, in the same shape as the create response, and always shows the latest version.
  • Deleted agents are left out of the list.
  • tag_ids is a comma-separated string of at most 32 tag ids. An agent must carry every tag you name. A tag_ids entry that does not exist in your organization returns 404 not_found.
  • When your organization has no agents, agents can be null; treat it as an empty list.
  • Getting a deleted agent, or one from another organization, returns 404 not_found.

​
Review earlier versions

Versions are numbered from 1. Every session reports the version it runs as agent_version_id. A session that was moved to another version did its earlier work on a different one, and its events record each move. To see the exact prompt and tools of a version, get that version.
  1. Open the agent and stay on the Configuration tab.
  2. Click the Version picker. The latest version is marked current.
  3. Pick a version to view it. Earlier versions are read-only.
  4. To make an earlier version the latest, click Restore this version. The console saves its definition as a new version.
The list returns every version, newest first, without pages:
Each entry holds the full definition at that version. The sample shows part of each entry. A get returns one entry from this list.
  • created_by is the user who saved the version and is empty when an automated caller saved it.
  • The version you get must belong to the agent in the path. A version id from another agent returns 404 not_found.

​
Tag agents

Tags are colored labels that you define once for your organization and apply to agents. Use them to filter the agent list. Tags are mutable and live outside versions: creating, applying, or removing a tag never creates an agent version, never changes the agent’s updated_at, and is not recorded on sessions.

​
Create a tag

A tag has a label, a color in #RRGGBB form, and an optional description.
  1. In the sidebar, click Agents.
  2. Click Manage tags, then Create tag.
  3. Fill in Label, Color, and an optional Description.
  4. Click Create tag.
Keep tag_id to apply the tag. A successful create returns 201 with the tag and a Location header for its get URL. The optional Idempotency-Key lets you retry the exact same request if the response is lost; a replay returns the same tag and Idempotency-Replayed: true. Reusing the key with a different request returns 409 idempotency_conflict. Without a key, check the tag list after an uncertain result before creating again.
  • label is 1 to 32 characters, and labels are unique within your organization, ignoring case. A label that another live tag already uses returns 409 conflict on label.
  • description is at most 280 characters.
  • Your organization can have at most 200 live tags.

​
List, get, update, and delete tags

listTags returns { "items": [...] } with every live tag in one response. getTag returns one tag, or 404 not_found for a deleted tag or one from another organization. updateTag is a partial update. Fields you omit keep their value, and an empty description clears it. Sending null for a field returns 400 invalid_request; omit the field instead. An empty update object {} also returns 400 invalid_request. Renaming or recoloring a tag changes it on every agent that carries it. An update returns 200 with the current tag. If its response is lost, get the tag before deciding what to do next. If the requested fields already match, the update took effect. If they differ, review the current values before sending a new update; another editor may have changed the tag.
  1. In Agents, click Manage tags.
  2. Open the tag’s row menu and click Edit, change the fields, and click Save tag.
  3. To delete, open the row menu, click Delete, and confirm in the Delete tag? dialog.
A delete returns 204 with no body, including when you repeat it for a tag already deleted in your organization. An unknown tag or one from another organization returns 404 not_found. The tag disappears from every agent at once, but the agents and their versions are not changed, and the label becomes free to reuse. A deleted tag cannot be restored.

​
Apply tags to an agent

applyAgentTag adds one tag and removeAgentTag removes one. replaceAgentTags sets the whole list in one call.
  1. Open the agent and stay on the Configuration tab.
  2. In Tags, use Add tag, or remove a tag from the list.
  3. Click Save tags. If you also changed the definition, the button reads Save changes and saves both.
applyAgentTag and replaceAgentTags return the agent’s full tag list. removeAgentTag returns 204 with no body, including when the tag was already removed.
An agent can carry at most 32 tags. applyAgentTag and removeAgentTag are both safe to repeat. In replaceAgentTags, duplicates collapse, and [] removes every tag.

​
Delete an agent

A delete is a soft delete. The agent leaves lists, returns 404 on reads, and cannot start new sessions. Its versions stay stored, and the sessions that used it stay readable. A deleted agent cannot be restored. Deleting an agent also deletes every automation that runs it, from the console or the API. The agent and its automations go together: if the delete is refused, none of them is deleted. Those automations could not run without the agent, and their triggers would go on holding their event sources. Sessions those automations already started stay readable. To keep an automation, point it at another agent before you delete this one.
  1. Open the agent, or open its row menu in Agents.
  2. Click Delete.
  3. The Delete agent dialog names the automations that will be deleted with the agent. Click Delete.

​
What can go wrong

The most common problems:
  • 409 revision_conflict on update. Someone saved a version after you read the agent. Get the agent, apply your change again, and retry. See Update rules.
  • 400 invalid_request on model. The model is not available to your organization. Copy an id from listModels; the message suggests valid ids.
  • 403 forbidden. Your role can view agents but not change them. Use an account or key with the developer or admin role.
  • 413 payload_too_large. The request body is over the size limit. Shorten the prompt, or move procedures into a skill.
Every error has required code and message fields and optional details. When present, details.field names the request field at fault. Use the generated Endpoints reference for exact alternatives and Errors for recovery guidance.
Limits on agent names, skills, apps, concurrency, tags, idempotency keys, request sizes, and rates are in Limits.

​
Next steps

Tools

See which tools an agent gets and turn some of them off.

Skills

Attach procedures that the agent loads when they apply.

Sessions

Run the agent in an environment and follow its work.

Multi-agent

Let one agent delegate to others, or lead a team.