托管深度代理 API 创建、更新、连接和调用 托管深度代理。使用 托管深度代理 SDK 用于 Python、TypeScript 和 React 应用程序。当您需要直接控制请求负载时，请使用 REST API。有关推荐的整体工作流程，请参阅 快速入门.

设置请求默认值

API 使用 /v1/deepagents:

请求需要 X-Api-Key header:

X-Api-Key: 

例如，使用上面设置的 base URL 和 header 列出代理：

curl "$DEEPAGENTS_BASE_URL/agents" \
  -H "X-Api-Key: $LANGSMITH_API_KEY"

缺少 X-Api-Key header 返回 401 with {"error": "Unauthorized"}。无效的 key 或缺少工作区访问权限的 key 返回 403 with {"error": "Forbidden"}。这些身份验证响应使用扁平的 {"error": "..."} body，而非其他 4xx 响应返回的结构化错误 body。有效 key 但其角色缺少所需权限时也会返回 403，但 body 为纯文本，注明缺失的权限（例如， missing permission mcp-servers:create），SDK 会在 error.body.

了解资源组

托管深度代理不是 LangSmith 部署。创建托管深度代理会生成一个托管深度代理资源、一个独立的 LangSmith 追踪项目，以及一个用于托管文件树的 Context Hub 代理仓库。

配置沙盒

创建代理和更新代理的有效负载可以包含 backend 对象。使用 state 当代理不需要沙盒特定后端行为时：

{
  "backend": {
    "type": "state"
  }
}

使用 sandbox 当代理需要 LangSmith 沙盒 用于代码执行、文件系统操作或长时间运行的任务。沙盒后端设置位于 backend.sandbox_config 下，仅在以下情况下有效 backend.type is sandbox:

{
  "backend": {
    "type": "sandbox",
    "sandbox_config": {
      "scope": "thread",
      "policy_ids": ["policy-id"],
      "idle_ttl_seconds": 900,
      "delete_after_stop_seconds": 300
    }
  }
}

此 sandbox 对象接受：

有关后端指导，请参阅 部署代理。有关独立沙箱概念，请参阅 LangSmith 沙箱概述.

使用通用 REST 命令

代理

请参阅 部署代理 了解创建和更新工作流。关于删除行为，请参阅 限制和注意事项.

线程

请参阅 运行代理 了解如何创建线程和管理跨运行的持久状态。

运行

请参阅 运行代理 了解如何在线程上启动运行并流式传输其输出。

MCP 服务器

请参阅 连接工具 了解如何注册 MCP 服务器和存储代理工具使用的凭证。

MCP 工具

参见 连接工具 用于列出已注册服务器公开的工具并进行构建 tools.json entries.

认证会话

参见 连接工具 用于运行授权 MCP 服务器的 OAuth 流程。

对代理列表进行分页

GET /v1/deepagents/agents 使用游标分页。传递 page_size （默认值为 20，最大值为 100），以及上次请求返回的不透明 cursor 。响应将结果包装在 items 数组中，同时返回一个 next_cursor 字段，当该字段为 null 时表示最后一页：

{
  "items": [],
  "next_cursor": null
}

该端点还接受 name 按名称子字符串过滤， sort_by (created_at, updated_at, or name，默认值为 updated_at），以及 sort_order (asc or desc，默认值为 desc).

了解 API 稳定性

路由在 /v1/进行版本控制，但该接口处于私有测试阶段，在正式发布前可能会发生不兼容的变更。参见 API 稳定性 了解破坏性变更的沟通方式。

该 API 并未镜像所有 LangSmith 部署端点。集成、触发器、技能、沙盒、认证提供商和认证令牌等端点组均未被镜像。