Deep Agents 框架-开发部署

上篇

引言

本篇主要介绍了解一下deepagents开发部署架构。目前来看这个系列适合做个个体应用，不适做服务化，非要做的化估计还得做很多努力。

1 使用CLI部署

Deep Agents Deploy 能够获取你的智能体配置，并将其部署为LangSmith 部署实例：这是一个支持水平扩展的服务器，内置了 30+ 个端点，涵盖了 MCP、A2A、智能体协议、人机协同以及记忆存储等 API。

它完全构建在开放标准之上：

• 开源框架
  采用 MIT 许可证，同时提供 Python 和 TypeScript 版本。
• AGENTS.md
  用于定义智能体指令的开放标准。
• 智能体技能
  用于定义智能体知识与动作的开放标准。
• 模型与沙箱无关
  支持任意模型和任意沙箱环境，彻底告别供应商锁定。
• 开放协议
  原生支持 MCP、A2A 和智能体协议。
• 支持自托管
  LangSmith 部署实例支持自托管，确保记忆数据完全保留在你自己的基础设施中。

Deep Agents Deploy 目前处于Beta 测试阶段，需要deepagents-cli>=0.0.36版本支持。

请注意，API、配置格式以及具体行为在不同版本发布之间可能会发生变更。详细的更新日志请查看发布页面。

1.1与 Claude 托管智能体进行对比

1.2 部署内容

deepagents deploy会将你的智能体配置打包，并作为LangSmith 部署实例进行部署。你需要配置以下几个核心参数：

1.3 安装

安装命令行工具，或者直接用uvx运行

#安装模式 uv tool install deepagents-cli #或者 无需安装 uvx deepagents-cli deploy

1.4 使用

deepagents init [name] [--force] # scaffold a new project deepagents dev [--config deepagents.toml] [--port 2024] [--allow-blocking] # bundle and run locally deepagents deploy [--config deepagents.toml] [--dry-run] # bundle and deploy

默认情况下，deepagents deploy会在当前目录下查找deepagents.toml文件。如果你想使用其他路径的配置文件，请加上--config参数：

deepagents deploy --config path/to/deepagents.toml

deepagents deploy 每次执行时都会完全重新构建并创建一个新的版本修订。
如果你想在本地进行快速迭代开发，请使用 deepagents dev

deepagents init

快速搭建一个新的智能体项目脚手架：

deepagents init my-agent

这会创建以下文件：

生成的文件结构

初始化之后，请编辑AGENTS.md文件来编写你的智能体指令，然后运行deepagents deploy进行部署。你也可以选择性地添加一个user/目录，用于存放每个用户的记忆模板 —— 详见用户记忆文档

1.5 项目布局

deploy命令采用了基于约定的项目布局。只要将以下文件放在你的deepagents.toml旁边，它们就会被自动识别：

mcp.json必须只包含使用http或sse传输协议的服务器。

• 原因：在部署环境（云端/沙箱）中，无法像本地那样随意启动新的进程（stdio传输方式需要启动本地进程）。
• 解决方案：如果你原本使用的是stdio服务器，在部署前必须将其转换为HTTP或SSE模式。

mcp.json必须只包含使用http或sse传输协议的服务器。

• 原因：在部署环境（云端/沙箱）中，无法像本地那样随意启动新的进程（stdio传输方式需要启动本地进程）。
• 解决方案：如果你原本使用的是stdio服务器，在部署前必须将其转换为HTTP或SSE模式。

1.6 配置文件

这个文件主要配置智能体的身份和沙箱环境。

• [agent]：必填部分，定义核心身份。
• [sandbox]：选填部分，定义运行环境（默认不开启沙箱）。

1.6.1 [agent] 部分 (必填)

这是智能体的核心身份配置。

表格

[agent] name = "research-assistant" model = "google_genai:gemini-3.1-pro-preview"

name字段是整个配置文件中唯一必填的值。其他所有配置都有默认值。

技能、用户记忆、子代理、MCP 服务器以及模型依赖项均根据项目布局自动检测。

1.6.2[sandbox]

配置 Agent 运行代码时的隔离执行环境。沙箱提供了一个带有文件系统和 Shell 访问权限的容器，这样即使运行不可信的代码，也不会影响到宿主机。关于支持的提供商和高级沙箱配置，请参阅沙箱集成文档。

