> ## Documentation Index > Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-fjmorr-1782499519-e1e0dbe.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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//AGENTS.md` (system prompt + generated frontmatter) + `subagents//tools.json` Add skills through the `files` map: write `skills//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: ```json { "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"} } } ``` ## OpenAPI ````yaml /langsmith/headless-fleet-openapi.json post /v1/fleet/agents openapi: 3.0.0 info: contact: {} description: > The Fleet API is a headless interface for building and running agents — create and configure agents, manage their connections and secrets, run threads, and wire up triggers. Paths are service-native (e.g. `/v1/fleet/agents`). Self-hosted deployments reach them through the gateway under an `/api` prefix (e.g. `/api/v1/fleet/agents`). ## Authentication Every request must carry **one** credential: | Scheme | Header | Value | | --- | --- | --- | | API key | `X-Api-Key` | A LangSmith API key (`lsv2_…`). | | Session token | `Authorization` | `Bearer `. | Workspace-scoped endpoints additionally require **`X-Tenant-Id`**, set to the workspace (tenant) UUID the request operates in. Organization- and identity-scoped endpoints omit it. ## Errors Errors follow [RFC 7807](https://www.rfc-editor.org/rfc/rfc7807) (Problem Details) and use one JSON shape across every endpoint: ```json { "type": "about:blank", "code": "agent_not_found", "detail": "No agent exists with that ID.", "status": 404 } ``` - `type` — URI identifying the error type. Currently always `about:blank` (the RFC 7807 default); branch on `code`, not `type`. - `code` — stable, machine-readable identifier. Branch on this rather than matching `detail`. - `detail` — human-readable explanation. Proxied endpoints also echo it as `message`. - `status` — mirrors the HTTP status code. | Status | Meaning | | --- | --- | | `400` | Malformed request or failed validation. | | `401` | Missing or invalid credentials. | | `403` | Authenticated, but not permitted to access this resource. | | `404` | The resource does not exist or is not visible to your workspace. | | `409` | Conflicts with current state (e.g. a duplicate). | | `422` | Well-formed but semantically invalid. | | `500` | Unexpected server error. | | `502` / `503` | An upstream dependency failed or was unavailable. Retries are usually safe. | ## Pagination List endpoints return a fixed-size page and an opaque cursor: ```json { "items": [ ], "next_cursor": "eyJ…" } ``` - `page_size` — items per page, `1`–`100` (default `20`). - `cursor` — pass the previous response's `next_cursor` to fetch the next page. An absent or empty `next_cursor` means there are no more results. Cursors are opaque — don't construct or parse them. title: Fleet API version: v1 servers: - url: / security: [] tags: - name: agents - name: agent connections - name: threads - name: skills - name: auth - name: integrations - name: secrets - name: models - name: tenants - name: users paths: /v1/fleet/agents: post: tags: - agents summary: Create an agent description: >- 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//AGENTS.md` (system prompt + generated frontmatter) + `subagents//tools.json` Add skills through the `files` map: write `skills//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: ```json { "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"} } } ``` parameters: - description: >- Comma-separated relations to hydrate: `owner` (resolve `owner_id` into an `owner` object) and/or `files` (raw file map). The legacy `include_files=true` boolean is a deprecated alias for `include=files`. name: include in: query schema: type: string enum: - owner - files requestBody: content: application/json: schema: $ref: '#/components/schemas/agents.CreateAgentRequest' description: Agent metadata, runtime, and optional file tree required: true responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/agents.Agent' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/agents.ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/agents.ErrorResponse' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/agents.ErrorResponse' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/agents.ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/agents.ErrorResponse' '502': description: Bad Gateway content: application/json: schema: $ref: '#/components/schemas/agents.ErrorResponse' '503': description: Service Unavailable content: application/json: schema: $ref: '#/components/schemas/agents.ErrorResponse' security: - API_Key: [] - Tenant_ID: [] - Bearer_Auth: [] components: schemas: agents.CreateAgentRequest: type: object required: - name properties: backend: $ref: '#/components/schemas/agents.AgentBackend' configurable: description: |- Caller-defined key/value tracking merged into the agent's runtime configuration. Typed runtime fields win on key collision. type: object additionalProperties: {} description: type: string display: $ref: '#/components/schemas/agents.AgentDisplay' extras: description: >- Deprecated: metadata is fully typed via `permissions` and `display`. Caller-defined key/value tracking attached to the agent's metadata. Sunset tracked in AB-2553: https://linear.app/langchain/issue/AB-2553 type: object additionalProperties: {} files: description: |- Raw file map for paths the typed fields don't cover. Setting a typed field and the corresponding `files` entry returns 422. type: object additionalProperties: $ref: '#/components/schemas/agents.FileEntry' model: $ref: '#/components/schemas/agents.AgentModel' name: type: string options: $ref: '#/components/schemas/agents.AgentOptions' permissions: description: |- Sharing settings. When omitted, the agent is private to its creator (identity `personal`, visibility `user`). allOf: - $ref: '#/components/schemas/agents.AgentPermissions' subagents: description: >- Subagents. Each entry is written to `subagents//AGENTS.md` and `subagents//tools.json`. type: array items: $ref: '#/components/schemas/agents.SubagentSpec' system_prompt: description: Agent system prompt. Written to `AGENTS.md`. type: string example: >- You are a helpful agent. Use the available tools to answer the user's question. tools: description: Tool config. Written to `tools.json`. allOf: - $ref: '#/components/schemas/agents.ToolsConfig' agents.Agent: type: object properties: access_level: description: The caller's access level on this agent. type: string enum: - READ - RUN - WRITE example: WRITE backend: $ref: '#/components/schemas/agents.AgentBackend' created_at: type: string format: date-time example: '2026-01-15T09:30:00Z' description: type: string example: Researches topics and drafts summaries. display: $ref: '#/components/schemas/agents.AgentDisplay' extras: type: object additionalProperties: {} files: description: Raw file map. Returned only when `include_files=true`. type: object additionalProperties: $ref: '#/components/schemas/agents.FileEntry' id: type: string format: uuid example: 11111111-1111-1111-1111-111111111111 instructions: description: >- Deprecated: use `system_prompt`. Echoed alongside `system_prompt` with the same value for backwards compatibility. type: string is_owner: description: True when the caller owns this agent. type: boolean example: true model: $ref: '#/components/schemas/agents.AgentModel' name: type: string example: Research Assistant options: $ref: '#/components/schemas/agents.AgentOptions' owner: $ref: '#/components/schemas/users.UserRef' owner_id: type: string format: uuid example: 7f8e9d0c-1b2a-3948-5766-8594a3b2c1d0 permissions: $ref: '#/components/schemas/agents.AgentPermissions' revision: description: Opaque identifier for the agent's current revision. type: string example: rev_3f9a2b1c subagents: description: >- Subagents parsed from `subagents//AGENTS.md` + `subagents//tools.json`. type: array items: $ref: '#/components/schemas/agents.SubagentSpec' system_prompt: description: Agent system prompt parsed from `AGENTS.md`. type: string example: You are a helpful research assistant. tools: description: Tool config parsed from `tools.json`. allOf: - $ref: '#/components/schemas/agents.ToolsConfig' updated_at: type: string format: date-time example: '2026-01-15T09:30:00Z' agents.ErrorResponse: type: object properties: code: type: string detail: type: string status: type: integer type: type: string agents.AgentBackend: type: object properties: sandbox_config: description: >- Sandbox configuration. Required when `type` is `sandbox`, rejected otherwise. allOf: - $ref: '#/components/schemas/agents.SandboxConfig' type: description: >- Execution backend. Defaults to `state` when omitted (along with the whole `backend` object). `state` runs without a sandbox: files live in LangGraph thread state, which is thread-scoped — they persist across turns within a thread but are not shared across threads. `sandbox` provisions an isolated computer. type: string enum: - state - sandbox example: sandbox agents.AgentDisplay: type: object properties: icon: type: string example: Rocket02 icon_color: type: string example: blue agents.FileEntry: type: object properties: commit_id: description: >- Optional pin to a specific skill commit (`type=skill` only). Defaults to the repo's latest commit. type: string content: description: >- File contents as a UTF-8 string. Required for `file` entries; must be empty for `skill` entries. type: string example: |- # AGENTS.md You are a helpful agent. repo_handle: description: >- Workspace skill repo handle. Required when `type=skill`, otherwise empty. type: string example: summarizer type: description: >- Entry kind. `file` (default) carries inline `content`; `skill` links a shared workspace skill repo via `repo_handle`. type: string enum: - file - skill example: file agents.AgentModel: type: object properties: id: description: >- Model id from GET /v1/fleet/models. Built-in ids are `provider:model` (e.g. anthropic:claude-sonnet-4-6); workspace (custom) models use the workspace model id. type: string example: anthropic:claude-sonnet-4-6 agents.AgentOptions: type: object properties: skip_memory_write_protection: description: >- Internal. Disables the human approval interrupt before memory writes. type: boolean x-internal: true slack_oauth_provider_id: description: Internal. Slack OAuth provider the agent posts replies as. type: string x-internal: true tools_url: description: >- Internal. MCP tool server the agent connects to; defaults to the platform server when empty. type: string x-internal: true trace_inputs_outputs: description: Whether the agent records run inputs/outputs to its tracing project. type: boolean triggers_paused: description: Internal. Not needed. type: boolean x-internal: true user_timezone: description: >- Default IANA timezone for runs that don't supply one (e.g. trigger-fired runs with no browser). Interactive runs inject the live timezone per-run and override this. Defaults to UTC on create when omitted. type: string example: America/New_York agents.AgentPermissions: type: object properties: identity: type: string enum: - personal - shared shared_users: $ref: '#/components/schemas/agents.SharedUsers' tenant_access_level: type: string enum: - read - run - write visibility: type: string enum: - tenant - user agents.SubagentSpec: type: object properties: description: description: Short human-readable description. type: string example: Researches a topic and summarises findings. instructions: description: >- Deprecated: use `system_prompt`. Accepted for backwards compatibility; `system_prompt` takes precedence when both are set. type: string model: description: >- Model for this subagent. Inherits the parent agent's model when omitted. allOf: - $ref: '#/components/schemas/agents.AgentModel' name: description: Subagent slug. Becomes `subagents//AGENTS.md`. type: string example: researcher system_prompt: description: Subagent system prompt. Written to `subagents//AGENTS.md`. type: string example: >- You are a research assistant. Use the available tools to gather information. tools: description: Subagent tool config. Written to `subagents//tools.json`. allOf: - $ref: '#/components/schemas/agents.ToolsConfig' agents.ToolsConfig: type: object properties: interrupt_config: description: >- Per-tool interrupt rules keyed by tool name. Each value is `true`/`false` (require approval or not) or an object (see InterruptOnConfig). `{}` = no interrupts. type: object additionalProperties: $ref: '#/components/schemas/agents.InterruptRule' tools: description: MCP tools available to the agent. Serialised to `tools.json`. type: array items: $ref: '#/components/schemas/agents.ToolSpec' users.UserRef: type: object properties: id: type: string format: uuid name: type: string example: Ada Lovelace agents.SandboxConfig: type: object properties: delete_after_stop_seconds: description: Time after a sandbox is stopped before it is deleted, in seconds. type: integer example: 1200 idle_ttl_seconds: description: Idle timeout after which an unused sandbox is paused, in seconds. type: integer example: 600 policy_ids: description: Sandbox policies governing tool execution. type: array items: type: string sandbox_id: description: Pinned sandbox instance the agent reuses across runs. type: string scope: description: >- Sandbox lifecycle. `thread` gives each thread its own sandbox; `agent` shares one sandbox across all of the agent's threads. Required when `backend.type` is `sandbox`. type: string enum: - thread - agent example: thread snapshot_id: description: Snapshot used when creating new sandbox-backed computers. type: string example: 550e8400-e29b-41d4-a716-446655440000 agents.SharedUsers: type: object properties: read: description: User IDs allowed to read the agent. type: array items: type: string run: description: User IDs allowed to run the agent. type: array items: type: string update: description: User IDs allowed to update the agent. type: array items: type: string agents.InterruptRule: type: object agents.ToolSpec: type: object properties: display_name: description: Display name for the tool. Defaults to the tool name when empty. type: string example: read_url_content mcp_server_name: description: Display name for the MCP server. Defaults to the URL when empty. type: string example: Fleet mcp_server_url: description: URL of the MCP server hosting this tool. type: string example: https://tools.example.com name: description: Tool name as exposed by the MCP server. type: string example: read_url_content securitySchemes: API_Key: description: LangSmith API key (`lsv2_...`). type: apiKey name: X-Api-Key in: header Tenant_ID: description: Workspace (tenant) UUID the request operates in. type: apiKey name: X-Tenant-Id in: header Bearer_Auth: description: Session JWT, sent as `Bearer `. type: apiKey name: Authorization in: header ````