代理合同参考

Overview

在本指南中，您可以学习；了解在MongoDB Atlas助手引擎上运行代理的最低要求。本指南介绍了Atlas Agent Engine 发现和运行代理所需的文件、agent.yaml模式以及兼容的框架和 LLM 提供程序。

代理不会实现自己的HTTP端点。 Atlas Agent Engine 在与代理沙箱相同的进程中导入代理。

最小可部署代理

最小可部署代理由两个文件组成：

my_agent/main.py：定义 App对象和图表。
agent.yaml：指向 my_agent/main.py 中定义的 App对象。

以下示例显示了一个最小的 main.py文件，其中定义了名为 my-agent 的 App对象并构建了代理图表：

my_agent/main.py

from agent_engine_sdk_langgraph import App
from langgraph.graph import StateGraph, MessagesState
from langgraph.prebuilt import ToolNode
from langchain_openai import ChatOpenAI
app = App(app_name="my-agent")
@app.tool()
def lookup(query: str) -> str:
    """Search the knowledge base."""
    return f"result for {query}"
@app.entrypoint
def build_agent():
    llm = app.llm(ChatOpenAI(model="gpt-4o-mini"))
    tools = app.get_tools()
    def call_model(state: MessagesState):
        return {"messages": [llm.invoke(state["messages"])]}
    graph = StateGraph(MessagesState)
    graph.add_node("agent", call_model)
    graph.add_node("tools", ToolNode(tools))
    graph.set_entry_point("agent")
    graph.add_edge("tools", "agent")
    return graph.compile(checkpointer=app.checkpointer())
app.run()

以下示例显示了一个最小的 agent.yaml文件：

agent.yaml

entrypoint: my_agent.main:app

在 main.py文件中，您必须执行以下组件：

在模块级别定义一个 App对象，通常命名为 app。
使用 @app.entrypoint 函数注册应用的入口点。
使用 @app.tool(...) 函数注册工具。
调用本模块底部的 app.run() 函数。

在 agent.yaml文件中，您必须使用 <module.path>:<attribute> 格式将 entrypoint YAML 密钥设立为 App对象。

代理指南

请遵循以下准则，确保代理通过Atlas 审核记录、策略执行以及暂停或恢复代理执行等平台功能正常工作：

通过 app.tool(...) 和 app.llm(...) 函数路由工具和 LLM 调用。

当您恢复暂停的执行时， Atlas助手引擎使用这些包装器进行Atlas 审核记录、策略执行以及重放工具和 LLM 调用。在这些包装器之外进行的调用不会被Atlas助手引擎审核，并且在恢复执行后不会正确重放。
保持图表状态JSON/ BSON可序列化。

代理沙箱是短暂的，因此Atlas代理引擎会在暂停和恢复操作之间将检查点状态保存到MongoDB 。图表状态中的每个值都必须可序列化为JSON或BSON ，检查点才能成功，例如基元、列表、字典、datetime、Enum 和 LangChain BaseMessage 子类。在没有序列化支持的情况下，请勿在图表状态中存储lambda、闭包、文件句柄、数据库连接或自定义类。
致电 app.llm(...) 仅当入口点位于调用堆栈上时才起作用。

当您从模块顶层代码、工具体或入口点未调用的任何其他函数中调用 app.llm(...) 时， Atlas助手引擎会生成错误，标识包含无效调用的文件和行。要学习；了解更多信息，请参阅执行生命周期。

执行生命周期

Atlas Agent Engine 在以下进程生命周期的定义点加载并运行代理代码：

代理沙盒，运行代理代码并构建图表。
工具沙箱，在与代理沙箱不同的进程中运行远程工具体。

注意

Python和 TypeScript SDK 的执行生命周期是相同的。

本节介绍代理代码的各个部分在每个进程中运行的时间，并使用以下术语：

模块顶层代码是代理源文件中的代码，在导入时在任何函数体之外运行。
入口点是用 @app.entrypoint 修饰的函数。
本地工具仅在代理沙箱自己的进程内运行。默认下，您向 @app.tool() 装饰器注册的每个工具都是本地工具。
远程工具是指通过在 agent.yaml文件的 sandboxes.tool.tools字段中列出来分配给工具沙箱的工具。代理沙箱解释远程工具，但远程工具体在工具沙箱中运行。

