> ## Documentation Index > Fetch the complete documentation index at: https://docs.labelbox.com/llms.txt > Use this file to discover all available pages before exploring further. # Agents > Create an agent, publish immutable versions of it, tag it, and delete it. 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](/recursion/sessions) from it. Every change to an agent's definition creates a new agent version. A version is immutable, and a session keeps the version it started with, so an edit 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](/recursion/organizations-and-roles). For the API, create a key on [API keys](/recursion/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 `` 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. ```bash theme={"theme":"css-variables"} curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/agents' \ -H "Authorization: Bearer $RECURSION_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "name": "Release notes writer", "description": "Drafts release notes from merged pull requests.", "model": "", "system": "You write release notes. Read the merged pull requests, group the changes by product area, and write one plain sentence for each change." }' ``` A `200` response is the agent, resolved to its first version. Some fields are left out here. ```json theme={"theme":"css-variables"} { "agent_id": "5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55", "latest_agent_version_id": "c1a94e07-2f6b-4d18-b3a5-0e7d8c6f4a21", "organization_id": "org_01a08a705220724f9a2fe1bcd8638c9d", "name": "Release notes writer", "description": "Drafts release notes from merged pull requests.", "system": "You write release notes. Read the merged pull requests, group the changes by product area, and write one plain sentence for each change.", "web_search_enabled": true, "mcp_servers": [], "skills": [], "default_vault_ids": [], "default_credential_refs": [], "disabled_integration_mcp_providers": [], "tags": [], "created_at": "2026-09-17T09:12:44Z", "updated_at": "2026-09-17T09:12:44Z" } ``` Keep `agent_id` to [start sessions](/recursion/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. | Field | Description | | - | - | | `name` | Required. The label shown in lists, at most 256 characters. | | `model` | Required. A model id from `listModels`. | | `system` | Required. The system prompt added to every conversation. | | `description` | A note for people. The model never sees it. | | `web_search_enabled` | Whether sessions get the `web_search` tool. Defaults to `true`. See [Tools](/recursion/tools). | | `mcp_servers` | Remote [MCP servers](/recursion/mcp-servers) the agent can call, each as `{ "name", "url" }`. | | `skills` | [Skills](/recursion/skills) and skill groups, at most 100 entries. | | `built_in_integrations` | Apps the agent may use, each as `{ "connection_id" }` naming an active connection from [Integrations](/recursion/integrations). At most 25. Sessions get each app's tool allow-list. See [Grant apps to an agent](/recursion/integrations#grant-apps-to-an-agent). | | `default_vault_ids` | [Vaults](/recursion/vaults) a session receives when its start request names none. Each vault must exist. | | `multiagent` | The agents this agent can delegate to, or the team it leads. See [Multi-agent](/recursion/multi-agent) and [Teams](/recursion/teams). | | `metadata` | Your own JSON object. The API returns it unchanged. | | `model_config` | Inference settings for every turn: `max_tokens`, `temperature`, `top_p`, `reasoning_effort`, and `provider_params`. Send `{}` or omit the field for the model's defaults. `null` is rejected. `reasoning_effort` must be one of the model's `supportedReasoningEfforts` from `listModels`. | | `default_credential_refs` | The credentials from the default vaults that the agent receives. Name every credential the agent should get, across all its default vaults. If you omit it, the API selects every credential those vaults hold when you save the agent and stores that selection with the version. A credential added to the vault later does not reach the agent until you save the agent again with it selected. An empty list with a non-empty `default_vault_ids` is rejected. | | `disabled_integration_mcp_providers` | Native integration providers whose MCP tools sessions do not receive, such as `github` or `jira`. It doesn't affect built-in integrations. On a new agent it defaults to an empty list, so sessions get the MCP tools of every connection the agent is granted. See [Tools](/recursion/tools#withhold-integration-tools). | | `max_concurrent_sessions` | From 1 to 10000. Sessions over the cap wait with `execution_state` `queued`. Subagent sessions do not count. The current value on the agent applies, not the value in a session's version. | The API sets `agent_id`, `latest_agent_version_id`, `organization_id`, `tags`, `created_at`, and `updated_at`. [Tags](#tag-agents) 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. ```bash theme={"theme":"css-variables"} curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/agents' \ -H "Authorization: Bearer $RECURSION_API_KEY" \ -H 'Idempotency-Key: release-notes-writer-2026-09-17' \ -H 'Content-Type: application/json' \ -d '{"name":"Release notes writer","model":"","system":"You write release notes."}' ``` | You send | Result | | - | - | | The same key and the same request | The original response. No second agent is created. | | The same key with any different request identity bytes | `409 idempotency_conflict` | | The same key while the first request still runs | `409 idempotency_in_progress`. Wait for the time in `Retry-After`, then retry. | 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](/recursion/api#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 the version they started with. 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. ```bash theme={"theme":"css-variables"} curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/agents/5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55/versions' \ -H "Authorization: Bearer $RECURSION_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "base_agent_version_id": "c1a94e07-2f6b-4d18-b3a5-0e7d8c6f4a21", "name": "Release notes writer", "model": "", "system": "You write release notes. Group the changes by product area. Put breaking changes first.", "disabled_integration_mcp_providers": ["jira"] }' ``` 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](#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. ```json theme={"theme":"css-variables"} { "code": "revision_conflict", "message": "source revision conflict: base_agent_version_id is not the agent's current version", "details": { "field": "base_agent_version_id", "requestId": "0b6f2c1d9a4e4b7f8c3d5e6a7b8c9d0e", "retryable": false } } ``` ## 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. ```bash theme={"theme":"css-variables"} curl 'https://api.recursion.labelbox.com/managed-agents/v1/agents?tag_ids=a41d7c02-5e9b-4f36-8a10-2b7c9d3e6f08' \ -H "Authorization: Bearer $RECURSION_API_KEY" ``` ```bash theme={"theme":"css-variables"} curl 'https://api.recursion.labelbox.com/managed-agents/v1/agents/5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55' \ -H "Authorization: Bearer $RECURSION_API_KEY" ``` ```json theme={"theme":"css-variables"} { "agents": [ { "agent_id": "5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55", "latest_agent_version_id": "c1a94e07-2f6b-4d18-b3a5-0e7d8c6f4a21", "name": "Release notes writer", "tags": [ { "tag_id": "a41d7c02-5e9b-4f36-8a10-2b7c9d3e6f08", "label": "release", "color": "#2F80ED" } ] } ] } ``` 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 records its `agent_version_id`. To see the exact prompt and tools a past session ran with, 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. ```bash theme={"theme":"css-variables"} curl 'https://api.recursion.labelbox.com/managed-agents/v1/agents/5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55/versions' \ -H "Authorization: Bearer $RECURSION_API_KEY" ``` ```bash theme={"theme":"css-variables"} curl 'https://api.recursion.labelbox.com/managed-agents/v1/agents/5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55/versions/c1a94e07-2f6b-4d18-b3a5-0e7d8c6f4a21' \ -H "Authorization: Bearer $RECURSION_API_KEY" ``` The list returns every version, newest first, without pages: ```json theme={"theme":"css-variables"} { "agent_versions": [ { "agent_version_id": "e82b5d19-7c40-4a6f-91d3-3f5a2c8b0e64", "agent_id": "5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55", "version_number": 2, "name": "Release notes writer", "system": "You write release notes. Group the changes by product area. Put breaking changes first.", "created_by": "usr_01a0867d1b0875be9f9a9938ffb90971", "created_at": "2026-09-17T10:03:12Z" }, { "agent_version_id": "c1a94e07-2f6b-4d18-b3a5-0e7d8c6f4a21", "agent_id": "5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55", "version_number": 1, "name": "Release notes writer", "system": "You write release notes. Read the merged pull requests, group the changes by product area, and write one plain sentence for each change.", "created_at": "2026-09-17T09:12:44Z" } ] } ``` 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**. ```bash theme={"theme":"css-variables"} curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/tags' \ -H "Authorization: Bearer $RECURSION_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"label":"release","color":"#2F80ED","description":"Agents that ship release work."}' ``` ```json theme={"theme":"css-variables"} { "organization_id": "org_01a08a705220724f9a2fe1bcd8638c9d", "tag_id": "a41d7c02-5e9b-4f36-8a10-2b7c9d3e6f08", "label": "release", "color": "#2F80ED", "description": "Agents that ship release work.", "created_at": "2026-09-17T09:20:05Z", "updated_at": "2026-09-17T09:20:05Z" } ``` Keep `tag_id` to apply the tag. * `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. ### 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. ```bash theme={"theme":"css-variables"} curl -X PUT 'https://api.recursion.labelbox.com/managed-agents/v1/agents/5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55/tags/a41d7c02-5e9b-4f36-8a10-2b7c9d3e6f08' \ -H "Authorization: Bearer $RECURSION_API_KEY" curl -X PUT 'https://api.recursion.labelbox.com/managed-agents/v1/agents/5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55/tags' \ -H "Authorization: Bearer $RECURSION_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"tag_ids":["a41d7c02-5e9b-4f36-8a10-2b7c9d3e6f08","d93b6e20-4c17-4a85-b2f9-7e1a0c5d8f36"]}' curl -X DELETE 'https://api.recursion.labelbox.com/managed-agents/v1/agents/5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55/tags/d93b6e20-4c17-4a85-b2f9-7e1a0c5d8f36' \ -H "Authorization: Bearer $RECURSION_API_KEY" ``` `applyAgentTag` and `replaceAgentTags` return the agent's full tag list. `removeAgentTag` returns `204` with no body, including when the tag was already removed. ```json theme={"theme":"css-variables"} { "tags": [ { "organization_id": "org_01a08a705220724f9a2fe1bcd8638c9d", "tag_id": "a41d7c02-5e9b-4f36-8a10-2b7c9d3e6f08", "label": "release", "color": "#2F80ED", "description": "Agents that ship release work.", "created_at": "2026-09-17T09:20:05Z", "updated_at": "2026-09-17T09:20:05Z" } ] } ``` An agent can carry at most 32 tags. `applyAgentTag` and `removeAgentTag` are both safe to repeat. In `replaceAgentTags`, duplicates collapse, and `[]` removes every tag. `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. Renaming or recoloring a tag changes it on every agent that carries it. In the console: 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. With the API: ```bash theme={"theme":"css-variables"} curl -X PATCH 'https://api.recursion.labelbox.com/managed-agents/v1/tags/a41d7c02-5e9b-4f36-8a10-2b7c9d3e6f08' \ -H "Authorization: Bearer $RECURSION_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"color":"#27AE60"}' curl -X DELETE 'https://api.recursion.labelbox.com/managed-agents/v1/tags/a41d7c02-5e9b-4f36-8a10-2b7c9d3e6f08' \ -H "Authorization: Bearer $RECURSION_API_KEY" ``` A delete returns `{ "deleted": true }`. 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. ## 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. 1. Open the agent, or open its row menu in **Agents**. 2. Click **Delete**. 3. In the **Delete agent** dialog, click **Delete**. ```bash theme={"theme":"css-variables"} curl -X DELETE 'https://api.recursion.labelbox.com/managed-agents/v1/agents/5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55' \ -H "Authorization: Bearer $RECURSION_API_KEY" ``` ```json theme={"theme":"css-variables"} { "deleted": true } ``` ## 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](#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](/recursion/skills). 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](/recursion/errors) for recovery guidance. | Symptom or code | Cause | Fix | | - | - | - | | `400 invalid_request` on `name`, `system`, or `max_concurrent_sessions` | A required field is missing, `name` is over 256 characters, or `max_concurrent_sessions` is outside 1 to 10000. | Read `details.field` and `message`, then correct the value. | | `400 invalid_request` on `model` | The model is not available to your organization. | Copy an id from `listModels`. The `message` suggests valid ids. | | `400 invalid_request` on `model_config` | `model_config` is `null`, or `reasoning_effort` is not one the model supports. | Send `{}` for defaults, and pick a value from the model's `supportedReasoningEfforts`. | | `400 invalid_request` on `disabled_integration_mcp_providers` | The list names an unsupported provider. | Use only the values listed in [Tools](/recursion/tools#withhold-integration-tools). | | `400 invalid_request` on `built_in_integrations` | More than 25 entries, a non-empty `tools`, or a connection that isn't an active built-in integration with at least one tool. | Read `message`. See [Grant apps to an agent](/recursion/integrations#grant-apps-to-an-agent). | | `400 invalid_request` on `skills[n].skill_id`, `skills[n].version`, or `skills[n].skill_group_id` | An attached skill, skill version, or skill group does not exist, is deleted, or belongs to another organization. | Check the id in that entry. See [Attach skills to an agent](/recursion/skills#attach-skills-to-an-agent). | | `400 invalid_request` on `tags`, `tag_id`, or `tag_ids` | Your organization already has 200 tags, an agent would carry more than 32, or `tag_ids` holds an empty id. | Delete unused tags, or remove tags from the agent. | | `400 invalid_json` | The body is not valid JSON, or a field has the wrong type. | Correct the body. `details.field` names the field when the type is wrong. | | `401 unauthorized` | The API key is missing, revoked, or expired. | Send a valid key. See [API keys](/recursion/api-keys). | | `403 forbidden` | Your role can view agents but not change them. | See [Organizations and roles](/recursion/organizations-and-roles). Use an account or key with the developer or admin role. | | `404 not_found` | The agent, version, tag, default vault, or granted integration connection does not exist, is deleted, or belongs to another organization. | Check the id. The API does not say which case applies. | | `409 conflict` on `label` | Another live tag uses the same label, ignoring case. | Pick another label, or reuse the existing tag. | | `409 revision_conflict` | `base_agent_version_id` is not the latest version. | Get the agent, apply your change again, and retry. | | `409 idempotency_conflict` | You reused an `Idempotency-Key` with a different request. | Use a new key for a new request. | | `409 idempotency_in_progress` | The first request with this key is still running. | Wait for the time in `Retry-After`, then retry. | | `413 payload_too_large` | The request body is over the size limit. | Shorten the prompt, or move procedures into a [skill](/recursion/skills). | | `429 rate_limit_exceeded` | Your organization is over its request rate. | Retry after `Retry-After` only when [the operation's retry contract permits it](/recursion/api#rate-limits). | | `503 idempotency_unavailable` | The API could not read or reserve the key, so the request did not run. | Retry with the same key and request bytes. | | `503 managed_agents_unavailable` | The service could not check the model or complete the request. | Retry only when `details.retryable` is not `false` and the operation's retry contract permits it. | Limits on agent names, skills, apps, concurrency, tags, idempotency keys, request sizes, and rates are in [Limits](/recursion/limits). ## Next steps See which tools an agent gets and turn some of them off. Attach procedures that the agent loads when they apply. Run the agent in an environment and follow its work. Let one agent delegate to others, or lead a team.