/ /

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

TypeScript 中适用于Atlas Agent Engine 的 LangGraph框架SDK。它为 LangGraph 代理提供了平台安全性、Atlas 审核和可观察性。 Python版本也可用。

安装

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

架构

file	用途
`src/index.ts`	公开再导出（`App`、`LangGraphBaseAgent` 等）
`src/runtime.ts`	`App` class — 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`	深度代理检查点策略（允许适配器拥有的发送路由）
`src/durable_deep_agent.ts`	持久 `task` 调度：子操作路径 + 消息 ID 标记
`src/session_fork.ts`	会话分叉：原生副本 +持久性OE 分支，包装到 `updateState`
`src/backends/toolpod.ts`	`AgentEngineToolPodBackend` (sandbox backend)

依赖方向

下面的每一行从上到下都是一个依赖排名（根据实际的本地导入图表计算）：

index.ts
runtime.ts
agent.ts
session_factory.ts
durable_session.ts
deep_agent.ts · execution_session.ts · secure_llm.ts · backends/toolpod.ts
deep_agent_checkpointer.ts · durable_deep_agent.ts · durable_subgraphs.ts · session_fork.ts
platform_checkpointer.ts
workflow_state.ts
durable_tools.ts · llm_adapter.ts · query.ts · suspend.ts · workflow_message.ts
messages.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

文件只能从此树中较低行的文件导入。以其他方式导入是错误。

配置

环境变量	默认	说明
`MONGODB_URI`	（未设置）	AER模式下检查点和查询插件的MongoDB连接源。
`MDB_AGENTIC_STORE_DB`	`mdb_store`	用于 AER模式下 LangGraph 检查点的每个项目MongoDB存储的基本名称。除非在下面进行覆盖，否则项目范围界定和发现仍然应用。
`CHECKPOINT_DB_NAME`	（未设置）	设立后的 `MongoDBSaver`数据库确切名称。跳过项目范围界定和发现。在代理AER Pod 环境或 SecretRef 上进行设置，以选择加入由双运行时代理共享的检查点数据库。

默认下，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.

与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 dependencies
npm install
# type-check only (no emit)
npm run typecheck
# build distributable
npm run build
# unit tests
npm run test
# lint
npm run lint

编码标准

严格 TypeScript (strict: true + noUncheckedIndexedAccess + exactOptionalPropertyTypes)。
Snake_case 文件名。
camelCase 函数/变量名称。
PascalCase 类/类型名称。
每个文件= 单一职责（一个类或一个重点概念）。
公共表面依赖于接口（依赖倒置）。
永远没有硬编码的秘密。

后退

API 参考

来年

会话分叉与 LangGraph Time-Travel