Update an agent

curl --request PATCH \
  --url https://api.smith.langchain.com/v1/deepagents/agents/{agent_id} \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "description": "Research assistant that searches the web, reads URLs, and summarizes sources.",
  "instructions": "You are a careful research assistant. Search for sources, read relevant pages, 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"
      },
      {
        "name": "read_url_content",
        "mcp_server_url": "https://tools.langchain.com",
        "mcp_server_name": "Fleet",
        "display_name": "read_url_content"
      }
    ],
    "interrupt_config": {
      "https://tools.langchain.com::tavily_web_search::Fleet": true,
      "https://tools.langchain.com::read_url_content::Fleet": false
    }
  }
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "description": "<string>",
  "owner_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "permissions": {
    "identity": "personal",
    "visibility": "tenant",
    "tenant_access_level": "read",
    "shared_users": {
      "read": [
        "<string>"
      ],
      "run": [
        "<string>"
      ],
      "update": [
        "<string>"
      ]
    }
  },
  "runtime": {
    "model": {
      "model_id": "openai:gpt-5.5"
    }
  },
  "extras": {},
  "is_owner": true,
  "backend": {
    "type": "state",
    "sandbox_config": {
      "scope": "thread",
      "snapshot_id": "550e8400-e29b-41d4-a716-446655440000",
      "policy_ids": [
        "<string>"
      ],
      "idle_ttl_seconds": 600,
      "delete_after_stop_seconds": 1200
    }
  },
  "revision": "<string>",
  "instructions": "<string>",
  "tools": {
    "tools": [
      {
        "name": "<string>",
        "mcp_server_url": "<string>",
        "mcp_server_name": "<string>",
        "display_name": "<string>"
      }
    ],
    "interrupt_config": {}
  },
  "subagents": [
    {
      "name": "<string>",
      "description": "<string>",
      "model_id": "<string>",
      "instructions": "<string>",
      "tools": {
        "tools": [
          {
            "name": "<string>",
            "mcp_server_url": "<string>",
            "mcp_server_name": "<string>",
            "display_name": "<string>"
          }
        ],
        "interrupt_config": {}
      }
    }
  ],
  "skills": [
    {
      "type": "inline",
      "name": "<string>",
      "description": "<string>",
      "instructions": "<string>",
      "files": {}
    }
  ],
  "files": {},
  "system_prompt": "<string>"
}

PATCH

agents

{agent_id}

Update an agent

curl --request PATCH \
  --url https://api.smith.langchain.com/v1/deepagents/agents/{agent_id} \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "description": "Research assistant that searches the web, reads URLs, and summarizes sources.",
  "instructions": "You are a careful research assistant. Search for sources, read relevant pages, 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"
      },
      {
        "name": "read_url_content",
        "mcp_server_url": "https://tools.langchain.com",
        "mcp_server_name": "Fleet",
        "display_name": "read_url_content"
      }
    ],
    "interrupt_config": {
      "https://tools.langchain.com::tavily_web_search::Fleet": true,
      "https://tools.langchain.com::read_url_content::Fleet": false
    }
  }
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "description": "<string>",
  "owner_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "permissions": {
    "identity": "personal",
    "visibility": "tenant",
    "tenant_access_level": "read",
    "shared_users": {
      "read": [
        "<string>"
      ],
      "run": [
        "<string>"
      ],
      "update": [
        "<string>"
      ]
    }
  },
  "runtime": {
    "model": {
      "model_id": "openai:gpt-5.5"
    }
  },
  "extras": {},
  "is_owner": true,
  "backend": {
    "type": "state",
    "sandbox_config": {
      "scope": "thread",
      "snapshot_id": "550e8400-e29b-41d4-a716-446655440000",
      "policy_ids": [
        "<string>"
      ],
      "idle_ttl_seconds": 600,
      "delete_after_stop_seconds": 1200
    }
  },
  "revision": "<string>",
  "instructions": "<string>",
  "tools": {
    "tools": [
      {
        "name": "<string>",
        "mcp_server_url": "<string>",
        "mcp_server_name": "<string>",
        "display_name": "<string>"
      }
    ],
    "interrupt_config": {}
  },
  "subagents": [
    {
      "name": "<string>",
      "description": "<string>",
      "model_id": "<string>",
      "instructions": "<string>",
      "tools": {
        "tools": [
          {
            "name": "<string>",
            "mcp_server_url": "<string>",
            "mcp_server_name": "<string>",
            "display_name": "<string>"
          }
        ],
        "interrupt_config": {}
      }
    }
  ],
  "skills": [
    {
      "type": "inline",
      "name": "<string>",
      "description": "<string>",
      "instructions": "<string>",
      "files": {}
    }
  ],
  "files": {},
  "system_prompt": "<string>"
}

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"

Path Parameters

agent_id

string<uuid>

required

Managed Deep Agent ID.

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

Sparse update payload. Omitted fields are left unchanged.

name

string

Updated agent name.

description

string

Updated agent description.

permissions

object

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

Show child attributes

runtime

object

Show child attributes

instructions

string

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

tools

object

Show child attributes

subagents

object[]

Updated subagent definitions. Replaces the existing subagents field in full.

Show child attributes

skills

object[]

Updated inline skills. Replaces the existing skills field in full.

Show child attributes

extras

object

Updated caller-defined metadata. Replaces the existing extras field in full.

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.

Show child attributes

backend

object

Show child attributes

system_prompt

string

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

configurable

object

Updated caller-defined runtime configuration. Typed runtime fields win on key collision.

deleted_paths

string[]

Relative file paths to remove from the file tree.

Response

Agent updated.

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.

Show child attributes

runtime

object

Show child attributes

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

Show child attributes

revision

string

Revision token for the latest file tree commit.

instructions

string

Deprecated alias echoed alongside system_prompt for backwards compatibility.

tools

object

Show child attributes

subagents

object[]

Show child attributes

skills

object[]

Show child attributes

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.

Show child attributes

system_prompt

string

Agent system prompt parsed from AGENTS.md.

Delete an agent

Clone an agent