Update Agent

POST/v1/agents/{agent_id}

Update an agent. Each successful update that changes at least one field increments the agent's version. Existing sessions keep the version they were created with; new sessions use the latest.

Optimistic locking

You must pass the agent's current version. If it doesn't match the server's current version, the request fails with 409 conflict — re-fetch the agent and retry. This prevents concurrent overwrites.

Path Parameters

Parameter	Type	Required	Description
agent_id	string	✅	The agent ID (agent_...)

Request Parameters

Parameter	Type	Required	Description
version	integer	✅	The agent's current version (optimistic lock).
model	string | object	❌	Model identifier. Omit to preserve. Cannot be cleared.
name	string	❌	Name. 1–256 chars. Omit to preserve. Cannot be cleared.
description	string | null	❌	Omit to preserve; send empty string or null to clear.
system	string | null	❌	System prompt. Omit to preserve; send empty string or null to clear.
tools	array | null	❌	Full replacement. Omit to preserve; send [] or null to clear. Max 128.
mcp_servers	array | null	❌	Full replacement. Omit to preserve; send [] or null to clear. Max 20.
metadata	object	❌	Metadata patch. Set a key to a string to upsert, or null to delete. Omit to preserve.

Field Update Semantics

Field kind	Semantics
Scalars (model, name)	Replace. Cannot be cleared.
Nullable scalars (description, system)	Replace, or clear with "" / null.
Arrays (tools, mcp_servers)	Full replacement — the provided array becomes the new value.
metadata	Per-key patch — upsert by string value, delete by null.

Full replacement for arrays

To add a tool without losing existing ones, GET the agent, append to the tools array, and POST the complete array back.

Request Examples

Python

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-sb-YOUR_KEY",
    base_url="https://api.sandbase.ai"
)

agent = client.beta.agents.update(
    agent_id="agent_01HqR2k7...",
    version=1,
    system="You are a senior research assistant. Always cite sources."
)
print(f"New version: {agent.version}")  # 2

cURL

curl -X POST https://api.sandbase.ai/v1/agents/agent_01HqR2k7... \
  -H "Authorization: Bearer sk-sb-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 1,
    "system": "You are a senior research assistant. Always cite sources."
  }'

Response

Returns the updated Agent object with an incremented version.

{
  "id": "agent_01HqR2k7...",
  "type": "agent",
  "version": 2,
  "name": "Research Assistant",
  "description": "A general-purpose research agent.",
  "model": { "id": "claude-sonnet-4", "speed": "standard" },
  "system": "You are a senior research assistant. Always cite sources.",
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } },
      "configs": [{ "name": "bash", "enabled": true, "permission_policy": { "type": "always_allow" } }]
    }
  ],
  "mcp_servers": [],
  "metadata": {},
  "archived_at": null,
  "created_at": "2026-05-29T10:00:00Z",
  "updated_at": "2026-05-29T11:00:00Z"
}

If no field actually changed, the version is not incremented and the existing agent is returned unchanged.

Errors

Status	Type	Description
400	invalid_request	Invalid field values
401	authentication_error	Invalid or missing API key
404	not_found	Agent not found
409	conflict	version does not match the current version. Re-fetch and retry.