初创企业

在代理沙箱和工具沙箱进程中， Atlas代理引擎在初创企业时执行以下操作：

加载代理的源文件。
运行模块顶层代码。

平台在初创企业时不会执行以下操作：

运行您的入口点。
运行工具体。 Atlas Agent Engine 解释工具定义以注册其签名，但不运行它们。

模块顶层代码可以访问权限进程范围的密钥，例如 MONGODB_URI 和 MCP OAuth凭证，因为这些值在进程的整个生命周期内可用。 Atlas Agent Engine 还会在沙箱启动时设置您为沙箱声明的密钥，包括 LLM API密钥。因此，沙箱中的模块顶层代码可以访问权限该沙箱的密钥。

代理沙盒调用

在代理沙箱中， Atlas代理引擎在调用期间执行以下操作：

运行一次入口点。
在代理沙箱自己的进程中执行本地工具体。

在代理沙箱调用期间，平台不会执行以下操作：

运行远程工具体。代理沙箱解释它们，然后将调用分派给工具沙箱。

工具沙盒调用

在工具沙箱中， Atlas助手引擎在调用期间执行以下动作：

在每个沙箱生命周期内延迟加载入口点，由第一个 invoke_llm 调用触发。此加载仅会发现您的 app.llm(...) 注册。
解释远程工具主体，然后在编排引擎将工具调用路由到沙箱时按需运行这些工具主体。

在工具沙箱调用期间， Atlas助手引擎不会执行以下操作：

执行图表。
运行本地工具体。

Atlas Agent Engine 将您在 sandboxes.tool.secrets字段中声明的密钥作为工具沙箱中的环境变量传递。在工具沙箱中运行的每个远程工具体都可以读取这些环境变量。要学习；了解有关沙箱如何在工具之间股票密钥的更多信息，请参阅MongoDB Atlas助手引擎限制。

生命周期摘要

下表汇总了代码的每个部分在每个执行进程和阶段的运行时间：

阶段	处理	顶层代码	入口点	远程工具体	本地工具体
初创企业	Agent Sandbox	执行	未执行	仅解释型	仅解释型
初创企业	工具沙箱	执行	未执行	仅解释型	仅解释型
每次调用	Agent Sandbox	未执行	执行一次	已解释，已分派到工具沙箱	执行
第一次 `invoke_llm` 调用	工具沙箱	未执行	执行一次，以注册 `app.llm(...)` 调用	未执行	未执行
每次工具调用	工具沙箱	未执行	未执行	按需执行	未执行

代理 YAML 模式

agent.yaml文件配置Atlas助手引擎如何发现和运行您的代理。它支持两种格式：单代理清单（适用于包含一个代理的存储库）和单一存储库清单（适用于包含多个代理的存储库）。

单一代理清单

下表描述了单代理 agent.yaml文件的可用字段。 Required 列指示最小 agent.yaml文件是否为字段。

