内容提要
文章介绍如何将LangGraph旅行代理迁移到MongoDB Atlas Agent Engine。该引擎提供托管运行时、长期记忆以及审计与治理层。迁移只需少量代码改动:用App类包装代理,通过app.llm()路由模型调用,用@app.tool()注册工具,替换检查点,添加agent.yaml配置,启用记忆功能,并通过CLI部署。代理核心逻辑保持不变,仍可访问原有MongoDB数据,同时获得沙箱隔离、策略与内容护栏。
延伸解读
迁移成本低,但需注意配置细节
文章展示的迁移只需少量代码改动:用App类包装代理、通过app.llm()路由模型调用、用@app.tool()注册工具、替换检查点等。核心业务逻辑无需重写,这降低了从自建运行时转向托管服务的门槛。但需注意,agent.yaml和project-config.yaml中的配置项(如沙箱网络策略、MCP工具白名单、记忆提取类型)需要根据实际需求仔细设置,否则可能影响代理的功能或安全性。
治理与护栏是托管服务的核心价值
Agent Engine提供了策略和内容护栏,管理员可以限制代理可用的模型、工具、LLM调用次数和token用量,并能对输入输出进行正则匹配以阻断或修改内容。例如,文章中的策略将代理限制为只读工具,防止其执行预订操作;护栏可阻止含信用卡号的输入到达模型。这些控制层无法由模型自身吸收,适合需要审计和合规的生产环境。
长期记忆需额外配置与代码适配
启用长期记忆不仅要在agent.yaml中设置features.memory为true,还需在project-config.yaml中配置记忆提取所用的LLM、嵌入模型(如Voyage AI)以及记忆类型(语义、情景、偏好)。此外,代理代码中需添加记忆召回步骤,将检索到的记忆作为上下文传给LLM。这意味着记忆功能并非开箱即用,需要根据业务场景调整提取和召回逻辑。
沙箱隔离与网络策略增强安全性
Agent Engine将代理代码和工具调用分别运行在独立的沙箱中,每个沙箱可配置可访问的密钥和网络出口白名单。例如,工具沙箱仅允许访问OpenAI和MongoDB相关域名。这种设计限制了潜在攻击面,但也要求开发者在agent.yaml中精确声明依赖的外部服务,否则代理可能因网络限制而无法正常工作。
Q&A
MongoDB Atlas Agent Engine 是什么?它主要解决什么问题?
MongoDB Atlas Agent Engine 是一个托管服务,为 AI 代理提供控制层,包括身份、托管运行时、长期记忆、审计和护栏。它旨在解决代理在生产环境中持久化、约束和记录模型工作的问题,这些控制层无法被模型吸收,必须存在于模型之外。
将 LangGraph 代理迁移到 Agent Engine 需要修改哪些代码?
迁移主要涉及少量代码改动:用 App 类包装代理;用 app.llm() 包装 LLM 调用;用 @app.tool() 注册工具;用 app.checkpointer() 替换原有检查点;添加 @app.entrypoint 装饰器标记入口;调用 app.run() 启动运行时。代理的核心逻辑和工具代码保持不变。
Agent Engine 如何为代理提供长期记忆?需要哪些配置?
Agent Engine 内置记忆服务。启用长期记忆需三步:在 agent.yaml 中设置 features.memory 为 true;在 project-config.yaml 中配置记忆提取(如使用 gpt-5.4-mini 提取语义、情景、偏好三类记忆)和 Voyage AI 嵌入模型(如 voyage-4-large);在代理代码中调用 app.memory.build_context() 检索相关记忆并传入 LLM 上下文。
Agent Engine 的治理策略和内容护栏分别控制什么?
治理策略控制代理能做什么,例如限制可使用的模型和工具、每次执行的 LLM 调用次数和 token 数量。内容护栏控制进出 LLM 的内容,通过正则表达式匹配输入输出,并执行阻止、修改或送审操作。
部署代理到 Agent Engine 需要哪些前提条件?
需要:注册 Atlas 账户并创建 Flex 或 M10+ 集群获取连接字符串;获取 LLM 提供商的 API 密钥(如 OpenAI);安装 agentengine CLI 并认证 Atlas 账户;安装 uv 和 Docker;若使用 MongoDB Atlas Managed MCP Server,还需创建 MCP 配置并获取客户端 ID 和密钥。
agent.yaml 文件在 Agent Engine 中起什么作用?主要配置项有哪些?
agent.yaml 用于配置 Agent Engine 如何发现和运行代理。主要配置项包括:name(应用名称)、entrypoint(入口点,格式为 module.path:attribute)、framework(如 langgraph)、mcp(远程 MCP 服务器及允许的工具)、sandboxes(代理和工具沙箱的密钥、工具及网络出口规则)。