Overview
在本指南中，您可以学习；了解如何设立单一存储库以管理单个存储库中的多个代理。单一存储库在存储库根目录使用一个 agent.yaml文件，其中列出了每个代理的名称和子目录路径。当根 agent.yaml 包含 agents 密钥而不是 entrypoint 密钥时， CLI会自动检测单一存储库格式。
目录结构
单一存储库需要一个根 agent.yaml 和每个代理的子目录中的单代理 agent.yaml。以下示例显示了包含两个代理的单一存储库的文件结构：
my-repo/ ├── agent.yaml # Monorepo root file ├── .env # Shared secrets for the local dev stack ├── pyproject.toml # Shared Python dependencies (optional) ├── agents/ │ ├── chat/ │ │ ├── agent.yaml # Per-agent configuration file with entrypoint │ │ ├── pyproject.toml │ │ ├── .env # Per-agent secrets │ │ └── src/ │ └── search/ │ ├── agent.yaml # Per-agent configuration file with entrypoint │ ├── pyproject.toml │ ├── .env # Per-agent secrets │ └── src/ └── shared/ # Shared libraries, included in all builds
配置 Monorepo
以下步骤说明如何配置所需的单一存储库文件并初始化单一存储库。
配置根 agent.yaml文件。
在存储库根目录创建一个 agent.yaml文件。使用 agents 列表声明每个代理的名称和路径。请勿在根文件中包含 entrypoint字段。
agents 列表中的每个条目都需要以下字段：
字段 | 必需 | 说明 |
|---|---|---|
| 是 | 代理标识符。将此字段设置为带连字符的小写字母数字值。请勿使用前导或尾随连字符，并确保该名称在单一存储库中是唯一的。 |
| 是 | 从存储库根目录到代理目录的相对路径。路径不能是绝对路径，也不能使用 |
以下示例agent.yaml文件配置了一个具有两个名为 chat 和 search 的代理的单一存储库：
agents: - name: chat path: agents/chat - name: search path: agents/search
配置每个代理的 agent.yaml文件。
在每个代理子目录中，创建一个使用单代理格式的 agent.yaml文件。该文件必须包含一个指向代理的应用程序对象的 entrypoint字段和一个定义代理工具运行内容以及可以访问权限哪些密钥的 sandboxes字段。要查看所有可用字段，请参阅创建项目指南中的代理.yaml 字段列表。
以下示例agent.yaml文件配置 chat代理：
entrypoint: chat_agent.graph:app name: chat sandboxes: agent: secrets: ["*"] tools: [] tool: secrets: ["*"] tools: []
以下示例agent.yaml文件配置 search代理：
entrypoint: search_agent.graph:app name: search sandboxes: agent: secrets: ["*"] tools: [] tool: secrets: ["*"] tools: []
agent 沙箱适用于必须在代理上运行的工具，例如中断工具。 tool 沙箱适用于与代理分开运行的工具。在其 tools字段下列出每个沙箱的工具。在每个沙箱的 secrets字段下配置密钥访问权限。当沙箱应仅接收选定的密钥时，将 ["*"] 替换为特定密钥名称的列表。
重要
每个子目录还必须包含一个 pyproject.toml文件，用于声明代理的Python依赖项。该文件必须设立[project].name 密钥，并包含用于设置 requires 和 build-backend 密钥的 [build-system] 表。要生成满足这些要求的文件，请在代理子目录中运行uv init --package。
创建 .env 文件。
单一存储库使用两种类型的 .env 文件：根 .env 用于存储本地开发堆栈在所有代理之间共享的密钥，每个代理子目录中的每个代理 .env 用于存储该代理自己的密钥。在启动本地环境之前手动创建它们。
在存储库根目录中，创建一个 .env文件，其中包含编排引擎和每个代理在本地开发期间使用的密钥，如以下示例所示：
MONGODB_URI=<your-mongodb-connection-string> <PROVIDER>_API_KEY=<your-api-key>
在每个代理子目录中，为仅该代理使用的密钥（例如特定于代理的API密钥）创建一个 .env文件。
重要
请勿将密钥提交给版本控制。
从单一代理迁移到单一存储库
要将现有的单代理存储库转换为单一存储库，请将代理文件移动到子目录中并重新初始化项目。
以下步骤展示了如何迁移到单一存储库。
将 .agentengine/目录移至代理子目录。
运行agentengine init 时， CLI会生成一个隐藏的 .agentengine/目录，其中包含 .agentengine/state.json文件中的工作区注册状态。在单一存储库中，每个代理都需要自己的 .agentengine/目录。
运行以下命令，将现有目录移至代理子目录中，从而保留助手的工作区注册信息：
mv .agentengine/ agents/<agent-name>/.agentengine/
重要
如果不移动 .agentengine/目录，运行agentengine init 会为代理注册一个新的工作区，并孤立以前的工作区注册。
创建根 agent.yaml文件。
在存储库根目录中，创建一个新的 agent.yaml，其中使用 agents 密钥列出您的代理，如前面的配置 Monorepo 部分中所述。
后续步骤
设置单一存储库后，您可以构建和部署代理。要学习；了解操作方法，请参阅以下指南：