注意

LlamaAgents 的云端部署目前处于 beta 预览阶段，已广泛开放以供反馈。你可以在本地试用，或部署到 LlamaCloud 并通过应用内的反馈按钮把意见发给我们。

LlamaAgents 从你的仓库读取配置来运行应用。配置定义在项目的 pyproject.toml 中。

pyproject.toml

[tool.llamaagents]
name = "my-app"
env_files = [".env"]

[tool.llamaagents.workflows]
workflow-one = "my_app.workflows:some_workflow"
workflow-two = "my_app.workflows:another_workflow"

[tool.llamaagents.ui]
directory = "ui"
build_output_dir = "ui/static"

认证

可以为部署配置自动注入访问 LlamaCloud 所需的认证信息。

[tool.llamaagents]
llama_cloud = true

设置之后：

• 开发期间，llamactl 使用环境变量认证或当前活动配置档，然后把 LLAMA_CLOUD_API_KEY、LLAMA_AGENTS_PROJECT_ID 与 LLAMA_CLOUD_BASE_URL 注入你的 Python 服务进程与 JavaScript 构建。
• 部署之后，LlamaCloud 会自动向 Python 进程注入一个专用 API key。前端进程收到的则是每个访问该应用的用户各自特有的短时会话 cookie。因此请在前端 API 客户端上配置项目 ID，让前端与后端的 LlamaCloud API 请求都限定在同一个项目 ID 内。

.env 文件

多数应用都需要 API key（例如 OpenAI）。你可以用 .env 文件声明它们，并在配置中引用：

[tool.llamaagents]
env_files = [".env"]

然后设置你的密钥：

.env

OPENAI_API_KEY=sk-xxxx

其他文件格式（YAML/TOML）

如果你希望 pyproject.toml 保持简洁，也可以把同样的配置写进 llama_agents.yaml 或 llama_agents.toml。所有字段的结构与类型都相同，只是省去 tool.llamaagents 这个前缀。

Schema

DeploymentConfig 字段

字段	类型	默认值	说明
name	string	"default"	URL 安全的部署名。在 pyproject.toml 中，若省略则回退到 project.name。
workflows	map<string,string>	—	workflowName -> "module.path:workflow" 的映射。
env_files	list<string>	[".env"]	要加载的 env 文件路径，相对于配置文件。重复项会被去掉。
env	map<string,string>	{}	运行时注入的环境变量。
required_env_vars	list<string>	[]	运行时必须设置的环境变量名。若有缺失或为空，llamactl serve 与部署都会立即报错失败。
llama_cloud	boolean	false	表示该部署会连接 LlamaCloud。设为 true 会自动注入一个 LlamaCloud API key。
ui	UIConfig	null	可选的界面配置。若存在 ui，则 directory 为必填。

必需的环境变量

用 required_env_vars 确保关键密钥在应用启动前就已就位：

[tool.llamaagents]
# Force the app to start only when these are set
required_env_vars = ["OPENAI_API_KEY", "ANTHROPIC_API_KEY"]

提示：本地开发时把它与 env_files 配合使用，或者通过部署的密钥管理服务提供这些值。

UIConfig 字段

字段	类型	默认值	说明
directory	string	—	界面源码路径，相对于配置目录。设置了 ui 时必填。
build_output_dir	string	${directory}/dist	构建后的界面输出目录。在 TOML/pyproject.toml 中设置时，路径相对于配置文件。通过 package.json（llamaagents.build_output_dir）设置时，按 ${directory}/${build_output_dir} 解析。
package_manager	string	"npm"（或推断）	构建界面所用的包管理器。未设置时，从 package.json 的 packageManager 推断（例如 pnpm@9.0.0 → pnpm）。
build_command	string	"build"	用于构建的 NPM 脚本名。
serve_command	string	"dev"	开发期用于提供服务的 NPM 脚本名。
proxy_port	integer	4502	开发期应用服务端代理指向的端口。

通过 package.json 集成界面

注意：设置好 ui.directory 让 package.json 能被找到之后，你就可以直接在其中配置界面。

例如：

{
  "name": "my-ui",
  "packageManager": "pnpm@9.7.0",
  "scripts": { "build": "vite build", "dev": "vite" },
  "llamaagents": {
    "build_output_dir": "dist",
    "package_manager": "pnpm",
    "build_command": "build",
    "serve_command": "dev",
    "proxy_port": 5173
  }
}