字段	类型	必需	说明和限制
`entrypoint`	字符串	是	`module.path:attribute` 格式的模块路径和属性。必须匹配正则表达式模式`^[\w.]+:[\w]+$`，其中左侧是以点分隔的模块路径，右侧是属性名称。
`name`	字符串	no	代理名称。只能包含小写字母数字和连字符。没有前导或尾随连字符。
`description`	字符串	no	代理的描述。最多 500 个字符。
`agent_card.summary`	字符串	no	代理用途摘要。显示在用户界面中。
`agent_card.capabilities`	list[string]	no	描述代理可以执行的操作的标签。显示在用户界面中。
`features.guardrails`	bool	no	当 `true` 时，启用护栏集成。
`features.memory`	bool	no	当 `true` 时，将内存服务器作为单独的服务启动。代理通过 `app.memory`客户端访问权限内存。需要设立`VOYAGE_API_KEY`。
`features.deep_agent`	bool	no	当 `true` 时，启用深度代理工厂方法。调用 `app.deep_agent()` 或 `app.deepAgent()` 的图表必须设立此字段，否则该方法会在构建时引发错误。要学习；了解更多信息，请参阅构建深度助手。
`features.playground`	bool	no	当为 `false` 时， Atlas助手引擎不会为代理预配 Playground用户界面。对于不生成可预览的会话输出的代理，请使用此字段，并改为使用API来调用它们。默认为 `true`。
`features.use_custom_parser`	bool	no	当 `true` 时，启用自定义流输出。需要向 `@app.output_parser` 装饰器注册的 `OutputParser`。如果将此字段设立为 `true` 而不注册解析器，则在代理启动时，调用将失败。要学习；了解更多信息，请参阅将自定义流输出添加到代理。
`mcp.servers.<name>.transport`	字符串	当定义了 `mcp.servers.<name>` 时	用于远程 MCP服务器连接的传输协议。接受值：`streamable_http`。要学习；了解更多信息，请参阅使用远程 MCP 服务器。
`mcp.servers.<name>.url`	字符串	当定义了 `mcp.servers.<name>` 时	远程 MCP服务器端点的URL 。
`mcp.servers.<name>.headers`	map[string, string]	no	静态HTTP 头部随每个请求发送到 MCP服务器。
`mcp.servers.<name>.auth.type`	字符串	是	身份验证类型。接受的值为 `bearer_env` 和 `oauth`。
`mcp.servers.<name>.auth.token_env`	字符串	当 `auth.type` 为 `bearer_env` 时	保存持有者令牌的环境变量的名称。该变量必须在 `.env`文件中设立。
`mcp.servers.<name>.auth.scope`	字符串	当 `auth.type` 为 `oauth` 时	在授权流程中请求的以空格分隔的 OAuth 范围。
`mcp.servers.<name>.auth.client_name`	字符串	no	同意屏幕上显示的 OAuth客户端的人类可读名称。
`mcp.servers.<name>.allowed_tools`	list[string]	no	要向代理公开的远程 MCP 工具名称的允许列表。设立为后，平台仅注册列出的工具，而忽略服务器返回的所有其他工具。省略时，平台会公开服务器返回的所有工具。使用此字段可将工具界面限制为仅使用代理所需的工具。
`mcp.servers.<name>.timeout_seconds`	int	no	每次 MCP 工具调用的请求超时（以秒为单位）。默认为 `30`。
`scaling.replicas`	int	no	部署的静态 Pod 计数。 Atlas Agent Engine 将此值分别应用于代理沙箱和工具沙箱。每个会话保留一个代理沙箱和一个工具沙箱（如果已配置），因此该值是该部署可以提供服务的并发会话数。接受 1 到 512 之间的值。省略时默认为 4。
`scaling.agent_idle_ttl_seconds`	int	no	在Atlas助手引擎为其他会话回收其保留的助手沙箱之前，空闲会话保留其保留的代理沙箱的时间（以秒为单位）。接受 1 到 86400 之间的值。省略时默认为 600。 `scaling.agent_idle_ttl_seconds` 是该字段的旧别名。
`scaling.tool_idle_ttl_seconds`	int	no	在Atlas Agent Engine 回收空闲会话之前，空闲会话保留其保留的工具沙箱的时间（以秒为单位）。接受 1 到 86400 之间的值。默认为 `scaling.agent_idle_ttl_seconds` 值。
`sandboxes`	映射	是	配置运行代理及其工具的命名沙箱。 Atlas Agent Engine 支持两个命名沙箱：`agent` 和 `tool`。您无法定义其他沙箱，并且Atlas Agent Engine 会拒绝分配给多个沙箱的工具。要学习；了解沙箱如何在工具之间股票密钥和出口目的地，请参阅MongoDB Atlas助手引擎限制。
`sandboxes.agent`	映射	是	代理沙箱的配置，即运行代理代码的硬件隔离沙箱。
`sandboxes.agent.secrets`	list[string]	no	代理沙箱可用的密钥名称或匹配密钥名称的全局模式列表。您可以使用 `*` 匹配所有密钥。 MONGODB_URI 自动可用，无需声明。
`sandboxes.agent.tools`	list[string]	no	要在代理沙箱中运行的工具名称列表或与工具名称匹配的 glob 模式。您可以使用 `*` 来匹配所有工具。不匹配沙箱的工具默认在代理沙箱中运行。
`sandboxes.agent.network`	映射	no	代理沙箱的网络策略，包括出站出口规则。要学习；了解更多信息，请参阅管理网络出口策略。
`sandboxes.tool`	映射	no	工具沙箱的配置，即运行远程工具体的硬件隔离沙箱。
`sandboxes.tool.secrets`	list[string]	no	可供工具沙箱使用的密钥名称或匹配密钥名称的 glob 模式列表。您可以使用 `*` 匹配所有密钥。 MONGODB_URI 自动可用，无需声明。
`sandboxes.tool.tools`	list[string]	no	要在工具沙箱中运行的工具名称列表或与工具名称匹配的 glob 模式。您可以使用 `*` 来匹配所有工具。要从工具体调用 LLM，请在此列表中包含 `invoke_llm` 工具，并在 `sandboxes.tool.secrets` 下声明您的 LLM提供商程序API密钥。
`artifact_repositories`	list[mapping]	no	为托管构建声明私有包注册表。每个条目都将注册表索引名称映射到保存其档案的Atlas Agent Engine 密钥。 Atlas Agent Engine 仅在构建时注入档案，不会将其公开给运行的Pod。注册表 URL 存在于项目工具（`pyproject.toml`、`package.json` 或 `.npmrc`）中，而不是在此区块中。如果省略此字段， Atlas Agent Engine 将使用现有工具配置不变地解析公共注册表中的依赖项。
`artifact_repositories[].name`	字符串	是	条目的唯一标识符。对于 PyPI 条目，必须与 `pyproject.toml` 中的 `[[tool.uv.index]]` 名称匹配。对于npm条目，验证首先将 `npm_scope` 与 `.npmrc` 中的限定范围的注册表进行匹配，然后再使用 `name`。必须匹配 `^[a-z][a-z0-9-]*$` 并在列表中保持唯一。
`artifact_repositories[].type`	字符串	是	存储库类型。接受的值为 `pypi` 和 `npm`。
`artifact_repositories[].secret`	字符串	是	保存档案的Atlas Agent Engine 密钥的名称。必须匹配 `^[A-Z][A-Z0-9_]{0,127}$`。
`artifact_repositories[].scope`	字符串	no	秘密范围。接受的值为 `project` 和 `workspace`。默认为 `project`。
`artifact_repositories[].auth`	字符串	no	身份验证方法。接受的值为 `token` 和 `basic`。默认为 `token`。
`artifact_repositories[].username`	字符串	no	用于注册表身份验证的用户名。当 `auth` 为 `basic` 时为必填项。对于省略此字段的 PyPI 令牌身份验证，默认`__token__`。 npm token auth 不使用用户名。
`artifact_repositories[].npm_scope`	字符串	no	映射到此注册表的npm作用域，例如 `@acme`。提供时，它是与 `.npmrc` 中限定作用域的注册表匹配的密钥。仅当 `type` 为 `npm` 时有效。

