Update Agent

POST/v1/agents/{agent_id}

Update an Agent configuration. Every effective change creates a new immutable version; a no-op returns the current version unchanged. Existing Sessions keep the version they started with. Unknown request fields are accepted and ignored.

Path parameters

stringagent_idrequired

Unique agent identifier beginning with agent_.

Request body

Optional<integer>version

Optional current Agent version for optimistic locking. When omitted, the server applies the update to the version it just loaded.

Optional<string>model

Replacement model identifier. Omit to preserve the current value.

Optional<string>name

Replacement name. Omit to preserve the current value.

Optional<string>description

Replacement description. Send an empty string to clear it; null is treated as omitted and preserves the current value.

Optional<string>system

Replacement system instructions. Send an empty string to clear them; null is treated as omitted and preserves the current value.

Optional<array · null>tools

Full replacement tool list. Send an empty array or null to clear all tools.

Optional<array · null>mcp_servers

Full replacement MCP server configuration list.

Optional<array · null>skills

Full replacement Skill list.

Optional<array · null>handoffs

Full replacement handoff configuration list.

Optional<object · null>metadata

Full replacement metadata object. Omitted metadata is preserved; null clears caller-owned metadata. Supplied metadata replaces caller-owned metadata rather than merging individual keys, while the platform-owned _sandbase namespace remains unchanged.

Optimistic locking

When version is supplied, a stale value returns 409 conflict. Fetch the current Agent, reapply the change, and retry with the latest version.

Array replacement

Array fields are not merged. Read the current agent and send the complete intended list when changing tools, MCP servers, Skills, or handoffs.

Errors

400invalid_request

One or more fields have invalid values.

401authentication_error

The API key is missing or invalid.

404not_found

The agent does not exist.

409conflict

The supplied version does not match the current agent version.

curl -X POST \
  "https://api.sandbase.ai/v1/agents/agent_01HqR2k7..." \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 1,
    "system": "Research carefully and always cite sources."
  }'

Response200 OK

{
  "id": "agent_01HqR2k7...",
  "type": "agent",
  "version": 2,
  "name": "Research Assistant",
  "description": "",
  "model": {
    "id": "anthropic/claude-sonnet-5",
    "effort": {
      "type": "high"
    },
    "speed": "standard"
  },
  "system": "Research carefully and always cite sources.",
  "tools": [
    {
      "type": "agent_toolset_20260401"
    }
  ],
  "mcp_servers": null,
  "skills": null,
  "handoffs": null,
  "metadata": null,
  "created_at": "2026-05-29T10:00:00Z",
  "updated_at": "2026-05-29T11:00:00Z",
  "archived_at": null
}