---
title: "Create an agent"
method: POST
path: "/v1/fleet/agents"
tags: ["agents"]
---

# Create an agent

`POST /v1/fleet/agents`

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.

## Query parameters

- `include_files` boolean

## Request body

- AgentsCreateAgentRequest
  - `backend` AgentsAgentBackend
    - `sandbox` AgentsSandboxConfig
      - `delete_after_stop_seconds` integer — Time after a sandbox is stopped before it is deleted, in seconds.
      - `idle_ttl_seconds` integer — Idle timeout after which an unused sandbox is paused, in seconds.
      - `policy_ids` string[] — Sandbox policies governing tool execution.
      - `snapshot_id` string — Snapshot used when creating new sandbox-backed computers.
    - `type` 'default' | 'thread_scoped_sandbox' | 'agent_scoped_sandbox' — Execution backend type. Use a scoped sandbox backend for sandbox-backed agents.
  - `configurable` object — Caller-defined key/value tracking merged into the agent's runtime configuration. Typed runtime fields win on key collision.
  - `description` string
  - `extras` object — Caller-defined key/value tracking attached to the agent's metadata.
  - `files` object — Raw file map for paths the typed fields don't cover. Setting a typed field and the corresponding `files` entry returns 422.
  - `instructions` string — Deprecated: use `system_prompt`. Accepted for backwards compatibility; `system_prompt` takes precedence when both are set.
  - `name` string, required
  - `permissions` AgentsAgentPermissions
    - `identity` 'personal' | 'shared'
    - `shared_users` AgentsSharedUsers
      - `read` string[] — User IDs allowed to read the agent.
      - `run` string[] — User IDs allowed to run the agent.
      - `update` string[] — User IDs allowed to update the agent.
    - `tenant_access_level` 'read' | 'run' | 'write'
    - `visibility` 'tenant' | 'user'
  - `runtime` AgentsAgentRuntime
    - `model` AgentsAgentModelConfig
      - `model_id` string — Model ID used to run the agent.
  - `skills` AgentsSkillSpec[] — Skills. Each entry is written to `skills/<name>/SKILL.md` and supporting files.
    - `description` string — Short human-readable description shown to the agent.
    - `files` object — Supporting files keyed by relative path. Each path becomes `skills/<name>/<path>`. Paths must be relative — no leading `/`, no `..` segments.
    - `instructions` string — Skill body. Written to `skills/<name>/SKILL.md`.
    - `name` string — Skill slug. Becomes `skills/<name>/SKILL.md`.
    - `type` 'inline' — Skill discriminator. Only `inline` is supported today.
  - `subagents` AgentsSubagentSpec[] — Subagents. Each entry is written to `subagents/<name>/AGENTS.md` and `subagents/<name>/tools.json`.
    - `description` string — Short human-readable description.
    - `instructions` string — Subagent system prompt. Written to `subagents/<name>/AGENTS.md`.
    - `model_id` string — Model ID for this subagent. Inherits the parent runtime when empty.
    - `name` string — Subagent slug. Becomes `subagents/<name>/AGENTS.md`.
    - `tools` AgentsToolsConfig
      - `interrupt_config` object — Per-tool interrupt rules keyed by tool name. Use `{}` for no interrupts.
      - `tools` AgentsToolSpec[] — MCP tools available to the agent. Serialised to `tools.json`.
        - `display_name` string — Display name for the tool. Defaults to the tool name when empty.
        - `mcp_server_name` string — Display name for the MCP server. Defaults to the URL when empty.
        - `mcp_server_url` string — URL of the MCP server hosting this tool.
        - `name` string — Tool name as exposed by the MCP server.
  - `system_prompt` string — Agent system prompt. Written to `AGENTS.md`.
  - `tools` AgentsToolsConfig
    - `interrupt_config` object — Per-tool interrupt rules keyed by tool name. Use `{}` for no interrupts.
    - `tools` AgentsToolSpec[] — MCP tools available to the agent. Serialised to `tools.json`.
      - `display_name` string — Display name for the tool. Defaults to the tool name when empty.
      - `mcp_server_name` string — Display name for the MCP server. Defaults to the URL when empty.
      - `mcp_server_url` string — URL of the MCP server hosting this tool.
      - `name` string — Tool name as exposed by the MCP server.