如果省略此项或设置为provider = "none"，则禁用沙箱。如果你需要执行代码或运行技能脚本，就需要用到沙箱。

provider

• 类型: 字符串
• 默认值:"none"
• 说明: 沙箱提供商。决定了容器在哪里运行。支持的值有："none","daytona","modal","runloop","langsmith"(私有测试版)。具体提供商详情请见沙箱集成文档。

template

• 类型: 字符串
• 默认值:"deepagents-deploy"
• 说明: 沙箱环境特定于提供商的模板名称。

image

• 类型: 字符串
• 默认值:"python:3"
• 说明: 沙箱容器的基础 Docker 镜像。

scope

• 类型: 字符串
• 默认值:"thread"
• 说明: 沙箱的生命周期范围。
  • "thread"：每次对话创建一个沙箱。
  • "assistant"：同一个 Agent 的所有对话共享一个沙箱。

范围行为详解：

• "thread"(默认)：每个对话都有自己独立的沙箱。不同的会话（Thread）会获得不同的沙箱，但同一个会话在多轮交互中会复用同一个沙箱。如果你希望每次对话都从一个干净的环境开始，请使用此选项。
• "assistant"：所有对话共享同一个沙箱。文件、已安装的包和其他状态会在不同对话之间持久保存。如果你希望 Agent 维护一个长期存在的工作区（比如一个克隆的代码仓库），请使用此选项。

1.6.3 [auth]

添加[auth]部分来控制已部署 Agent 的身份验证。当存在此部分时，打包工具会自动生成一个auth.py文件并将其接入到部署环境中。当[frontend].enabled = true时，此项是必填的；否则是选填的（如果不填，LangSmith 部署将默认应用x-api-key的验证要求）。

provider

• 类型: 字符串
• 必填: 是
• 说明: 身份验证提供商。支持的值有："supabase","clerk","anonymous"。

[agent] name = "my-agent" model = "google-genai:gemini-3.1-pro-preview" [auth] provider = "supabase" # supabase | clerk | anonymous

所需的环境变量取决于你选择的提供商：

请将这些变量与其他凭证一起添加到你的 .env 文件中。打包工具会在部署时验证是否包含了所有必需的变量，如果缺少任何变量，它会快速失败并给出清晰的错误提示。

运行时行为：

• 未经认证的请求将返回401状态码。
• 认证成功后，经过验证的用户身份会被注入到config.configurable.langgraph_auth_user_id中。
• 所有资源（线程、运行记录、存储）都会通过metadata.owner自动按用户进行隔离（即每个用户只能看到自己的资源）。
• LangSmith Studio 在本地开发时会绕过身份验证

这段文档介绍了如何给你的智能体配一个现成的前端界面。你不需要自己写 React 代码，只要在配置文件里开启这个功能，系统就会自动给你生成一个聊天网页。

以下是详细的配置说明：

1.6.4 [frontend] 前端配置详解

前置条件：需要deepagents-cli >= 0.0.43版本。

开启[frontend]后，系统会将一个预构建的React 聊天界面与你的智能体一起部署。

• 访问路径：前端界面挂载在/app路径下。
• API 路径：你的 LangGraph API 依然保留在根路径/（如/threads,/runs等）。
• 认证方式：支持三种模式 ——Clerk、Supabase或匿名访问。

配置参数

[agent] name = "my-agent" model = "anthropic:claude-sonnet-4-6" [auth] provider = "supabase" # or "clerk" [frontend] enabled = true app_name = "My Agent" subtitle = "Your AI research assistant" prompts = [ "Summarize this paper", "Find related work", "Draft an outline", ]

身份验证提供商

当[frontend].enabled = true时，[auth]是必填项。请从以下三种提供商中选择一种：

1. Clerk ([auth] provider = "clerk")

• 真正的按用户验证。
• 每个用户都需要登录；线程（Threads）和记忆（Memory）都会按用户进行隔离（即用户只能看到自己的数据）。

2. Supabase ([auth] provider = "supabase")

• 真正的按用户验证。
• 与 Clerk 一样，提供按用户的数据隔离。