artifact_repositories 凭证仅在构建时解析。要学习；了解私有项目存储库在云构建和本地开发中的工作原理，请参阅构建代理映像并在本地运行代理。

每个会话在其生命周期内保留自己的代理和工具沙箱， Atlas Agent Engine 会重置沙箱，然后再将沙箱分配给新会话。因此，一个会话写入沙箱的项目对后续会话不可见。

Atlas Agent Engine 在构建时对 scaling 值进行快照，因此更改会在下一次构建和部署生效。更改平台默认不会调整已部署工作区的大小。工作区会保留最近构建中的硬件隔离沙箱计数，直到您再次构建和部署它。空闲生存时间 (TTL) 值应用整个项目。当一个项目中的多个代理设立不同的值时，该项目将应用最近部署的代理中的值。

注意

您必须在与 agent.yaml文件位于同一目录中的单独 dev.yaml文件中配置本地开发设置，而不是在 agent.yaml 本身中。要学习；了解更多信息，请参阅配置本地开发设置。

以下示例显示了一个包含服务端口覆盖、功能标志、密钥访问权限限制和私有项目存储库的agent.yaml文件：

name: my-agent
entrypoint: my_agent.main:app
features:
  guardrails: true
scaling:
  replicas: 4
  agent_idle_ttl_seconds: 900
  tool_idle_ttl_seconds: 300
