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"
  },
  "model": "openai:gpt-5.5",
  "backend": {
    "type": "default"
  },
  "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" } }, "backend": { "type": "default" }, "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 } } }

Documentation Index

Fetch the complete documentation index at: https://docs.langchain.com/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
model
string

Model identifier used to run the agent. Use the form {provider}:{model_name}, for example openai:gpt-5.5. Values without a colon are interpreted as references to a saved Playground configuration, not as direct model identifiers.

Example:

"openai:gpt-5.5"

​
permissions
object

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

​
runtime
object
​
backend
object

Backend configuration for the agent. Use default when the agent does not need sandbox-specific backend behavior. Use thread_scoped_sandbox or agent_scoped_sandbox when the agent needs LangSmith sandbox resources for code execution, filesystem work, or long-running tasks. See Sandboxes overview.

​
instructions
string

Agent system prompt. Written to AGENTS.md.

​
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.

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
​
backend
object

Backend configuration for the agent. Use default when the agent does not need sandbox-specific backend behavior. Use thread_scoped_sandbox or agent_scoped_sandbox when the agent needs LangSmith sandbox resources for code execution, filesystem work, or long-running tasks. See Sandboxes overview.

​
extras
object
​
revision
string

Revision token for the latest file tree commit.

​
instructions
string

Agent system prompt parsed from AGENTS.md.

​
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.