3. Anonymous ([auth] provider = "anonymous")

• 注意：这不是为了安全，而是为了演示。
• 打包工具会附带一个宽松的验证处理程序，它会覆盖 LangSmith 部署默认的x-api-key要求，这样前端才能访问/threads接口。
• 这意味着任何拥有部署 URL 的人都可以调用 API。
• 前端会给每个浏览器分配一个 UUID Cookie，并据此过滤线程选择器（这仅仅是用户体验层面的隔离，不是安全隔离）。
• 为了提醒你风险，CLI 在推送部署前需要用户进行交互式的y/N确认。

✨ 你将获得的功能

配置好前端后，你会得到以下功能：

• 与 Agent 进行流式聊天。
• 线程选择器，标题会根据用户的第一条消息自动生成。
• 实时待办事项、文件以及子代理活动面板，这些面板会反映你的深度 Agent 的实时图谱状态。
• 明/暗色主题切换，首次加载时跟随系统偏好，之后会记住用户的选择。
• （仅限 Clerk / Supabase）登录 / 注册 / 登出流程 —— Clerk 提供完整的组件（包含社交登录、密码重置）；Supabase 提供邮箱/密码登录及内置的密码重置流程。

⚙️ 环境变量

前端复用了[auth]中大部分已有的配置。只有 Clerk 需要额外提供一个面向浏览器的密钥。

这段话是在讲部署后的收尾工作。

代码部署上去只是第一步，为了让登录跳转能正常工作（比如登录完能自动跳回你的应用，而不是报错），你得去第三方平台（Clerk 或 Supabase）的后台做个“白名单”设置。

以下是中文翻译：

🚀 部署后设置

部署完成后，请将你的部署 URL添加到身份验证提供商的仪表板中，这样验证后的重定向才能正确回到你的应用。对于每个部署 URL，这都是一次性的设置步骤。

Clerk 配置

• 路径：仪表板 → 你的应用 →Domains（域名）→ 添加你的部署主机名（例如clerk-abc.us.langgraph.app）。
• 注意：Clerk 的开发实例会自动把localhost加入白名单，但生产环境的部署 URL 需要显式添加。

Supabase 配置

• 路径：仪表板 →Authentication（认证）→URL Configuration（URL 配置）→ 在Redirect URLs（重定向 URL）中添加https://<你的部署地址>/app/**。
• 注意：如果不添加此项，密码重置和邮箱确认链接将无法正确跳转回你的应用。

1.6.5 .env

将.env文件放在deepagents.toml旁边，并在里面填入你的 API 密钥：

1.7 认证

运行时的身份验证行为取决于[auth]的配置：

1. 配置了 Supabase 或 Clerk

• [auth] provider = "supabase"或"clerk"
• 机制：真正的按用户验证。
• 如何调用：在Authorization请求头中传递用户的身份验证提供商令牌（Token）。

2. 配置了匿名模式

• [auth] provider = "anonymous"
• 机制：打包工具会附带一个宽松的验证处理程序。API 对任何拥有部署 URL 的人开放。
• 如何调用：不需要任何请求头。
• 注意：如果你要发布前端但不需要真正的按用户验证，则必须使用此选项。

3. 未配置 [auth] 部分

• 机制：部署将回退到 LangSmith 部署的默认行为，即要求x-api-key。
• 如何调用：在x-api-key请求头中传递你的 LangSmith API 密钥。
• 限制：仅在[frontend].enabled为false或未设置时有效。

当[auth]配置为 Supabase 或 Clerk 时，请在Authorization请求头中传递来自你身份验证提供商的令牌：

表格

每个用户的线程和记忆都会自动隔离——用户 B 无法看到用户 A 的线程。

1.8 沙箱供应商

在deepagents.toml中设置[sandbox].provider，并在.env文件中添加所需的环境变量。

• 关于可用的提供商列表，请查看沙箱集成文档。
• 关于生命周期模式和 SDK 使用方法，请查看沙箱文档

1.9 部署端点

已部署的服务器开放了以下功能：

