Sign in

v48

latestOpenAPI 3.1.0raw.githubusercontent.com2026-05-275867561.6 MB
agents

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}

Path parameters

agent_idstring uuid required

Agent ID

Query parameters

include_filesboolean

Echo the agent's file tree in the response

Request body

configurableobject

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

deleted_pathsstring[]

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

descriptionstring
extrasobject

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

filesobject

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

instructionsstring

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

namestring
system_promptstring

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

Example request

{
  "backend": {
    "sandbox": {
      "delete_after_stop_seconds": 1200,
      "idle_ttl_seconds": 600,
      "snapshot_id": "550e8400-e29b-41d4-a716-446655440000"
    },
    "type": "thread_scoped_sandbox"
  },
  "runtime": {
    "model": {
      "model_id": "claude-sonnet-4-6"
    }
  },
  "skills": [
    {
      "description": "Summarise text into a paragraph.",
      "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": {
        "tools": [
          {
            "display_name": "read_url_content",
            "mcp_server_name": "Fleet",
            "mcp_server_url": "https://tools.example.com",
            "name": "read_url_content"
          }
        ]
      }
    }
  ],
  "system_prompt": "You are a helpful agent. Use the available tools to answer the user's question.",
  "tools": {
    "tools": [
      {
        "display_name": "read_url_content",
        "mcp_server_name": "Fleet",
        "mcp_server_url": "https://tools.example.com",
        "name": "read_url_content"
      }
    ]
  }
}

Response

OK

access_level'READ' | 'RUN' | 'WRITE'
created_atstring date-time
descriptionstring
extrasobject
filesobject

Raw file map. Returned only when include_files=true.

idstring uuid
instructionsstring

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

is_ownerboolean
namestring
owner_idstring uuid
revisionstring
system_promptstring

Agent system prompt parsed from AGENTS.md.

updated_atstring date-time

Example response

{
  "backend": {
    "sandbox": {
      "delete_after_stop_seconds": 1200,
      "idle_ttl_seconds": 600,
      "snapshot_id": "550e8400-e29b-41d4-a716-446655440000"
    },
    "type": "thread_scoped_sandbox"
  },
  "runtime": {
    "model": {
      "model_id": "claude-sonnet-4-6"
    }
  },
  "skills": [
    {
      "description": "Summarise text into a paragraph.",
      "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": {
        "tools": [
          {
            "display_name": "read_url_content",
            "mcp_server_name": "Fleet",
            "mcp_server_url": "https://tools.example.com",
            "name": "read_url_content"
          }
        ]
      }
    }
  ],
  "tools": {
    "tools": [
      {
        "display_name": "read_url_content",
        "mcp_server_name": "Fleet",
        "mcp_server_url": "https://tools.example.com",
        "name": "read_url_content"
      }
    ]
  }
}