Sign in

v48

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

Create an agent

Creates an agent with the given metadata, runtime configuration, and optional file tree. Returns the agent's identity, ownership, and a revision token identifying the initial file tree. Creation is atomic — either the agent is fully created or no state is persisted.

The file tree is built from typed fields:

  • system_prompt → AGENTS.md (instructions is a deprecated alias; system_prompt wins when both are sent)
  • tools → tools.json
  • subagents[i] → subagents/<name>/AGENTS.md + subagents/<name>/tools.json
  • skills[i] → skills/<name>/SKILL.md + supporting files

All file paths in skills[i].files and the top-level files map must be relative — no leading /, no .. segments.

extras is an arbitrary key/value map for caller-defined tracking attached to the agent's metadata.

Use files for paths the typed fields don't cover. Setting both a typed field and the corresponding files entry returns 422.

post/v1/fleet/agents

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.

descriptionstring
extrasobject

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

filesobject

Raw file map for paths the typed fields don't cover. Setting a typed field and the corresponding files entry returns 422.

instructionsstring

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

namestring required
system_promptstring

Agent system prompt. Written to AGENTS.md.

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

Created

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"
      }
    ]
  }
}