对于 AI 代理：可在 https://www.mongodb.com/zh-cn/docs/llms.txt 获取文档索引—通过在任何 URL 路径后添加 .md 可获取所有页面的 Markdown 版本。

@mongodb-js/代理-引擎-sdk-langgraph

用于 Atlas 代理引擎 的 Typescript 版 LangGraph 框架 SDK。它为 LangGraph 代理提供了平台安全、Atlas 审核和可观测性。还提供 Python 版本。

安装

npm install @mongodb-js/agent-engine-sdk-langgraph

架构

file
用途

src/index.ts

公共重新导出（App、LangGraphBaseAgent 等）

src/runtime.ts

App 类 — SDK 入口点

src/agent.ts

LangGraphBaseAgent 封装 CompiledStateGraph

src/query.ts

LangGraphQueryPlugin — 来自 MongoDBSaver 集合的会话摘要/消息

src/secure_llm.ts

SecureWrappedLLM — 通过代理路由 LLM 调用

src/messages.ts

LangChain ↔ 平台消息转换器

src/llm_adapter.ts

从 BaseChatModel 到平台 BaseLLM 的适配器

src/subagents.ts

子代理分发 + lc_agent_name 跟踪

src/node_logger_adapter.ts

LangGraph 回调 → NodeExecutionLogger

src/deep_agent.ts

deepagents 库包装器

src/deep_agent_task.ts

深度代理 task 工具调用解析

src/deep_agent_checkpointer.ts

将检查点标记为深度助手视图，保留深度助手自己的任务标识，而不是命名 Send 工作线程

src/durable_deep_agent.ts

持久性 task 分派：子操作路径 + 消息 ID 标记

src/session_fork.ts

会话分叉：原生副本 + 持久性 OE 分支，封装到 updateState

src/backends/toolpod.ts

AgentEngineToolPodBackend (sandbox backend)

依赖方向

下面的每一行都是一个依赖级别，从上到下（从实际的本地导入图表计算得出）：

index.tsruntime.tsagent.tssession_factory.tsdurable_session.tsdeep_agent.ts · execution_session.ts · secure_llm.ts · backends/toolpod.tsdeep_agent_checkpointer.ts · durable_deep_agent.ts · durable_subgraphs.ts · session_fork.tsplatform_checkpointer.tsworkflow_state.tsdurable_tools.ts · llm_adapter.ts · query.ts · suspend.ts · workflow_message.tsmessages.ts · checkpoint_branch.ts · checkpointer.ts · deep_agent_task.ts ·durable_message_identity.ts · node_logger_adapter.ts ·stopped_tool_call_middleware.ts · subagents.ts · thread_id.ts ·backends/tool_sandbox.ts · workflow_json.ts

在此树中，文件只能从下方行的文件导入。反向导入是错误。

配置

| Environment variable | Default | Description | | --- | --- | | MONGODB_URI | (unset) | MongoDB connection source for the checkpointer and query plugin in AER mode. | | MDB_AGENTIC_STORE_DB | mdb_store | Base name for the per-project MongoDB store used for LangGraph checkpoints in AER mode. Project scoping and discovery still apply unless overridden below. | | CHECKPOINT_DB_NAME | (unset) | Exact MongoDBSaver database name when set. Skips project scoping and discovery. Set it on the agent AER pod environment or a SecretRef to opt into a checkpoint database shared by dual-runtime agents. |

默认情况下，LangGraph 检查点 thread_id 为 session_id:workspace_id。代理可以注册 app.resolveThreadId((ctx) => ...)；其返回值在全新调用和恢复调用时会被原样使用，不会附加工作区后缀。自定义键对 Atlas 代理 引擎 /query/sessions* 历史记录不可见，该历史记录仍仅查找默认会话/工作区派生的键。绕过工作区范围的代理在检查点数据库中拥有冲突隔离性。该键必须能够在每一轮中从 RequestContext（包括会话和经过身份验证的身份）中重建。