• MCP：允许其他 Agent 将你的 Agent 作为工具来调用。
• A2A：通过 A2A 协议进行多智能体编排（即让多个 Agent 协同工作）。
• Agent Protocol：用于构建用户界面的标准 API。
• Human-in-the-loop：针对敏感操作的“人工审批”关卡（即关键时刻让人类介入确认）。
• Memory：支持访问短期和长期记忆。

1.10 例子

一个具备“按用户偏好设置”功能的内容写作 Agent，且该 Agent 拥有更新这些偏好的权限。

[agent] name = "deepagents-deploy-content-writer" model = "google_genai:gemini-3.1-pro-preview"

my-content-writer/ ├── deepagents.toml ├── AGENTS.md ├── skills/ │ ├── blog-post/SKILL.md │ └── social-media/SKILL.md └── user/ └── AGENTS.md # writable — agent learns user preferences

一个配备了 LangSmith 沙箱环境的编程 Agent，用于运行代码。

[agent] name = "deepagents-deploy-coding-agent" model = "google_genai:gemini-3.1-pro-preview" [sandbox] provider = "langsmith" template = "coding-agent" image = "python:3.12"

一个负责制定 GTM（市场进入）策略的 Agent，它将调研工作委派给子 Agent 处理。

my-gtm-agent/ ├── deepagents.toml ├── AGENTS.md ├── skills/ │ └── competitor-analysis/ │ └── SKILL.md └── subagents/ └── market-researcher/ ├── deepagents.toml ├── AGENTS.md └── skills/ └── analyze-market/ └── SKILL.md

这是一个轻量级的内部演示智能体，它附带了现成的用户界面，并以匿名模式运行（无需注册账号，也无需配置复杂的基础设施）

[agent] name = "internal-demo" model = "anthropic:claude-sonnet-4-6" [auth] provider = "anonymous" # API open to anyone with the URL — confirm at deploy time [frontend] enabled = true

1.11 使用记忆

用户记忆功能能为每个用户提供一个可独立写入的AGENTS.md文件，并且这些内容会在多次对话之间持久保存。要启用它，只需在你的项目根目录下创建一个user/文件夹即可：

user/ └── AGENTS.md # optional — seeded as empty if not provided

1. 初始化阶段（打包时）

只要项目里存在user/目录（哪怕是空的），系统就会为每个用户分配一个专属路径：/memories/user/AGENTS.md。

• 有模板：如果你放了一个user/AGENTS.md文件，它的内容会作为初始模板。
• 无模板：如果目录是空的，系统会创建一个空文件作为起点。

2. 运行时阶段（用户交互）

系统会根据用户的身份（runtime.server_info.user.identity）来隔离数据，确保每个人只能读写自己的文件。

• 首次访问：系统会把上面的“模板”复制一份给这个新用户。
• 后续访问：
  • 智能体对这个文件的修改会被保存（比如用户说“记住我喜欢吃辣”，智能体会写入文件）。
  • 部署更新不会覆盖用户数据：这点非常重要！即使你重新部署项目（更新了代码或模板），老用户的记忆文件不会被重置，依然保留他们之前的个性化数据。

工作原理

• 打包时：打包工具会读取user/AGENTS.md文件（如果不存在则使用空字符串），并将其包含在种子载荷中。
• 运行时（首次访问）：当 Agent 第一次遇到某个user_id时，它会将AGENTS.md模板写入该用户命名空间下的存储中。现有的条目永远不会被覆盖（即不会重置用户的个性化设置）。
• 预加载：用户专属的AGENTS.md会被传递给记忆中间件，因此在每次对话开始时，Agent 都能在上下文中看到其内容。
• 可写性：Agent 可以使用edit_file工具来更新它。相比之下，共享的AGENTS.md文件和skills文件夹是只读的。

权限表

用户身份

• 来源：user_id是通过自定义身份验证从runtime.user.identity中解析出来的。
• 自动注入：平台会自动注入经过验证的用户身份 ——不需要通过configurable手动传递它。
• 未认证情况：如果当前请求没有经过验证的用户，该次调用的用户记忆功能将被优雅地跳过（即不会报错，只是不加载个人记忆）。

1.12 子智能体

子智能体允许主智能体将特定的专业任务委派给独立的子智能体。

每个子智能体都拥有：

• 独立的系统提示词
• 可选的技能
• 可选的 MCP 工具

