注意

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

开始使用 llamactl

llamactl 是 LlamaAgents 的本地开发与部署 CLI。它能搭建应用骨架、在本地运行应用服务，并从你的终端管理云端部署。

更喜欢图形界面？

你也可以直接从 LlamaCloud 控制台部署起始模板。见从 LlamaCloud 一键部署。

开始前请先准备：

• 安装 uv。llamactl 用它来管理 Python 环境与项目依赖。
• 安装 git。云端部署是从源码仓库构建的。
• 如果你用的模板带前端，请安装 Node.js。macOS 与 Linux 我们推荐 nvm；Windows 我们推荐 Chocolatey。
• Windows 支持仍属实验性。想要最佳体验请使用 WSL2。若直接在 Windows 上运行，见 Windows 指南。

安装

用 uv 全局安装 llamactl：

终端窗口

uv tool install -U llamactl

或者把它固定到某个项目：

终端窗口

uv add --dev llamactl

身份认证

用浏览器登录：

终端窗口

llamactl auth login

如果无法使用浏览器登录，请改用 API key 与项目 ID：

终端窗口

llamactl auth token --api-key "$LLAMA_CLOUD_API_KEY" --project "$LLAMA_AGENTS_PROJECT_ID"

对于 CI 或其他非交互环境，你可以跳过存储的配置文件，改为设置环境变量：

终端窗口

export LLAMA_CLOUD_API_KEY="llx-..."
export LLAMA_AGENTS_PROJECT_ID="project-id"

配置档、环境与项目相关命令见 llamactl auth、llamactl environments 与 llamactl projects。

初始化项目

创建一个新的 LlamaAgents 项目：

终端窗口

llamactl init

llamactl init 会打开模板选择器并写出项目脚手架。模板可能只含 Python 工作流，也可能是「Python 应用 + 前端界面」。

llamactl init 使用符号链接。在 Windows 上，请在运行该命令前用 start ms-settings:developers 开启开发者模式。

脚手架里可能包含面向助手的那些文件，例如 AGENTS.md、CLAUDE.md 与 GEMINI.md。它们是可选的，不影响构建、运行或部署。

应用配置位于你项目的 pyproject.toml，或 llama_agents.yaml / llama_agents.toml。schema 见部署配置参考。

本地运行

在项目目录里启动本地开发服务：

终端窗口

llamactl serve

llamactl serve 会安装依赖、读取该应用配置的工作流、把它们作为 API 提供服务，并在应用带 UI 时代理前端的开发服务。

例如，下面这份配置会在名为 my-package 的本地部署下提供 my-workflow：

[project]
name = "my-package"

[tool.llamaagents.workflows]
my-workflow = "my_package.my_workflow:workflow"

[tool.llamaagents.ui]
directory = "ui"

src/my_package/my_workflow.py

workflow = MyWorkflow()

本地 API 可在 http://localhost:4501/deployments/my-package 访问。要运行该工作流，请向 /deployments/my-package/workflows/my-workflow/run 发一个 POST 请求。

各选项见 llamactl serve。工作流 API 细节见工作流与应用服务 API。

创建云端部署

云端部署基于 Git 仓库构建。请先把项目提交并推送：

终端窗口

git remote add origin https://github.com/org/repo
git add -A
git commit -m "Set up LlamaAgents app"
git push -u origin main

然后创建部署：

终端窗口

llamactl deployments create

deployments create 会在你的 $EDITOR 中打开一份 YAML 部署规格。请检查识别出的仓库、部署配置路径、Git ref 与密钥。保存并关闭文件即创建该部署。

要非交互地创建，请传入一个文件：

终端窗口

llamactl deployments create -f deployment.yaml

私有 GitHub 仓库需要 LlamaCloud 拥有仓库访问权限。若缺少访问权限，llamactl 会返回一个告知下一步该怎么做的错误。

声明式部署

对于可重复的部署，请生成一份 apply 形态的部署规格：

终端窗口

llamactl deployments template > deployment.yaml

编辑该文件，然后应用它：

终端窗口

llamactl deployments apply -f deployment.yaml

apply 在部署不存在时创建它，存在时更新它。密钥的值可以引用本地环境变量：

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

在改动云端状态之前先跑一次演练：

终端窗口

llamactl deployments apply -f deployment.yaml --dry-run

查看与流式日志

列出当前活动项目中的部署：

终端窗口

llamactl deployments get

获取单个部署：

终端窗口

llamactl deployments get NAME

流式查看日志：

终端窗口

llamactl deployments logs NAME --follow

当其他工具需要结构化输出时，给 deployments get 加上 -o json 或 -o yaml。

更新部署

如果部署跟踪的是某个分支，请重新解析该分支，并从最新提交开始一次新的发布：

终端窗口

llamactl deployments update NAME

要指向特定的分支、标签或提交：

终端窗口

llamactl deployments update NAME --git-ref main

对于推送模式的部署，update 只在当前仓库已配置好部署远端时才会推送本地代码。用 --push 关联并推送当前仓库，或用 --no-push 重新部署服务端已有的代码：

终端窗口

llamactl deployments update NAME --push
llamactl deployments update NAME --no-push

要在编辑器里修改部署规格：

终端窗口

llamactl deployments edit NAME

或者把规格纳入版本控制并重新应用：

终端窗口

llamactl deployments apply -f deployment.yaml

为自托管部署打包

如果你更愿意自己构建并部署容器，请用 llamactl pkg 为应用生成容器相关文件。见 pkg 命令参考。

---

下一步：阅读工作流与应用服务 API中关于定义与暴露工作流的内容。