读取仅限于作用域。会话历史记录将每个 Atlas 代理 引擎 session_id 扩展为其仅限工作区范围的复合键；一旦已知工作区范围，就不会查询裸露的无范围键，因为共享存储上的每个工作区都可以读取和写入裸露的键。因此，在存在范围划分之前写入的旧版检查点不会由历史记录终结点提供服务。空范围仅在显式未划分范围的运行时（本地开发和测试，没有 APP_ID）上是合法的。托管 AER 携带 REQUIRE_PROJECT_SCOPED_DB；如果那里缺少 APP_ID，则读取和写入将失败并关闭，而不是信任线路工作区或使用裸密钥。自定义密钥的生产采用者仍应将共享数据库内的检查点密钥唯一性视为代理拥有的。

import { App } from "@mongodb-js/agent-engine-sdk-langgraph";
const app = new App({ appName: "support-agent" });
app.resolveThreadId((ctx) => `${ctx.sessionId}__${ctx.userId}`);
app.entrypoint(() => {  // Build the LangGraph graph here and pass this saver to graph.compile().  const checkpointer = app.checkpointer();  return buildGraph().compile({ checkpointer });});
// On the agent AER pod, set CHECKPOINT_DB_NAME to the exact shared database.

工具故障

工具自身的故障遵循 LangGraph.js：股票ToolNode 将其报告给模型为 ToolMessage。工具调用期间的平台故障则不同，因为工具可能已经运行：示例，编排引擎的回答丢失，或者拒绝或从不确认工具的结果。平台故障会终止回合，而不是到达模型。下一个模型调用、下一个工具调用以及保存故障的步骤的任何保存（包括其待处理的写入）都会被拒绝，最后一步是该工具调用的回合会失败而不是完成，因此重试和下一回合将故障交给模型。

被拒绝的保存依赖于来自 app.checkpointer() 的平台检查指针。使用自己的保存程序（例如普通 MemorySaver）编译的图表仍然会在回合中失败，但该保存程序会保留该步骤，因此下一回合可以向模型显示失败情况。在客户端收到 ToolMessage 包含失败文本的工具步骤后，流式回合以平台失败为错误而结束。

但仍存在一个例外情况：当编排引擎无法访问远程工具的 Tool Pod 时，它会将此次故障记录为该工具自身的故障，因此模型会被告知该工具已发生故障。

与 Python SDK 的区别

功能
Python
Typescript
注意

MCP 工具服务器

✅

✅

agent-engine-runner-shared的 mcp_tools.ts/mcp_oauth.ts，发现功能已连接到 App。

langgraph.types.Overwrite

✅

⚠️ shim

LangGraph.js 中尚不支持 — 通过防御性解包处理。

技能

通过 App.deepAgent(..., { skills: [...] }) 传递父源目录。在运行时，deepagents 会通过配置的后端列出每个源，并仅发现其包含 SKILL.md 的直接子目录；发现过程不是递归的。deepagents 会跳过不可读或无法解析的 frontmatter 以及缺少 name 或 description 的技能；它会发出警告，但仍可能加载代理技能命名或目录名称违规。此 SDK 会转发声明的路径，而不会检查或过滤器它们。技能根目录是在 Tool Pod 启动时解析的，而不是在 SDK 导入时解析的，因此正常的静态 SDK 导入即可工作，无需导入顺序的变通方法。

开发中

# install dependenciesnpm install
# type-check only (no emit)npm run typecheck
# build distributablenpm run build
# unit testsnpm run test
# lintnpm run lint

编码规范

  • 严格的 Typescript (strict: true + noUncheckedIndexedAccess + exactOptionalPropertyTypes)。

  • Snake_case 文件名。

  • camelCase 函数/变量名。

  • PascalCase 类/类型名称。

  • 每个文件 = 单一职责（一个类或一个专注的概念）。

  • 公共接口依赖于抽象（依赖倒置原则）。

  • 绝不硬编码密钥。

后退
功能
来年
Session Fork 与 LangGraph Time-Travel
给本页内容打分