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 agent is a file tree. Typed fields are ergonomic shortcuts that the server renders into specific paths:

• system_prompt → AGENTS.md
• tools → tools.json
• subagents[i] → subagents/<name>/AGENTS.md (system prompt + generated frontmatter) + subagents/<name>/tools.json

Add skills through the files map: write skills/<name>/SKILL.md (plus any supporting files) for an inline skill, or a files entry with type: "skill" and a repo_handle to link a shared workspace skill.

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

Beyond the file tree, typed blocks configure the agent itself:

• model — required — the model to run, referenced by its catalog id from GET /v1/fleet/models. A built-in (default) model uses a provider:model id, e.g. {"id": "anthropic:claude-sonnet-4-6"}. A custom (workspace) model uses the workspace model id, e.g. {"id": "beeb2ec7-3311-423b-89a3-9c95a59593af"}. The server resolves the id against the catalog; an unknown id returns 422.
• display — presentation metadata (icon, icon_color).
• backend — execution backend: state (no computer, files live in LangGraph state) or sandbox (an isolated computer). For sandbox, the nested sandbox_config sets the scope (thread = one sandbox per thread, agent = one shared across threads — required) plus optional sandbox_id, snapshot_id, policy_ids, and TTLs. sandbox_config is only valid when type is sandbox. When backend (or backend.type) is omitted it defaults to the state backend, which is thread-scoped: files live in LangGraph thread state and persist across turns within a thread but are not shared across threads.
• options — behavioural flags such as trace_inputs_outputs.

tools.interrupt_config maps a tool name to its human-in-the-loop rule. Each value is either a boolean (true = require approval before the tool runs, false = run automatically) or an object { "allowed_decisions": [...], "description": "...", "args_schema": {...} } where allowed_decisions is a subset of approve, edit, reject, respond. {} means no interrupts.

Use files for paths the typed fields don’t cover. Setting both a typed field and the files entry that resolves to the same path returns 422.

Example request body:

{
"name": "researcher",
"description": "Researches topics and summarises findings.",
"permissions": {"identity": "personal", "visibility": "tenant", "tenant_access_level": "read"},
"model": {"id": "anthropic:claude-sonnet-4-6"},
"display": {"icon": "Rocket02", "icon_color": "blue"},
"backend": {"type": "sandbox", "sandbox_config": {"scope": "thread", "snapshot_id": "550e8400-e29b-41d4-a716-446655440000"}},
"options": {"trace_inputs_outputs": true, "triggers_paused": false, "skip_memory_write_protection": false, "tools_url": "https://tools.example.com/mcp", "slack_oauth_provider_id": "prov_123"},
"system_prompt": "You are a helpful research agent.",
"tools": {
"tools": [
{"name": "read_url_content", "mcp_server_url": "https://tools.example.com"}
],
"interrupt_config": {"read_url_content": true}
},
"subagents": [
{"name": "summarizer", "description": "Summarises text", "system_prompt": "You summarise text."}
],
"files": {
"skills/summarize/SKILL.md": {"type": "file", "content": "# Summarize\n\nGive a one-paragraph summary."},
"skills/shared-helper": {"type": "skill", "repo_handle": "shared-helper"}
}
}