Update an agent

Updates the specified agent. All request fields are optional; omitted fields are left unchanged.

Merge semantics follow PATCH conventions:

• Top-level scalars (name, description) merge field-by-field — sending one does not affect the other.
• Nested objects (runtime, permissions, tools, subagents, skills, extras) are replaced in full when any of their fields is provided. To preserve existing nested values, include them in your PATCH.
• Providing any of system_prompt, tools, subagents, skills, or files triggers a new file tree commit. instructions is a deprecated alias for system_prompt and is still accepted; system_prompt wins when both are sent.

Entries under files are created or replaced by path. The call is atomic per request: if any entry fails validation, no changes are applied.

PATCH /v1/fleet/agents/{agent_id}

Error

A valid request URL is required to generate request examples

200

{
  "backend": {
    "sandbox": {
      "delete_after_stop_seconds": 1200,
      "idle_ttl_seconds": 600,
      "policy_ids": [
        "<string>"
      ]
    },
    "type": "sandbox"
  },
  "created_at": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "extras": {},
  "files": {},
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "instructions": "<string>",
  "is_owner": true,
  "name": "<string>",
  "owner_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "permissions": {
    "shared_users": {
      "read": [
        "<string>"
      ],
      "run": [
        "<string>"
      ],
      "update": [
        "<string>"
      ]
    }
  },
  "revision": "<string>",
  "runtime": {
    "model": {
      "model_id": "claude-sonnet-4-6"
    }
  },
  "skills": [
    {
      "description": "Summarise text into a paragraph.",
      "files": {},
      "instructions": "# Summarize\n\nGiven a text, produce a one-paragraph summary.",
      "name": "summarize",
      "type": "inline"
    }
  ],
  "subagents": [
    {
      "description": "Researches a topic and summarises findings.",
      "instructions": "You are a research assistant. Use the available tools to gather information.",
      "model_id": "claude-sonnet-4-6",
      "name": "researcher",
      "tools": {
        "interrupt_config": {},
        "tools": [
          {
            "display_name": "read_url_content",
            "mcp_server_name": "Fleet",
            "mcp_server_url": "https://tools.example.com",
            "name": "read_url_content"
          }
        ]
      }
    }
  ],
  "system_prompt": "<string>",
  "tools": {
    "interrupt_config": {},
    "tools": [
      {
        "display_name": "read_url_content",
        "mcp_server_name": "Fleet",
        "mcp_server_url": "https://tools.example.com",
        "name": "read_url_content"
      }
    ]
  },
  "updated_at": "2023-11-07T05:31:56Z"
}

Authorizations

API KeyTenant IDBearer Auth

X-API-Key · string · header · required

Path Parameters

agent_id · string<uuid> · required

Agent ID

Query Parameters

include_files · boolean

Echo the agent's file tree in the response

Body

application/json

backend · object

Show child attributes

configurable · object

Caller-defined key/value tracking merged into the agent's runtime configuration. Typed runtime fields win on key collision.

Show child attributes

deleted_paths · string[]

Paths to remove from the file tree. Relative paths only.

description · string

extras · object

Caller-defined key/value tracking attached to the agent's metadata.

Show child attributes

files · object

Raw file entries created or replaced by path. Triggers a new commit.

Show child attributes

instructions · string

Deprecated: use system_prompt. Accepted for backwards compatibility; system_prompt takes precedence when both are set.

name · string

permissions · object

Show child attributes

runtime · object

Show child attributes

skills · object[]

Skills. Each entry is written to skills/<name>/SKILL.md and supporting files. Triggers a new commit.

Show child attributes

subagents · object[]

Subagents. Each entry is written to subagents/<name>/AGENTS.md and subagents/<name>/tools.json. Triggers a new commit.

Show child attributes

system_prompt · string

Agent system prompt. Written to AGENTS.md. Triggers a new commit.

Example:

"You are a helpful agent. Use the available tools to answer the user's question."

tools · object

Tool config. Written to tools.json. Triggers a new commit.

Show child attributes

Response

200

application/json

OK

access_level · enum<string>

Available options: READ, RUN, WRITE

backend · object

Show child attributes

created_at · string<date-time>

description · string

extras · object

Show child attributes

files · object

Raw file map. Returned only when include_files=true.

Show child attributes

id · string<uuid>

instructions · string

Deprecated: use system_prompt. Echoed alongside system_prompt with the same value for backwards compatibility.

is_owner · boolean

name · string

owner_id · string<uuid>

permissions · object

Show child attributes

revision · string

runtime · object

Show child attributes

skills · object[]

Skills parsed from skills/<name>/SKILL.md and supporting files.

Show child attributes

subagents · object[]

Subagents parsed from subagents/<name>/AGENTS.md + subagents/<name>/tools.json.

Show child attributes

system_prompt · string

Agent system prompt parsed from AGENTS.md.

tools · object

Tool config parsed from tools.json.

Show child attributes

updated_at · string<date-time>