sandboxes:
  agent:
    secrets: ["*"]
    tools: []
  tool:
    secrets:
      - SEARCH_API_KEY
      - ANTHROPIC_API_KEY
    tools:
      - my_search_tool
      - invoke_llm
artifact_repositories:
  - name: corps-pypi
    type: pypi
    secret: ARTIFACT_REPO_CORPS_PYPI_TOKEN
    username: aws
    scope: project

Monorepo 清单

如果您的存储库包含多个代理，请使用顶级 agents: 列表在单个 agent.yaml文件中定义它们。 Atlas Agent Engine 会检测到此列表，并将该文件视为单一存储库清单，而不是单代理配置。以下 agent.yaml文件是具有多个代理的单一存储库清单的示例：

agents:
  - name: chat
    path: agents/chat
  - name: research
    path: agents/research

字段	类型	必需	说明
`agents[].name`	字符串	是	代理名称。只能包含小写字母数字和连字符。没有前导或尾随连字符。在列表中必须是唯一的。
`agents[].path`	字符串	是	代理子目录的路径，相对于存储库根目录。该路径不能引用存储库之外的位置。

每个代理子目录必须包含自己的单代理 agent.yaml文件。

.env 要求

如果在 dev.yaml文件中将 services.mongodb.local设立为 false，则必须在 .env文件中设立MONGODB_URI 环境变量，才能成功部署代理。

您的代理还需要 .env文件中的 LLM API密钥才能在运行时进程请求。平台本身不验证或要求特定的 LLM凭证，但如果没有这些凭证，代理将在运行时失败。使用 <PROVIDER>_API_KEY 语法为您的 LLM提供商设立环境变量。

框架和 LLM 提供商

本节介绍可与Atlas Agent Engine 一起使用的框架和 LLM 提供程序。

框架

Atlas Agent Engine 通过 agent-engine-sdk-langgraph包支持 LangGraph 和 LangChain。框架适配器可处理以下集成点：

interrupt() 用于在继续之前暂停代理执行以供人工查看
MongoDBSaver 用于将代理的图表状态保存到MongoDB ，以便在恢复暂停的执行时将其恢复
LangChainInstrumentor 用于在执行期间记录 LLM 和工具调用，以便进行调试和监控

法学硕士提供者

您可以在代理中使用任何 LLM提供商。要使用模型，请为提供商构造一个 LangChain BaseChatModel 并将其传递给 app.llm() 方法。 Atlas Agent Engine 通过业务流程引擎路由该调用。

下表显示了常见的提供商程序示例及其环境密钥和 LangChain 类：

提供商	环境键	LangChain 类
OpenAI	`OPENAI_API_KEY`	`ChatOpenAI`
人择	`ANTHROPIC_API_KEY`	`ChatAnthropic`
Gemini	`GEMINI_API_KEY` （可选：`GEMINI_MODEL`）	`ChatGoogleGenerativeAI`
Cerebras	`CEREBRAS_API_KEY` （可选：`CEREBRAS_MODEL`）	`ChatCerebras`

以下代码示例展示了如何为 app.llm() 方法配置每个提供商：

# OpenAI
from langchain_openai import ChatOpenAI
llm = app.llm(ChatOpenAI(model="gpt-4o-mini"))
# Anthropic
from langchain_anthropic import ChatAnthropic
llm = app.llm(ChatAnthropic(model="claude-sonnet-4-5"))
# Gemini
from langchain_google_genai import ChatGoogleGenerativeAI
llm = app.llm(ChatGoogleGenerativeAI(model="gemini-2.5-flash-lite"))
# Cerebras
from langchain_cerebras import ChatCerebras
llm = app.llm(ChatCerebras(model="qwen-3-235b-a22b-instruct-2507"))

后续步骤

要学习；了解如何验证和调用已部署的代理，请参阅“调用代理”指南。

来年

公开预览版限制