项目简介
一个命令行工具和技能集，能让任何编程助手成为在 Google Cloud 上创建、评估和部署 AI 智能体的专家。它提供脚手架、评测、部署和可观测性等命令，并与 ADK 框架集成。
README 预览
\n \n agents-cli\n The CLI and skills for building agents on Gemini Enterprise Agent Platform.\n\n \n Get Started | \n Skills | \n Commands | \n PyPI | \n Issues | \n Docs | \n Release Notes | \n Star us\n \n\n\n---\n\nTurn your favorite coding assistant into an expert at building and deploying agents on Google Cloud.\n\n**Agents CLI in Agent Platform** (`agents-cli`) gives your coding agent the skills and commands to build, scale, govern, and optimize enterprise-grade agents — so you don't have to learn every CLI and service yourself.\n\n**Works seamlessly with:**\n[Antigravity CLI](https://antigravity.google/) • [Claude Code](https://docs.anthropic.com/en/docs/claude-code) • [Codex](https://github.com/openai/codex) • *and any other coding agent.*\n\n## Get Started\n\n**Prerequisites:** Python 3.11+, [uv](https://docs.astral.sh/uv/getting-started/installation/), and [Node.js](https://nodejs.org/en/download).\n\n### 1. Install\n\n```bash\nuvx google-agents-cli setup\n```\n\n\nOr just the skills — your coding agent will handle the rest\n\n```bash\nnpx skills add google/agents-cli\n```\n\n\n\n### 2. Open your coding agent\n\nLaunch [Antigravity CLI](https://antigravity.google/), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), or any coding agent you prefer.\n\n### 3. Build your first agent\n\nAsk your coding agent to build something — e.g. *"Use agents-cli to build a caveman-style agent that compresses verbose text into terse, technical grunts"*\n\nSee the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tutorial/) for a step-by-step walkthrough.\n\n**[Browse the full documentation →](https://google.github.io/agents-cli/)**\n\n---\n\n## Agent Skills\n\n| Skill | What you
常见问题 (5)
故障排除如何解决在 Windows 上运行 agents-cli setup 或其他命令时出现的 PermissionError [WinError 5] Access denied 错误?
这种情况发生在 1.9.0 之前的 agents-cli 版本中：当某个工具（例如 uv.exe）在磁盘上被找到，但 Windows 阻止其执行时，通常是由 AppLocker、Defender 或 NTFS 权限策略导致的。shutil.which() 在 Windows 上能找到可执行文件，但并不会验证它是否真的能运行，而旧的子进程辅助函数也没有捕获由此产生的 PermissionError。
通过将 agents-cli 升级到 1.9.0 或更高版本来修复：
python -m pip install --upgrade agents-cli验证安装：
agents-cli info升级后，CLI 会报告一个清晰的工具解析错误，而不是原始的 Python 回溯信息。要使命令成功运行，还必须确保 uv.exe 被允许执行：
uv --version如果仍然返回 "Access is denied"，请让 IT 管理员在 AppLocker/Defender 中允许 uv.exe，或在被允许的位置重新安装 uv，或者在 uv 未被阻止的环境中运行 CLI。同样的问题还可能影响 setup、lint、login、deploy、publish 和 scaffold 命令，因为它们共享同一个子进程运行器。
故障排除为什么即使在运行 setup 之后，agents-cli info 仍显示 "Installed skills: none"？
这是 agents-cli v1.9.0 中的一个 bug：agents-cli info 在运行 npx skills list --json 时没有加上 -g 标志，因此它只能检测到项目级作用域的 skills，而遗漏了全局安装的 skills（即由 agents-cli setup 安装到 ~/.agents/skills/ 的那些）。这些 skills 实际上已经正确安装——可以通过 ls ~/.agents/skills/google-agents-cli-*/SKILL.md 或 npx -y skills list -g --json 来验证。该 bug 已在 v1.12.0 中修复，因此请升级你的 CLI：uv tool install google-agents-cli --upgrade（或者重新运行 uvx google-agents-cli@latest setup）。
故障排除为什么 Agent Runtime 的部署指南和可观测性指南在部署前运行 `agents-cli infra single-project` 这一问题上给出了相互冲突的说明？
这一矛盾是一个文档 bug，已在 agents-cli v1.8.0 中修复。请遵循以下顺序规则：
- **Basic Agent Runtime / Cloud Run：** 直接部署；请勿先运行 infra single-project。
- **GKE：** 正常执行部署；部署过程会执行所需的针对性 Terraform 操作。
- **由 Terraform 管理的可观测性（任何目标）：** 在首次部署前运行 agents-cli infra single-project --apply。
- **现有的命令式（imperative）部署：** 除非在切换所有权之前先导入或删除现有资源，否则请勿在事后应用 Terraform。否则，请保持命令式所有权，并手动配置可观测性。
在命令式 Agent Runtime 部署之后应用 Terraform，可能会创建第二个 Runtime 或将操作目标指向第二个 Runtime。请升级到 v1.8.0 或更高版本，以获取更正后的 README、迁移指南和 skill 文档。
故障排除如何防止并发的 agents-cli deploy --no-wait 进程覆盖彼此待处理的 Agent Runtime 操作？
升级到 **agents-cli v1.8.0 或更高版本**，该版本修复了 v1.3.1 中的竞态问题：通过唯一的 owner ID 原子性地声明 deployment_metadata.json，在 Runtime 重新验证和远程提交期间持有跨进程锁，并使 cleanup/finish 操作具备 owner 感知能力。
python -m pip install --upgrade agents-cli==1.8.0如果无法立即升级，请将部署操作串行化，确保每个 agent 项目同一时间只运行一个 CLI 进程：
flock -n /tmp/my-agent-deploy.lock agents-cli deploy --no-wait不要在 CI 中并行运行部署任务。如果进程在远程提交后失败且结果未知，应让该操作保持 fail-closed 的 state=starting 状态，并手动进行调和，而不是清除元数据。
故障排除为什么 agents-cli 从远程 Git 模板生成脚手架时会遗漏符号链接的共享文件并导致 ImportError？
这是 agents-cli 1.4.1–1.5.0 中的一个回归问题：远程模板脚手架将每个符号链接都当作安全警告跳过，但仍报告成功，导致诸如 app/shared -> ../../shared 之类的目录缺失。请升级到 agents-cli 1.7.0 或更高版本，然后重新运行脚手架命令，并验证目标是否存在，例如 demo/app/shared/config.py。如果无法升级，请将仓库内部的符号链接替换为物理复制的目录，并通过脚本和 CI 漂移检查保持它们同步。不要仅依赖 local@ 测试：它会在预复制阶段解引用符号链接，可能掩盖远程模板的故障。