企业官网建设流程全解析

deepagentsjs（包名deepagents）是一个"开箱即用"的 Agent 框架（agent harness），基于 LangGraph 构建，内置规划、文件系统工具、子智能体等能力。本文带你快速完成 deepagentsjs 智能体的部署与调试：先用几行代码invoke本地跑通，再用流式输出和 LangGraph Studio 调试界面观察每一步执行，最后把智能体部署成可被 UI 调用的 LangGraph 服务。

一、deepagentsjs 是什么：先认识这个智能体框架

deepagentsjs 的官方定位是 "The batteries-included agent harness"（电池全包式的智能体运行框架）。你不需要自己拼装提示词、工具和上下文管理，安装后立刻得到一个可用的智能体：

• 规划：write_todos工具，把复杂任务拆解成待办清单并跟踪进度
• 文件系统：read_file、write_file、edit_file、ls、glob、grep，用文件作为"工作记忆"
• 子智能体：task工具，把子任务委派给隔离上下文的子智能体并行处理
• 智能默认值：内置提示词与中间件，工具开箱即用

上图展示了 DeepAgent 的组成：用户提供指令和工具，中间的 LLM 可以调用规划工具（Planning Tool）、子智能体委派工具（Sub-Agent Delegation Tool）和文件系统工具（Filesystem Tools）。

核心源码位于 libs/deepagents/src/，入口函数createDeepAgent定义在 libs/deepagents/src/agent.ts，各种能力以"中间件（middleware）"形式挂载，位于 libs/deepagents/src/middleware/。

二、快速上手：安装 deepagentsjs 并第一次 invoke

一键安装步骤

在 Node.js 项目里执行（npm 7+ / pnpm 8+ 会自动安装 peer 依赖）：

npm install deepagents

⚠️ 如果你用 Yarn，需要手动补装 peer 依赖：yarn add @langchain/core @langchain/langgraph @langchain/langgraph-checkpoint @langchain/langgraph-sdk langchain langsmith

最小可运行示例

准备一个模型 API Key（如ANTHROPIC_API_KEY或OPENAI_API_KEY），然后：

import { createDeepAgent } from "deepagents"; const agent = createDeepAgent(); const result = await agent.invoke({ messages: [ { role: "user", content: "研究一下 LangGraph 并把摘要写入 summary.md" }, ], });

这就是从 0 到 1 的完整流程：智能体自动拆解任务、写文件、调用工具，最后返回结果。想要自定义模型、工具和提示词，只需传入配置对象（model、tools、systemPrompt），完整示例见 examples/research/research-agent.ts——它构建了一个带联网搜索工具和"研究员/编辑"两个子智能体的深度调研智能体。

小贴士：createDeepAgent返回的是一个编译好的 LangGraph 图，所以invoke、stream、检查点（checkpointers）、Studio 调试这些 LangGraph 原生能力全部直接可用。

三、调试技巧：用流式输出观察每一步执行

生产级智能体通常要跑几分钟、调用几十次工具，invoke的"黑盒等待"很难定位问题。debug deepagentsjs 智能体最实用的方法是流式输出：

for await (const [namespace, chunk] of await agent.stream( { messages: [{ role: "user", content: "调研量子计算进展" }] }, { streamMode: "updates", subgraphs: true }, )) { // namespace 为空是主智能体，非空则是子智能体 console.log(namespace.length ? `[subagent: ${namespace.join("|")}]` : "[main agent]", chunk); }

两个关键参数：

• streamMode: "updates"：每次状态更新时推一个事件，方便看每个节点（模型调用、工具执行）
• subgraphs: true：连子智能体内部的事件也一起收到，namespace告诉你事件来自哪个子图

仓库里提供了多个可直接运行的调试示例：

• examples/streaming/basic.ts：主/子智能体事件区分的最简写法
• examples/streaming/progress.ts：跟踪子智能体执行进度
• 更多流式模式（分 token、按类型过滤、生命周期事件等）见 examples/streaming/ 目录

四、部署到 LangGraph Studio：可视化调试智能体

本地终端看日志终究有限。deepagentsjs 与 LangGraph 生态深度集成，可以一键把智能体部署到 LangGraph 的本地开发环境，在LangGraph Studio里用可视化界面逐步调试：消息流、节点跳转、状态变更一目了然。

最快配置方法：三步部署

第 1 步：确认智能体以命名导出形式存在。例如 examples/research/research-agent.ts 导出了agent。

第 2 步：在同目录编写langgraph.json声明图入口。以研究示例为例（examples/research/langgraph.json）：

{ "dependencies": ["../"], "graphs": { "research": "./research-agent.ts:agent" }, "env": ".env" }

其中"graphs"把图 ID 映射到文件路径:导出名，"env"指定环境变量文件位置。

第 3 步：在项目根目录启动开发服务器：

npx @langchain/langgraph-cli dev -c examples/research/langgraph.json

启动后 CLI 会自动打开 LangGraph Studio（或按提示打开本地地址），选择research这个 assistant，就能在界面上直接对话、单步查看每个节点、检查检查点状态。

进阶：多智能体部署

生产场景中常见"监督者 + 多个子智能体"架构。示例 examples/async-subagents/parallel-research/ 展示了完整玩法：

• langgraph.json 同时注册supervisor（监督者）和researcher（研究员）两个图
• 运行npx @langchain/langgraph-cli dev -c examples/async-subagents/parallel-research/langgraph.json启动
• 前端 UI（Vite + React，使用@langchain/langgraph-sdk流式通信）通过 supervisor.ts 与智能体交互，并展示并行研究员卡片

相关部署细节可参考 examples/async-subagents/parallel-research/README.md。

五、生产部署检查清单 📋

把 deepagentsjs 智能体推向生产前，建议逐项确认：

1. 环境变量管理：API Key、搜索服务 Key 等统一放.env，在langgraph.json中通过"env"字段声明，不要硬编码
2. 模型配置：通过model参数切换到生产级模型（如 examples/research/research-agent.ts 使用 Claude Sonnet 并设置temperature: 0保证输出稳定）
3. 可观测性：接入 LangSmith 追踪每次运行的完整轨迹，方便线上问题回溯；LangSmith 也是官方推荐的开发、调试、部署 AI 智能体平台
4. 执行边界：deepagentsjs 遵循"信任 LLM"模型，智能体可以做工具允许的一切操作——务必在工具/沙箱层面设限。项目提供多种后端选择：libs/deepagents/src/backends/ 下有state、filesystem、store等实现，沙箱方案可参考 examples/sandbox/（Deno、Daytona、Modal 等）
5. 权限控制：需要限制智能体能读/写哪些路径时，可配置 permissions，源码见 libs/deepagents/src/permissions/
6. 人类审批（HITL）：对高风险操作加入 human-in-the-loop 中断与审批，相关测试用例见 libs/deepagents/src/middleware/hitl.int.test.ts
7. 回归评估：上线前用内置的评估套件跑一遍，覆盖 todos、子智能体、记忆、工具选择等场景，见 evals/ 目录

六、总结

回顾一下这条从invoke到 LangGraph Studio 的完整路径：

deepagentsjs 的价值在于把"智能体框架"里最琐碎的部分（规划、文件记忆、子智能体委派、上下文摘要）都做成了默认能力，而它返回原生 LangGraph 图的设计，又让调试与部署平滑接入 LangGraph Studio、LangGraph Platform 等整套生产工具链。从invoke一行代码起步，到 Studio 可视化调试，再到可被 UI 调用的服务，deepagentsjs 的每一步都有现成示例可参考——接下来建议直接打开 examples/ 目录，选一个最接近你业务的示例跑起来。