Replace Agent (CAS)

PATCH/v1/agents/{agent_id}

Product update with compare-and-set. row_version is required and must equal the current value, otherwise 409. Supplied fields replace saved values; explicit null values return 400. Use this form when several editors can change the same Agent.

Path parameters

stringagent_idrequired

Agent ID (agt_ prefix).

Headers

Optional<string>Idempotency-Key

Optional. When omitted the service generates one, so a retried request can create a duplicate. Send your own stable key for retries.

Request body

row_version plus any subset of the Agent fields.

integerrow_versionrequired

The row_version you last read. A stale value returns 409.

Optional<string>model

Model ID from the Models API, up to 200 characters.

Optional<string>name

Display name, up to 128 characters.

Optional<string>instructions

System instructions, up to 256 KiB.

Optional<string>runtime_profile

Execution runtime: codex (default), claude, or mcode.

Optional<array>skills

Skill references: {"skill_id": "skl_…", "version": null | "<version>"}. null uses the Skill default version, resolved when a Session starts.

Optional<array>mcp_connections

MCP references: {connection_id, server_label, allowed_tools, required}. Up to 32; server_label must be unique in the Agent.

Optional<array>tools

Up to 64 function tools plus at most one web_search tool. Sessions currently require web_search mode disabled, and client-side function results are not supported yet.

Optional<object>text

format.type text or json_schema (with an object schema); verbosity low, medium, or high.

Optional<object>reasoning

effort none, minimal, low, medium, high, xhigh, or max; summary concise, detailed, or auto.

Optional<string>service_tier

auto (default), default, flex, priority, or fast.

Optional<object>metadata

Up to 16 string pairs; keys up to 64 and values up to 512 characters.

Optional<string>description

Up to 4096 characters.

Optional<string>note

Change note recorded on the new version.

curl -X PATCH https://api.sandbase.ai/v1/agents/agt_8c1f2b9e-3d4a-4f6b-9c2e-1a7d5e3b4c60 \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "row_version": 2,
    "description": "Research Agent used by the weekly brief.",
    "note": "Add description"
  }'

Response200 OK

{
  "id": "agt_8c1f2b9e-3d4a-4f6b-9c2e-1a7d5e3b4c60",
  "object": "agent",
  "name": "Research assistant",
  "model": "deepseek/deepseek-v4-flash",
  "instructions": "Answer with cited sources.",
  "tools": [],
  "text": {
    "format": {
      "type": "text"
    },
    "verbosity": "medium"
  },
  "reasoning": {
    "effort": null,
    "summary": null
  },
  "service_tier": "auto",
  "multi_agent": {
    "enabled": false,
    "max_concurrent_subagents": null
  },
  "visibility": "private",
  "status": "active",
  "version": 3,
  "row_version": 3,
  "projection_status": "ready",
  "runtime_profile": "codex",
  "description": "Research Agent used by the weekly brief.",
  "metadata": {
    "team": "research"
  },
  "mcp_connections": [],
  "skills": [],
  "created_at": 1791273600,
  "updated_at": 1791273600,
  "archived_at": null
}