Update Agent

POST/v1/agents/{agent_id}

SDK-style partial update. Supplied fields replace the saved values and create a new version; omitted fields keep their values. No row_version is needed. description and note are not accepted here; use Replace (PATCH) for them. Archived Agents return 404.

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

Any subset of these fields. Other fields return 400.

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>"}. Up to 32. On a new binding, null pins the current default when the Agent is saved. For an existing binding, null preserves its pinned version; supply an explicit version to upgrade.

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.

curl -X POST https://api.sandbase.ai/v1/agents/agt_8c1f2b9e-3d4a-4f6b-9c2e-1a7d5e3b4c60 \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Answer in five bullet points with cited sources."
  }'

Response200 OK

{
  "id": "agt_8c1f2b9e-3d4a-4f6b-9c2e-1a7d5e3b4c60",
  "object": "agent",
  "name": "Research assistant",
  "model": "deepseek/deepseek-v4-flash",
  "instructions": "Answer in five bullet points 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": 2,
  "row_version": 2,
  "projection_status": "ready",
  "runtime_profile": "codex",
  "description": "",
  "metadata": {
    "team": "research"
  },
  "mcp_connections": [],
  "skills": [],
  "created_at": 1791273600,
  "updated_at": 1791273600,
  "archived_at": null
}