主智能体会自动获得一个任务工具，可以通过名字把任务派发给这些子智能体。关于子智能体的优势及其在 SDK 层面的工作原理，请参阅子智能体文档。

1.12.1 目录结构

在你的项目根目录下创建一个subagents/目录。该目录下的每一个子文件夹都代表一个子智能体：

my-agent/ ├── deepagents.toml ├── AGENTS.md └── subagents/ ├── researcher/ │ ├── deepagents.toml # name, description, optional model override │ ├── AGENTS.md # subagent system prompt │ ├── skills/ # optional — subagent-specific skills │ │ └── analyze-market/ │ │ └── SKILL.md │ └── mcp.json # optional — HTTP/SSE MCP tools └── writer/ ├── deepagents.toml └── AGENTS.md

这段文档详细规定了子智能体文件夹里的“入职标准”。想让你的子智能体被系统识别并正常工作，必须满足以下文件要求：

子智能体目录文件规范

每个子智能体的子文件夹必须包含以下核心文件，也可以根据需要添加扩展文件：

必填文件 (核心身份)

选填文件 (扩展能力)

1.12.2 子智能体配置

[agent] name = "researcher" description = "Researches market trends, competitors, and target audiences" model = "google_genai:gemini-3.1-pro-preview"

1.12.3 继承机制

子 Agent 默认会继承主 Agent 的某些属性：

1.12.4 记忆隔离机制

每个子智能体都会获得一个专属且隔离的记忆命名空间，路径为/memories/subagents/<name>/。
在部署时，子智能体的AGENTS.md（系统提示词）和skills（技能）会被自动植入到这个命名空间中作为基础。

权限对照表

1.12.5 例子

这是一个面向市场（Go-to-Market）的智能体，它会将具体的调研工作委派给一个专业的子智能体来处理：

#deepagents.toml [agent] name = "gtm-strategist" model = "google_genai:gemini-3.1-pro-preview"

#subagents/researcher/deepagents.toml [agent] name = "researcher" description = "Researches market trends, competitors, and target audiences to inform GTM strategy" model = "google_genai:gemini-3.1-pro-preview"

#subagents/researcher/AGENTS.md # Market Researcher You are a market research specialist. Your job is to gather and synthesize market data to support go-to-market decisions. ## Focus Areas - Market sizing: TAM, SAM, SOM estimates - Competitor analysis: product positioning, pricing, market share - Audience segmentation: demographics, psychographics, buying behavior

1.13 限制

• MCP 配置：仅支持 HTTP/SSE 协议。打包时会自动拒绝stdio传输方式。
• 不支持自定义 Python 工具。请使用 MCP 服务器来封装并暴露你的自定义工具逻辑。

2 投产

本指南涵盖了将 Deep Agent 从本地原型转化为生产环境部署的关键考量。它将带你一步步完成以下工作：

• 规划记忆范围（决定智能体该记什么、忘什么）
• 配置执行环境（确保运行环境安全稳定）
• 添加护栏（防止智能体“发疯”或越界）
• 连接前端（让用户能真正用起来）

2.1 概览

Agent 依靠记忆和执行环境中的信息来完成任务。在生产环境中，信息的共享与访问主要由以下几个基本要素决定：

• 线程：指单次对话。默认情况下，消息历史和临时文件都仅限于该线程内，不会延续到下一次。
• 用户：指与 Agent 交互的人。记忆和文件可以是用户私有的，也可以是跨用户共享的。身份验证和授权由你的认证层提供。
• 助手：指配置好的 Agent 实例。记忆和文件可以绑定给某一个助手，也可以在所有助手间共享。

本页面将涵盖以下内容：

• LangSmith 部署：包含认证、Webhooks 和定时任务的托管基础设施。
• 生产考量：多租户、身份验证、凭证管理、异步处理和持久性。
• 记忆：如何在多次对话之间持久化信息。
• 执行环境：文件存储和代码执行。
• 护栏：速率限制、错误处理和数据隐私。
• 前端：如何将你的用户界面连接到已部署的 Agent。

2.2 langsmith部署

2.3 生产考虑

2.4 记忆

2.5 执行环境

2.6 护栏

2.7 前端