注意

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

在 GitHub Actions 里使用 llamactl deployments apply -f，适合你想把部署规格纳入源码管理、并在每次推送时自动更新的场景。

必需的 Secrets 与 Variables

llamactl 可以从环境变量完成认证，因此 CI 不需要存储配置档：

• LLAMA_CLOUD_API_KEY：作为 GitHub Actions 的 secret 存放。
• LLAMA_AGENTS_PROJECT_ID：作为 GitHub Actions 的 variable 或 secret 存放。

如果你要部署到非默认的 LlamaCloud 环境，还要设置 LLAMA_CLOUD_BASE_URL。

部署规格

在仓库里保留一份部署规格，例如 deployment.yaml：

name: my-agent
spec:
  repo_url: https://github.com/${GITHUB_REPOSITORY}
  deployment_file_path: "."
  git_ref: ${GITHUB_SHA}
  secrets:
    OPENAI_API_KEY: ${OPENAI_API_KEY}

deployments apply 会在把部署发往 LlamaCloud 之前，先从进程环境中解析 ${VAR} 引用。这让同一份文件既能使用 GitHub 提供的值（如 GITHUB_SHA），也能使用由工作流注入的密钥。

如果希望工作流每次都更新同一个部署，请使用稳定的 name。若省略 name 而规格里用了 generate_name，每次 apply 都可能创建一个新部署。

工作流示例

name: Deploy LlamaAgents app

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      LLAMA_CLOUD_API_KEY: ${{ secrets.LLAMA_CLOUD_API_KEY }}
      LLAMA_AGENTS_PROJECT_ID: ${{ vars.LLAMA_AGENTS_PROJECT_ID }}
      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
    steps:
      - uses: actions/checkout@v4

      - name: Apply deployment
        run: uvx llamactl deployments apply -f deployment.yaml --annotate-on-error

--annotate-on-error 会把校验错误与 API 错误写回 YAML 输入，于是 Actions 日志能指向出问题的那个字段。命令失败时返回非零退出码。

捕获状态输出

llamactl 把机器可读的输出留在 stdout，把状态信息放在 stderr。如果工作流要解析 deployments apply 的状态文本，请显式捕获 stderr：

终端窗口

status="$(uvx llamactl deployments apply -f deployment.yaml --annotate-on-error 2>&1 >/dev/null)"
printf '%s\n' "$status"

当下游步骤需要部署名时，请在 deployment.yaml 里用稳定的 name，而不是去解析状态消息。