创建项目

命令语法

使用以下命令搭建新项目：

agentengine create [--template <template-id>] [--name <display-name>] [--dir <path>] [--llm <provider>] [--llm-base-url <url>] [--llm-model <model>] [--llm-auth-header <header>] [--memory] [--yes]

根据您指定的标志， CLI会提示您配置项目。

此命令创建一个包含 project-config.yaml文件的项目目录，并在 <project-directory>/agents/<slug> 子目录中构建助手的工作区目录。 <slug> 值是 --name 值的小写带连字符版本。工作区目录包含 agent.yaml、.env 以及其他特定于代理的文件（将在后续章节中介绍）。

命令标志

显示名称限制

CLI将显示名称复制到生成的源文件中。名称不能包含以下字符：

• 双引号 (")

• 反斜杠 (\)

• 反引号

• 控制字符、换行符或文本方向字符

如果在使用交互式CLI时输入了无效名称， CLI将显示错误并再次提示。如果向 --name 标志传递无效名称，则该命令将失败并显示错误，指出指定不允许的字符或字符类别。

支持的模板

下表描述了可以传递给 agentengine create 命令的入门模板：

本地环境默认值

当您从提供商目录中选择 LLM 连接时，agentengine create 会提示您输入所需的连接详细信息，例如API密钥。如果在Shell环境中设立了 LLM_API_KEY，该命令会将其作为默认。确认该值后，该命令会将其作为 LLM_API_KEY 写入生成的 .env文件。您无需手动配置此值。

启用内存后，agentengine create 会检测本地环境中的 VOYAGE_API_KEY，并将其作为默认。确认该值会将其写入生成的 .env。

当您使用 --yes 标志运行agentengine create 时，该命令不会提示输入检测到的环境值。对于除 custom 之外的每个提供商目录选项，您必须在运行命令之前在环境中设立LLM_API_KEY。当您同时传递 --memory --yes 时，必须在运行命令之前在环境中设立VOYAGE_API_KEY，否则命令会失败。

chatbot-client 模板生成 .env.local文件而不是 .env文件。在运行应用之前，您必须使用以下值手动填充 .env.local文件：

• 已部署代理的API URL

• 您的项目ID

• 您的工作区ID

• 您的服务帐户访问权限令牌

自定义脚手架代理

agentengine create 完成后，导航到代理位于 <project-directory>/agents/<slug> 的工作区目录并查看生成的文件。

所有生成的代理都包含 .agents/skills/atlas-agent-engine（对于 Codex、Copilot 和其他代理）或 .claude/skills/atlas-agent-engine（对于 Claude Code）的 atlas-agent-engine技能。

使用代理入门模板时，查看生成的代理源和 .env文件，确认 LLM 连接满足您的要求。 LLM客户端、模型、端点和身份验证行为在生成的代理源代码中配置。

对于配置 LLM 连接的目录选项，生成的 .env文件包含共享档案 LLM_API_KEY。如果您选择 Manual setup，请在代理代码中配置 LLM 连接，并将代码所需的任何密钥添加到 .env文件中。要学习；了解更多信息，请参阅在代码中设置 LLM 网关。

使用 chatbot-client 模板时，查看.env.local文件并确认您正确设立了已部署代理的API URL、项目ID、工作区ID和服务帐户访问权限令牌。聊天机器人客户端应用中没有 agent.yaml文件。

从入门模板设置 LLM 网关

运行agentengine create 命令时，该命令会提示您选择 LLM 连接，类似于以下示例：

Which LLM connection do you want to use?
  1) OpenAI
  2) Anthropic
  3) Google Gemini
  4) OpenRouter
  5) OpenAI-compatible - AWS Bedrock, Azure Foundry
  6) Anthropic-compatible - AWS Bedrock, Azure Foundry
  7) Manual setup - implement the LLM client in code

如果您从此目录中选择一个提供商，agentengine create 命令会提示输入连接所需的详细信息，其中可能包括以下内容：

• 基本 URL

• 模型或部署名称

• API 密钥

• 无法识别托管时的连接身份验证标头

该命令将选定的 LLM客户端写入生成的代理源，并将共享档案作为 LLM_API_KEY 存储在生成的 .env文件中。

该命令还会提示您选择助手和工具访问权限外部主机的方式：

• 应用推荐的 network.egress 配置。如果没有可用的网关托管，例如当您选择 Manual setup (custom) 时，此选项将指示您稍后配置 LLM 出口。

• 允许所有出站访问权限。

如果您的 LLM 连接不是列出的选项之一，请选择 Manual setup 并在代码中设立网关。此选项会创建模型构建器存根，以便您可以在代理代码中配置连接。

在代码中设置 LLM 网关

要将 LLM 连接到代理，请创建一个特定于框架的模型，并将生成的模型实例从代理的入口点传递给 app.llm(...) 方法。您可以将模型构建代码放在代理代码中的任何文件中，但入门模板会将存根放在特定于语言的文件中。如果您不使用入门模板，则可以在其他地方定义模型，只要 app.llm(...) 接收到受支持的模型对象。

下表描述了在不同运行时的代码中设置 LLM 网关的惯例：

构造函数用于设置端点、身份验证标头和模型名称。示例，LangGraph Python insurance-agent 模板在 src/<module>/llm.py 中定义 build_llm() 并返回一个 LangChain BaseChatModel。代理入口点导入 build_llm() 并将返回的模型传递给 app.llm(...)。

允许网关托管，以便代理可以访问它。将自定义网关托管和端口添加到 agent.yaml文件中的 network.egress区块。示例，要将 gateway.example.com:443 添加到工具沙箱的现有出口允许列表，运行以下命令：

agentengine agent egress add --component tool gateway.example.com:443

要学习；了解有关为代理配置网络出口的更多信息，请参阅网络出口入门指南。

命令语法

在代理工作区目录中，运行以下命令以注册代理并生成本地文件：

agentengine init [--workspace-id <id>] [--project-id <id>] [--org-id <id>] [--base-url <url>] [--context <name>]

此命令以交互方式选择或创建组织和项目，生成本地开发文件，并将代理注册为Atlas Agent Engine 上的工作区。

命令标志

交互式流程

运行agentengine init 时， CLI将指导您完成以下步骤：

1. 使用编号菜单列出您的组织，包括 "Create a new organization..." 选项。如果组织不存在， CLI会提示您输入名称以创建组织。

2. 选择组织后，将使用编号菜单列出您的项目，包括 "Create a new project..." 选项。如果项目不存在， CLI会提示您输入名称以创建项目。

3. 将所选项目另存为处于本地身份验证状态的活动 project_id。

4. 在代理目录中生成以下本地开发文件：

   • docker-compose.yml

   • .agentengine/Dockerfile

   • .agentengine/entrypoint.py

   • .dockerignore

   • .gitignore

5. 将代理注册为平台上的工作区，并创建指定了 workspace_id、org_id 和 project_id 的 .agentengine/state.json文件。

代理入门模板

如果您使用的是 TypeScript 模板，请先安装 Node.js 依赖项，然后再在本地启动代理：

pnpm install

检查脚手架代理后，运行agentengine dev up 以在本地启动代理：

agentengine dev up

聊天机器人客户端模板

在 .env.local文件中设置必要的值后，安装依赖项并启动开发服务器：

pnpm install
pnpm run dev

在浏览器中打开 http://localhost:3000 以使用聊天用户界面。