Skip to main content
POST
/
agents
Create an agent
curl --request POST \
  --url https://api.smith.langchain.com/v1/deepagents/agents \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "name": "research-assistant",
  "description": "Research assistant that can search the web and summarize sources.",
  "permissions": {
    "identity": "personal",
    "visibility": "user"
  },
  "runtime": {
    "model": {
      "model_id": "openai:gpt-5.5"
    }
  },
  "instructions": "You are a careful research assistant. Search for sources, keep notes, and return concise answers with citations.",
  "tools": {
    "tools": [
      {
        "name": "tavily_web_search",
        "mcp_server_url": "https://tools.langchain.com",
        "mcp_server_name": "Fleet",
        "display_name": "tavily_web_search"
      }
    ],
    "interrupt_config": {
      "https://tools.langchain.com::tavily_web_search::Fleet": true
    }
  }
}
'
{ "id": "dfa71115-c971-4197-8f02-20826fbc6f40", "name": "research-assistant", "description": "Research assistant that can search the web and summarize sources.", "owner_id": "33499cf9-4c02-49af-909d-b8f42e051eab", "created_at": "2026-05-15T20:50:32.708302+00:00", "updated_at": "2026-05-15T20:50:32.708302+00:00", "permissions": { "identity": "personal", "visibility": "user", "tenant_access_level": "read" }, "runtime": { "model": { "model_id": "openai:gpt-5.5" } }, "revision": "13ac11f11da376e588cb84825ed88d05298f27aaaa90c6f694abf572f34161d9", "instructions": "You are a careful research assistant. Search for sources, keep notes, and return concise answers with citations.", "tools": { "tools": [ { "name": "tavily_web_search", "mcp_server_url": "https://tools.langchain.com", "mcp_server_name": "Fleet", "display_name": "tavily_web_search" } ], "interrupt_config": { "https://tools.langchain.com::tavily_web_search::Fleet": true } } }

Authorizations

​
X-Api-Key
string
header
default:LANGSMITH_API_KEY
required

Headers

​
X-User-Timezone
string

IANA timezone name (for example, America/Los_Angeles) stamped into the agent's runtime configuration when the agent is created or updated. The runtime uses this timezone to inject a localized current-date line into the agent's system prompt, so the agent reasons about dates in the user's local time. Optional. Defaults to UTC when omitted; invalid values fall back to UTC.

Example:

"America/Los_Angeles"

Query Parameters

​
include_files
boolean
default:false

Include the raw file map in the agent response. Accepted truthy values are true and 1.

Body

application/json
​
name
string
required

Human-readable agent name. Must not be blank.

​
description
string

Short agent description.

​
permissions
object

Agent visibility and sharing configuration. When omitted on create, defaults to personal identity, tenant visibility, and read tenant access.

​
runtime
object
​
instructions
string

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

​
tools
object
​
subagents
object[]

Subagents. Each entry is written to subagents/<name>/AGENTS.md and, when provided, subagents/<name>/tools.json.

​
skills
object[]

Inline skills. Each entry is written to skills/<name>/SKILL.md and supporting files.

​
extras
object

Caller-defined key-value metadata attached to the agent.

​
files
object

Raw file map for paths not covered by typed fields. Keys are relative file paths. Setting a typed field and the corresponding files entry returns 422.

​
backend
object
​
system_prompt
string

Agent system prompt. Written to AGENTS.md. Preferred over deprecated instructions when both are provided.

​
configurable
object

Caller-defined runtime configuration merged into the agent config. Typed runtime fields win on key collision.

Response

Agent created.

​
id
string<uuid>
​
name
string
​
description
string
​
owner_id
string<uuid>
​
created_at
string<date-time>
​
updated_at
string<date-time>
​
permissions
object

Agent visibility and sharing configuration. When omitted on create, defaults to personal identity, tenant visibility, and read tenant access.

​
runtime
object
​
extras
object
​
access_level
enum<string>

Caller access level for this agent.

Available options:
READ,
RUN,
WRITE
​
is_owner
boolean

Whether the authenticated caller owns this agent.

​
backend
object
​
revision
string

Revision token for the latest file tree commit.

​
instructions
string

Deprecated alias echoed alongside system_prompt for backwards compatibility.

​
tools
object
​
subagents
object[]
​
skills
object[]
​
files
object

Raw file map for paths not covered by typed fields. Keys are relative file paths. Setting a typed field and the corresponding files entry returns 422.

​
system_prompt
string

Agent system prompt parsed from AGENTS.md.