Overview
在本指南中，您可以学习；了解如何为Atlas Agent Engine代理启动本地开发环境。 agentengine dev 命令构建一个包含应用程序程序代码的 Docker映像，并在您的计算机上启动完整的代理堆栈，包括协调器、代理沙箱、工具沙箱和本地MongoDB实例。当环境运行时， CLI会打印服务 URL，以便您可以开发和测试代理。
先决条件
开始之前，请确保安装 agentengine CLI。要学习；了解有关如何安装CLI、进行身份验证和注册项目的更多信息，请参阅安装和身份验证。
可选配置设置
本节介绍可用于配置本地开发环境的可选设置。
启用内存
如果在 agent.yaml文件中设立了features.memory: true，则在启动本地环境之前将以下变量添加到 .env文件中：
VOYAGE_API_KEY：生成内存嵌入时必需的。MONGOMEM_DB_NAME：可选。内存服务器写入内容的MongoDB 数据库名称。默认为mdb_memory_<project-id>。
配置本地开发设置
您可以使用 dev.yaml文件覆盖本地服务端口分配，并在开发过程中打开或关闭本地MongoDB实例。将 dev.yaml文件放在与 agent.yaml文件相同的目录中。此文件是可选文件，平台不会将其添加到您的 .gitignore文件中，因此您可以提交并股票设置。
下表描述了可以包含在 dev.yaml文件中的字段：
字段 | 类型 | 必需 | 说明 |
|---|---|---|---|
| int (1–65535) | no | 平台服务的端口覆盖。有效的服务名称包括： |
| bool | no | 是否将本地MongoDB实例作为开发堆栈的一部分启动。默认为 |
| int | no | MongoDB在本地运行时侦听的端口。默认为 |
以下示例显示了设置所有可用字段的 dev.yaml文件：
services: playground: port: 3000 oe: port: 8000 aer: port: 8001 tool: port: 8002 mongodb: local: true port: 27017
启动本地开发
agentengine dev 命令支持两种初创企业模式：用于主动开发的热重载模式和用于测试类似生产拓扑结构的隔离模式。
热重载模式（推荐）
热重载模式在单个应用容器内运行所有代理服务，并将源代码直接挂载到其中。当您编辑文件时，监视文件会检测到更改并自动重新加载受影响的服务，而无需完全重建。
（可选）将VS Code作为开发容器附加。
如果使用 Visual Studio (VS) Code，请执行以下步骤以直接附加到运行的容器。这提供了具有完整 IntelliSense 和调试支持的集成开发体验。
在VS Code中安装 Dev 容器扩展。
当堆栈运行时，打开 Command Palette 并选择 Dev Containers:/ Reopen in Container。
VS Code连接到应用容器并重新加载其中的工作区。
隔离模式
您可以使用 --isolated 标志以隔离模式启动本地环境。隔离模式在单独的容器中启动每个代理服务，从而镜像生产拓扑结构。使用此模式来验证跨服务边界的行为或重现特定于生产的问题。由于代码不是从托管挂载的，因此您必须在更改代码后重新生成映像。
管理本地环境
使用以下 agentengine dev 命令管理运行环境。
查看日志
要从所有运行的服务流日志，运行以下命令：
agentengine dev logs
要从特定服务流日志，请将服务名称作为位置参数传递：
agentengine dev logs <service>
在单一存储库中，将 --all 传递给共享的全工作区堆栈的流日志：
agentengine dev logs --all
检查本地堆栈状态
agentengine dev status 命令显示本地撰写堆栈的当前状态，包括每个服务的状态和已发布的托管URL。以下示例显示了命令语法：
agentengine dev status [--workspace <name>] [--all] [--json]
下表描述了可用标志：
标记 | 说明 |
|---|---|
| （仅限 Monorepo）按名称定位特定代理，如根 |
| （仅限 Monorepo）以 all-workspaces堆栈为目标。 |
| 将机器可读状态对象打印到 stdout。包括 |
重新启动服务
agentengine dev restart 命令会重新启动热重载 app 和 oe 容器，而不重建映像。在更改托管上的依赖项后使用此选项。以下示例显示了命令语法：
agentengine dev restart [--workspace <name>]
此命令仅针对热重载堆栈。它不支持--all 或隔离模式。
添加新的依赖项
当您向 pyproject.toml文件添加依赖项时，如果 uv.lock文件已存在，本地开发堆栈可能不会安装该依赖项。当 uv.lock文件存在时，开发入口点会将环境与 --frozen 标志同步，从而解析锁文件中的依赖项，而不是 pyproject.toml文件中的依赖项。
要安装新的依赖项，运行以下命令以删除uv.lock文件并重新启动堆栈：
rm uv.lock agentengine dev stop agentengine dev up
或者，您可以运行以下命令来更新锁文件，然后再重新启动堆栈：
uv lock agentengine dev stop agentengine dev up
使用私有工件存储库
如果您的代理依赖于托管在私有项目存储库（例如 AWS CodeArtifact 上的私有 PyPI 或npm注册表）中的包，请在 agent.yaml文件的 artifact_repositories区块中声明它们。在热重载模式下，agentengine dev up 和 agentengine dev restart 命令会自动配置 type: pypi 条目的注册表凭证。 CLI不会自动配置npm条目。对于npm私有依赖项，请通过本地npm配置进行身份验证，例如项目级 .npmrc文件。
对于每个声明的 PyPI存储库，通过以下方式之一提供档案：
进程环境或
.env文件中的UV_INDEX_<NAME>_PASSWORD（以及可选的_USERNAME）变量。示例，对于名为corps-pypi的索引，设立UV_INDEX_CORPS_PYPI_PASSWORD。声明的
secret字段，从.env文件中读取。对于 AWS CodeArtifact索引，是指从活动 AWS 配置文件或 SSO 会话中创建的令牌。
如果没有凭证可解析已声明的存储库，则CLI失败并命名要检查的存储库和源。
要跳过自动配置并自行管理UV_INDEX_* 变量，运行以下命令：
agentengine dev up --no-artifact-auth
注意
如果声明 type: pypi 条目并以 --isolated 或 --all模式启动，则CLI会返回错误，而不是启动在依赖项安装时失败的容器。
要学习；了解artifact_repositories模式，请参阅代理 YAML 模式。要学习；了解私有工件存储库在云构建中的工作原理，请参阅私有工件存储库。
停止服务
要暂停本地环境而不删除容器，运行以下命令：
agentengine dev stop [--workspace <name>] [--all]
该命令会停止容器而不删除容器。再次运行 agentengine dev up 以恢复容器而无需重建。
重置本地状态
要停止所有容器并删除所有关联的卷和生成的运行时文件，运行以下命令：
agentengine dev clean [--workspace <name>] [--all]
警告
运行 agentengine dev clean 会永久删除存储在MongoDB Atlas Local 卷中的所有本地数据。在运行此命令之前，请备份所需的所有数据。
清理后，运行agentengine dev up 以重新生成文件并启动新的本地容器。
对远程 MCP 服务器进行身份验证
agentengine dev mcp auth 命令管理mcp.servers 下的 agent.yaml文件中配置的远程 MCP 服务器的 OAuth凭证。这些命令写入登录凭证写入 ~/.agentengine/mcp-oauth 的开发档案缓存，生成的 agentengine dev up 堆栈会自动挂载该目录。
每个项目和每个 MCP 端点的缓存都是独立的。从一个项目登录不会日志另一项目，因此您必须为每个项目运行一次 agentengine dev mcp auth login 命令。要学习；了解MCP 服务器的命名要求，请参阅服务器命名规则。
身份验证登录
使用 agentengine dev mcp auth login 命令打开服务器的提供商授权流程，并将凭证保存在开发缓存中，如以下示例所示：
agentengine dev mcp auth login <server> [--no-browser]
--no-browser 标志会打印登录URL ，而不是在浏览器中打开该URL 。
服务器公布的授权URL必须使用 https 方案。如果服务器公布使用任何其他方案的授权端点，该命令将停止并生成 Refused to open unauthorized MCP OAuth URL 错误。
身份验证状态
使用 agentengine dev mcp auth status 命令检查服务器是否存在缓存的凭证，如以下示例所示：
agentengine dev mcp auth status [server] [--check]
--check 标志使用缓存的凭证连接到 MCP服务器，并调用工具列表端点以确认服务器接受这些档案。
身份验证上传
Use the agentengine dev mcp auth upload command to base64-encode the local OAuth cache for a server and store it as a workspace secret named AGENTIC_MCP_OAUTH_B64_<SERVER>. This command exposes the authorization credentials to deployed agents.
以下示例显示了命令语法：
agentengine dev mcp auth upload <server> [--workspace-id <id>] [--sync]
--workspace-id 标志指定工作区ID，``同步`` 标志在上传密钥后立即重新加载活动部署中的密钥。
上传之前， CLI会检查缓存中记录的服务器URL是否与 agent.yaml文件中的URL匹配。如果缓存是为不同端点记录的，则CLI会拒绝上传并提示您再次运行agentengine dev mcp auth login 命令。
验证配置
agentengine agent validate 命令使用与构建管道相同的解析器和验证器在本地检查 agent.yaml文件。在构建之前运行它，以发现错别字、无效值和网络策略错误。
以下示例显示了命令语法：
agentengine agent validate [path] [--strict]
默认路径是 ./agent.yaml。传递显式路径以验证不同位置（例如单一存储库工作区）中的文件。
该命令返回以下退出代码：
退出代码 | 含义 |
|---|---|
|
|
| 验证失败。输出会标识无效字段。 |
| 文件或 I/O 错误。无法读取文件。 |
该命令不需要身份验证，并且可以在没有有效令牌的情况下在 CI 中运行。
当 artifact_repositories 为非空时，该命令会根据与 agent.yaml 位于同一目录中的项目工具对声明的索引名称进行交叉检查。对于Python助手，它显示为 pyproject.toml 和 uv.lock。对于 TypeScript 代理，它显示为 package.json、.npmrc 和 package-lock.json。允许在锁文件中使用未声明的私有 URL，因为档案注入是可选的。区块云构建的相同硬错误会停止验证并返回退出代码 1。
登录后，该命令还会打印针对缺失或范围错误的 artifact_repositories[].secret 值的非阻塞警告，包括在没有活动 agentengine init 上下文的情况下声明工作区范围条目时的 WORKSPACE_CONTEXT_NEEDED 警告。传递 --strict 可将这些警告视为退出代码 1。要学习；了解私有工件存储库在云构建中的工作原理，请参阅私有工件存储库。
注意
agentengine agent validate 命令是实验性的。随着验证器扩展到涵盖更多 agent.yaml 字段，其标志、输出格式和退出代码可能会发生变化。