## Response `201`

Created

- AgentsAgent
  - `access_level` 'READ' | 'RUN' | 'WRITE'
  - `backend` AgentsAgentBackend
    - `sandbox` AgentsSandboxConfig
      - `delete_after_stop_seconds` integer — Time after a sandbox is stopped before it is deleted, in seconds.
      - `idle_ttl_seconds` integer — Idle timeout after which an unused sandbox is paused, in seconds.
      - `policy_ids` string[] — Sandbox policies governing tool execution.
      - `snapshot_id` string — Snapshot used when creating new sandbox-backed computers.
    - `type` 'default' | 'thread_scoped_sandbox' | 'agent_scoped_sandbox' — Execution backend type. Use a scoped sandbox backend for sandbox-backed agents.
  - `created_at` string, date-time
  - `description` string
  - `extras` object
  - `files` object — Raw file map. Returned only when `include_files=true`.
  - `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` AgentsAgentPermissions
    - `identity` 'personal' | 'shared'
    - `shared_users` AgentsSharedUsers
      - `read` string[] — User IDs allowed to read the agent.
      - `run` string[] — User IDs allowed to run the agent.
      - `update` string[] — User IDs allowed to update the agent.
    - `tenant_access_level` 'read' | 'run' | 'write'
    - `visibility` 'tenant' | 'user'
  - `revision` string
  - `runtime` AgentsAgentRuntime
    - `model` AgentsAgentModelConfig
      - `model_id` string — Model ID used to run the agent.
  - `skills` AgentsSkillSpec[] — Skills parsed from `skills/<name>/SKILL.md` and supporting files.
    - `description` string — Short human-readable description shown to the agent.
    - `files` object — Supporting files keyed by relative path. Each path becomes `skills/<name>/<path>`. Paths must be relative — no leading `/`, no `..` segments.
    - `instructions` string — Skill body. Written to `skills/<name>/SKILL.md`.
    - `name` string — Skill slug. Becomes `skills/<name>/SKILL.md`.
    - `type` 'inline' — Skill discriminator. Only `inline` is supported today.
  - `subagents` AgentsSubagentSpec[] — Subagents parsed from `subagents/<name>/AGENTS.md` + `subagents/<name>/tools.json`.
    - `description` string — Short human-readable description.
    - `instructions` string — Subagent system prompt. Written to `subagents/<name>/AGENTS.md`.
    - `model_id` string — Model ID for this subagent. Inherits the parent runtime when empty.
    - `name` string — Subagent slug. Becomes `subagents/<name>/AGENTS.md`.
    - `tools` AgentsToolsConfig
      - `interrupt_config` object — Per-tool interrupt rules keyed by tool name. Use `{}` for no interrupts.
      - `tools` AgentsToolSpec[] — MCP tools available to the agent. Serialised to `tools.json`.
        - `display_name` string — Display name for the tool. Defaults to the tool name when empty.
        - `mcp_server_name` string — Display name for the MCP server. Defaults to the URL when empty.
        - `mcp_server_url` string — URL of the MCP server hosting this tool.
        - `name` string — Tool name as exposed by the MCP server.
  - `system_prompt` string — Agent system prompt parsed from `AGENTS.md`.
  - `tools` AgentsToolsConfig
    - `interrupt_config` object — Per-tool interrupt rules keyed by tool name. Use `{}` for no interrupts.
    - `tools` AgentsToolSpec[] — MCP tools available to the agent. Serialised to `tools.json`.
      - `display_name` string — Display name for the tool. Defaults to the tool name when empty.
      - `mcp_server_name` string — Display name for the MCP server. Defaults to the URL when empty.
      - `mcp_server_url` string — URL of the MCP server hosting this tool.
      - `name` string — Tool name as exposed by the MCP server.
  - `updated_at` string, date-time

## Other responses

- `400` — Bad Request
- `403` — Forbidden
- `409` — Conflict
- `422` — Unprocessable Entity
- `500` — Internal Server Error
- `502` — Bad Gateway
- `503` — Service Unavailable

---

[API](https://skmtc.net/langchain-ai/apis/langsmith.md) · [All operations](https://skmtc.net/langchain-ai/apis/langsmith/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/langchain-ai/langsmith/versions/a0acb3a6a101/schema)