企业官网建设流程全解析

🚀 30+款热门AI模型一站整合，DeepSeek/GLM/Qwen 随心用，限时 5 折。 👉 点击领海量免费额度

在实际 AI 代理开发中，一个常见的痛点是如何将自然语言描述的创意快速转化为一个可运行、可评估、可部署的 AI 代理。开发者往往需要手动搭建项目结构、编写复杂的代理逻辑、设计评估集、配置部署环境，这个过程不仅耗时，而且容易出错。Google 推出的 Agents CLI 正是为了解决这一系列工程化问题而设计的工具。它不是一个独立的命令行工具，而是一个专为 AI 开发工具（如 Gemini CLI、Claude Code、Codex 等）设计的“技能包”，将这些工具与 Google Cloud 的 Agent Development Kit (ADK) 和 Agent Platform 深度集成，让开发者能够通过自然语言指令，完成从构思到上线的完整代理生命周期管理。

本文将带你深入理解 Agents CLI 的核心机制，并完成一个从零开始的实战演练：构建一个能将冗长文本压缩成“原始人”风格摘要的“Caveman Compressor”代理。你将学会如何利用 Agents CLI 背后的技能，通过 AI 开发工具自动化完成项目脚手架搭建、代理逻辑编写、本地测试、评估集创建与运行，以及最终部署到 Google Cloud 的 Cloud Run 服务。整个过程将清晰地展示如何将自然语言指令转化为具体的工程操作，实现高效的 AI 代理开发工作流。

1. 理解 Agents CLI 的核心定位与工作流

在深入代码之前，必须厘清 Agents CLI 在整个 Google Cloud AI 代理生态中的角色。它不是让你在终端里直接输入agents-cli命令来创建代理，而是为 AI 开发工具提供了一套可调用的“技能”。

1.1 Agents CLI 是什么：AI 开发工具的“副驾驶”

Agents CLI 本质上是一个封装了专家知识的工具集。它将 Agent Development Kit (ADK) 的复杂设计模式、代理评估的最佳实践以及 Google Cloud 部署的配置细节，打包成一系列机器可读的“技能”。当你在 Gemini CLI、Claude Code 或 Codex 等工具中输入如“构建一个文本压缩代理”这样的自然语言指令时，这些工具能够识别并调用 Agents CLI 对应的技能（如google-agents-cli-scaffold），自动执行一系列标准化的工程任务。

这种设计带来了几个关键优势：

• 降低认知负荷：开发者无需记忆 ADK 的 API 细节、评估框架的配置语法或 Cloud Run 的部署参数。
• 标准化流程：确保每个代理项目都遵循一致的最佳实践结构，便于团队协作和后期维护。
• 加速迭代：通过自然语言快速触发构建、评估、部署循环，极大提升了原型开发速度。

1.2 核心组件与依赖关系

要使用 Agents CLI，你的环境中需要以下几个关键组件协同工作：

1. AI 开发工具：这是与用户交互的入口。它接收你的自然语言指令，理解意图，并决定调用哪个 Agents CLI 技能。常见的工具包括 Antigravity、Gemini CLI、Claude Code、Codex 等。
2. Agents CLI 技能包：这是一系列预定义的、可执行特定任务（如创建项目、运行评估、部署）的模块。它们通过uvx google-agents-cli setup安装。
3. Agent Development Kit (ADK)：一个开源的、代码优先的框架，用于构建复杂的 AI 代理。Agents CLI 生成的代理代码基于 ADK。
4. Google Cloud 项目与 Agent Platform：这是代理的运行时和部署目标。你需要一个已启用 Agent Platform API 的 Google Cloud 项目。
5. Python 与 uv：Agents CLI 通过uv（一个快速的 Python 包安装器）进行安装和管理。

它们之间的关系可以概括为：AI 开发工具作为指挥官，根据你的指令，调度Agents CLI 技能去操作ADK 框架生成代码，并最终将产物部署到Google Cloud Agent Platform。

1.3 典型工作流解析

一次完整的代理创建与部署，通常遵循以下标准化流程：

1. 环境准备：安装 uv、设置 Agents CLI、确保 AI 开发工具就绪。
2. 项目脚手架：AI 工具调用scaffold技能，创建包含标准目录结构、基础依赖和示例代码的新项目。
3. 代理构建：AI 工具编辑核心代理文件（如app/agent.py），根据你的需求实现具体逻辑。
4. 本地运行与测试：通过agents-cli run命令在本地验证代理的基本功能。
5. 评估与迭代：AI 工具创建评估集（.evalset.json）和评估配置，运行agents-cli eval run，并根据结果反馈调整代理指令或逻辑。
6. 部署：AI 工具添加部署配置（如针对 Cloud Run），并执行agents-cli deploy将代理发布到云端。
7. 观测：在 Google Cloud Console 中查看代理的追踪（Traces）、日志和指标。

2. 环境准备与前置条件检查

在开始构建“Caveman Compressor”之前，必须确保所有基础组件都已正确安装和配置。遗漏任何一步都可能导致后续流程失败。

2.1 创建并配置 Google Cloud 项目

这是代理能够部署和运行的基石。

1. 创建新项目或选择现有项目：访问 Google Cloud Console ，在顶部导航栏的项目选择器中，点击“新建项目”或选择一个已有项目。
2. 启用计费：确保项目已关联有效的结算账号。Agent Platform 的部分服务（如 Cloud Run、Vector Search）会产生费用。
3. 启用必要 API：在 Console 中，进入“API 和服务” -> “库”。搜索并启用以下 API：
   • Agent Platform API
   • Cloud Run API
   • Cloud Build API（部署时需要）
   • Artifact Registry API（存储容器镜像）
4. 配置服务账号（可选但推荐）：为安全起见，可以创建一个专用于代理部署的服务账号，并授予其必要的权限（如Cloud Run Admin,Service Account User,Storage Object Admin等）。在本地开发时，通过gcloud auth application-default login命令进行身份验证。

注意：对于快速原型和教程，直接使用个人账号通过gcloud登录通常更方便。但在生产环境中，务必使用具有最小权限的服务账号。

2.2 安装 Python 包管理器 uv

Agents CLI 通过uv安装，这是一个比传统pip更快的 Python 包管理工具。

在 macOS/Linux 上安装：

curl -LsSf https://astral.sh/uv/install.sh | sh

安装完成后，重启终端或运行source ~/.bashrc（或source ~/.zshrc）使uv命令生效。

在 Windows 上安装（通过 PowerShell）：

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

验证安装：

uv --version

应输出类似uv 0.4.x的版本信息。

2.3 安装并设置 Agents CLI

这是唯一一个需要你直接在终端执行的 Agents CLI 命令。它通过uvx（uv 的全局脚本运行器）来安装google-agents-cli及其所有技能。

uvx google-agents-cli setup

这个命令会：

• 下载google-agents-cli包。
• 将其安装到一个隔离的虚拟环境中。
• 将agents-cli命令行工具注册到你的系统路径中。

安装完成后，验证是否成功：

agents-cli --help

你应该能看到完整的命令列表，包括create,install,run,eval,deploy等。

2.4 准备 AI 开发工具

你需要一个能够理解并调用 Agents CLI 技能的 AI 开发工具。以下以Claude Code（或类似工具）为例，其工作方式具有代表性。

1. 安装 Claude Code：根据其官方文档进行安装。通常这可能是一个 IDE 插件（如 VS Code 扩展）或一个桌面应用程序。
2. 确保工具已识别 Agents CLI：大多数这类工具会自动检测系统路径中的agents-cli命令。你可以尝试在工具中询问：“你能使用 agents-cli 吗？” 或 “列出可用的 agents-cli 技能”。工具应该能回应并展示相关能力。
3. 配置工具上下文（如果需要）：有些工具可能需要你明确指定项目路径或 Python 环境。确保工具的工作目录是你计划创建代理项目的地方。

环境检查清单：

• [ ] Google Cloud 项目已创建且计费已启用。
• [ ]Agent Platform API等必要 API 已启用。
• [ ]gcloudCLI 已安装并登录 (gcloud auth application-default login)。
• [ ]uv已安装且版本 >= 0.4。
• [ ]agents-cli --help能正常显示帮助信息。
• [ ] AI 开发工具（如 Claude Code）已安装并可正常交互。

3. 实战：构建“Caveman Compressor”代理

现在，我们将按照标准工作流，一步步构建我们的文本压缩代理。请打开你的 AI 开发工具（下文以“工具”代称），并跟随操作。

3.1 启动项目：通过自然语言指令生成脚手架

在 AI 开发工具的聊天界面中，输入以下精确的指令：

使用 agents-cli 构建一个代理，将冗长的文本压缩成简洁的、原始人风格的摘要。

工具接收到指令后，会激活google-agents-cli-workflow和google-agents-cli-scaffold技能。接下来，工具可能会与你进行几轮交互以澄清需求：

1. 部署目标：工具会问“您希望将代理部署到哪里？” 对于本教程，选择Cloud Run。这是 Google Cloud 上完全托管的无服务器容器平台，适合快速部署和扩展。
2. 安全约束：工具可能会询问是否有特定的内容安全策略或模型防护（Model Armor）要求。对于原型，通常可以先选择默认或“无”。
3. 项目名称与路径：工具会确认项目名称。它可能会建议caveman-agent，并询问创建路径。

确认后，工具将自动执行以下命令序列（你可以在工具的“终端”或“执行日志”面板中观察到）：

# 1. 创建项目脚手架 agents-cli create caveman-agent --prototype --yes # 2. 进入项目目录 cd caveman-agent # 3. 安装项目依赖（ADK等） agents-cli install

生成的目录结构解析：执行完成后，你的当前目录下会生成一个caveman-agent文件夹，其结构如下：

caveman-agent/ ├── app/ │ ├── __init__.py │ ├── agent.py # 代理的核心逻辑定义文件 │ └── tools.py # （可选）自定义工具定义 ├── tests/ │ ├── __init__.py │ ├── test_agent.py # 单元测试 │ └── eval/ # 评估相关文件 │ ├── eval_config.json │ └── evalsets/ │ └── example.evalset.json ├── infrastructure/ # 部署基础设施配置（如Terraform） │ └── cloud_run/ ├── DESIGN_SPEC.md # 工具自动生成的代理设计规范 ├── pyproject.toml # Python项目依赖管理 ├── requirements.txt └── README.md

关键文件是app/agent.py和DESIGN_SPEC.md。后者记录了工具根据你的指令理解的需求，是后续迭代的重要依据。

3.2 编写代理逻辑：编辑app/agent.py

项目创建后，工具会自动打开app/agent.py文件。初始内容是一个简单的“回声”代理。现在，你需要指示工具将其替换为“原始人压缩器”的逻辑。

在工具中输入：

编辑 app/agent.py 文件，实现一个 caveman compressor 代理。它应该使用 Gemini 模型，指令是：将冗长输入文本转换为简短、简单的摘要，带有原始人般的语气。规则：省略冠词、填充词和礼貌用语；使用短句和简单词汇；保留技术术语；语气应该是突兀和有趣的，但核心含义必须保留。给出一个输入输出示例。

工具会调用google-agents-cli-adk-code技能，利用其对 ADK 设计模式的理解，生成类似下面的代码：

# app/agent.py from agents import Agent from agents.models import Gemini # 定义根代理 root_agent = Agent( name="caveman_agent", model=Gemini(model="gemini-flash-latest"), # 使用 Gemini Flash 模型，速度快成本低 instruction="""You are a text compressor. Convert verbose input text into short, simple summaries with a caveman-like tone. Rules: - Omit articles, filler words, and politeness. - Use short sentences and simple words. - Preserve technical terms. - The tone should be abrupt and funny, but the core meaning must be retained. Example input: "I would like to deploy the application to production environment." Example output: "Me deploy. Production. Now." """, # 可以在此处添加 tools=[] 来集成搜索、计算等工具 )

代码关键点解释：

• from agents import Agent：从 ADK 导入核心的Agent类。
• Gemini(model="gemini-flash-latest")：指定使用 Gemini Flash 模型的最新版本。这是一个在响应速度和成本间取得良好平衡的模型，适合此类文本转换任务。你也可以根据需要换成gemini-pro-latest或其他模型。
• instruction：这是代理的“人格”和任务描述。清晰、具体的指令对于获得稳定输出至关重要。我们给出了明确的规则和示例。
• name：代理的名称，用于日志和追踪。

3.3 本地运行测试：验证代理基本功能

在将代码提交或部署之前，必须在本地进行快速测试，确保代理能正确响应。

在工具中输入：

在本地运行代理，测试一下。输入是：“Please help me understand the deployment options available for my project.”

工具会执行命令：

agents-cli run "Please help me understand the deployment options available for my project."

你将在工具的输出中看到类似的结果：

"Deploy options: Agent Runtime, Cloud Run, GKE. Pick one. Ship."

这个输出符合预期：它去掉了礼貌用语（“Please help me understand”），将“deployment options”简化为“Deploy options”，列出了核心选项，并以突兀、有趣的命令式语气（“Pick one. Ship.”）结尾。

注意：agents-cli run命令会在本地启动一个轻量级的运行时，加载你的app/agent.py中定义的代理，处理输入，并返回输出。这是快速迭代代理指令（instruction）的最有效方式。

4. 评估代理：创建与运行评估集

本地测试通过只意味着代理能运行。要衡量其输出质量是否稳定、是否符合所有规则，需要系统性的评估。Agents CLI 集成了评估框架，支持使用 LLM 作为评判官（LLM-as-Judge）。

4.1 创建评估集

评估集（Eval Set）是一个 JSON 文件，包含了一系列输入和期望的输出或评判标准。指示你的工具创建评估集：

为这个原始人代理编写评估并运行它们。评估需要覆盖压缩质量、技术术语保留和语气。

工具会激活google-agents-cli-eval技能，执行以下操作：

1. 在tests/eval/evalsets/目录下创建caveman.evalset.json文件。
2. 根据你的要求，生成多个测试用例。

让我们查看一下工具可能生成的评估集内容：

// tests/eval/evalsets/caveman.evalset.json { "name": "caveman_compressor_evals", "evals": [ { "input": "The quarterly financial report indicates a substantial increase in revenue growth year-over-year, primarily driven by our strategic partnerships in the Asian market.", "eval": { "type": "llm_judge", "criteria": "The output must be a concise, caveman-style summary that preserves the key terms 'quarterly financial report', 'revenue growth', and 'Asian market'. It must omit polite phrases and articles." } }, { "input": "Could you possibly assist me in resetting my forgotten password for the user portal?", "eval": { "type": "llm_judge", "criteria": "The output must be abrupt and funny, converting the polite request into a direct command like 'Reset password. Portal.' It should not contain 'please', 'could you', or 'assist'." } }, { "input": "We are experiencing a critical outage in the us-east1 region due to a network partition. The SRE team is actively working on mitigation.", "eval": { "type": "llm_judge", "criteria": "The output must retain the technical terms 'outage', 'us-east1 region', 'network partition', 'SRE team', and 'mitigation'. The tone should be urgent but caveman-like." } } ] }

评估集解析：

• 每个eval对象包含一个input（给代理的输入）和一个eval配置。
• type: "llm_judge"表示使用一个 LLM（通常是另一个 Gemini 模型）来根据criteria（评判标准）判断代理的输出是否合格。
• criteria需要清晰、可衡量，明确指出输出的必要元素和禁止元素。

4.2 配置与运行评估

工具在创建评估集后，还会检查或创建tests/eval/eval_config.json文件，用于配置评估运行时，例如指定作为评判官的 LLM 模型。

然后，工具会运行评估：

agents-cli eval run

命令执行后，你会在终端看到评估进度和结果。输出会显示每个测试用例是否通过，以及评判官（LLM）的反馈理由。例如：

Running evaluation for caveman_compressor_evals... - [PASS] Test Case 1: Output "Report good. Revenue up. Asia partners." meets criteria. - [FAIL] Test Case 2: Output "Help reset password?" is still too polite. Missing caveman tone. - [PASS] Test Case 3: Output "Outage! us-east1. Network broke. SRE fix." meets criteria. Evaluation completed. 2 passed, 1 failed.

4.3 迭代优化代理

当出现失败用例时，正是迭代改进的时候。根据评估反馈（如“语气仍然太礼貌”），你可以指示工具调整代理的instruction。

在工具中输入：

第二个测试用例失败了，反馈说输出太礼貌。请修改 agent.py 中的指令，让语气更粗鲁、更突兀，确保它完全省略任何请求性词语。

工具会修改app/agent.py中的instruction，例如在规则中增加一条：“-Neveruse words like 'could', 'would', 'please', 'help'. Use imperative commands only.”。

修改后，再次运行agents-cli eval run，直到所有测试用例通过。这个“构建-评估-迭代”的循环是提升代理质量的核心。

5. 部署到 Google Cloud Cloud Run

当代理在本地通过评估后，就可以部署到生产环境了。我们将使用 Cloud Run，因为它无需管理服务器，自动扩缩容，并且与 Agents CLI 集成良好。

5.1 添加部署配置

在工具中输入部署指令：

将这个代理部署到 Cloud Run。

工具会激活google-agents-cli-deploy技能，执行以下操作：

1. 增强项目脚手架：运行agents-cli scaffold enhance --deployment-target cloud_run。这个命令会在infrastructure/目录下生成或更新 Cloud Run 部署所需的配置文件，可能包括 Dockerfile、Cloud Build 配置、以及 IaC（如 Terraform）模板。这些文件定义了如何将你的代理代码打包成容器，并部署到 Cloud Run。
2. 检查并配置权限：工具会确保当前gcloud认证的用户或服务账号拥有部署到 Cloud Run 的权限（Cloud Run Admin,Service Account User,Cloud Build Editor等）。

5.2 执行部署命令

配置完成后，工具会执行部署命令：

agents-cli deploy

这个命令在后台会触发一系列 Google Cloud 服务：

1. 容器构建：使用 Cloud Build 根据Dockerfile将你的代理代码及其依赖打包成一个容器镜像，并推送到 Artifact Registry。
2. 服务部署：在 Cloud Run 上创建一个新的 Revision（版本），使用上一步构建的镜像，并配置必要的环境变量、内存、CPU 等。
3. URL 生成：部署成功后，Cloud Run 会为该服务分配一个唯一的 HTTPS URL。

部署过程可能需要几分钟。完成后，你会在终端看到类似下面的输出：

Deployment successful! Service URL: https://caveman-agent-xyz-uc.a.run.app You can send requests to: POST https://caveman-agent-xyz-uc.a.run.app/agent

5.3 验证线上服务

获得 Service URL 后，你可以立即测试部署的代理。使用curl或任何 HTTP 客户端（如 Postman）发送请求：

curl -X POST \ -H "Content-Type: application/json" \ -d '{"message": "I am writing to kindly request an extension for the project deadline, as we have encountered some unforeseen complexities during the integration phase."}' \ https://caveman-agent-xyz-uc.a.run.app/agent

预期的响应应该是一个符合“原始人”风格的 JSON：

{ "response": "Need more time. Project hard. Integration tricky." }

6. 观测、排错与生产环境考量

部署成功只是第一步。在生产环境中，你需要监控代理的运行状况、理解其行为、并能够快速排查问题。

6.1 启用与查看追踪（Cloud Trace）

Agents CLI 在部署到 Cloud Run 时，默认会启用 Cloud Trace。这是 Google Cloud 的分布式追踪服务。

1. 在 Google Cloud Console 中，导航到Cloud Trace。
2. 在 Trace 列表中，你应该能看到以你的服务名（如caveman-agent）开头的追踪记录。每条记录对应一次向代理发送的请求。
3. 点击一条追踪，你可以看到详细的时序图，包括：
   • 总耗时。
   • LLM 调用：花了多长时间，使用了哪个模型。
   • 工具执行（如果代理调用了工具）：每个工具的执行耗时。
   • 内部处理逻辑。

追踪是排查“代理响应慢”问题的首要工具。如果一次请求耗时过长，你可以立即看到是 LLM 调用慢，还是某个自定义工具拖慢了整体流程。

6.2 配置高级可观测性

默认的 Trace 提供了请求链路视图。对于更深入的分析，你可能需要将日志和指标导出到 BigQuery 和 Cloud Storage 进行长期存储和分析。

在工具中输入：

为我的代理设置可观测性基础设施。

工具会调用相关技能，自动执行以下任务（可能需要你的确认）：

1. 创建服务账号：一个具有特定权限（如写入 BigQuery 和 Cloud Storage）的服务账号。
2. 创建 Cloud Storage 存储桶：用于存储详细的代理执行日志。
3. 创建 BigQuery 数据集和表：用于结构化存储指标和事件，方便进行 SQL 查询和分析。
4. 更新部署配置：修改 Cloud Run 服务的环境变量或侧车（sidecar）配置，使其将追踪和日志数据发送到新创建的资源。

完成这些设置后，你可以在 BigQuery 中编写查询，来分析代理的每日调用量、平均响应时间、不同输入的输出分布等。

6.3 常见问题与排查路径

在开发和使用 Agents CLI 工作流时，你可能会遇到以下典型问题：

6.4 生产环境最佳实践

将原型转化为稳定生产服务，还需要考虑以下几点：

1. 版本管理与回滚：Cloud Run 每次部署都会创建一个新的 Revision。利用此功能，为每次变更打上标签，并配置流量分配。如果新版本出现问题，可以立即将 100% 流量切回之前的稳定版本。
2. 安全加固：
   • 身份认证：为 Cloud Run 服务启用 IAM 认证，只允许特定的服务账号或用户访问。
   • 网络：将 Cloud Run 服务配置为仅允许内部访问（通过 VPC 网络），或使用 API 网关、负载均衡器作为入口。
   • 密钥管理：不要将 API 密钥等敏感信息硬编码在代码中。使用 Google Cloud Secret Manager 存储，并通过环境变量注入到 Cloud Run 服务。
3. 性能与成本优化：
   • 模型选择：根据任务复杂度选择模型。gemini-flash适合简单任务，gemini-pro能力更强但更贵。通过评估确定性价比最高的模型。
   • 容器优化：优化Dockerfile，使用多阶段构建减小镜像体积，加快部署速度。
   • 自动扩缩容：根据 QPS 和并发请求数合理配置 Cloud Run 的自动扩缩容参数，在性能和成本间取得平衡。
4. 持续集成/持续部署：将agents-cli eval run和agents-cli deploy集成到你的 CI/CD 流水线（如 Cloud Build、GitHub Actions）中。确保代码合并前通过所有评估，并自动部署到测试环境。

通过 Agents CLI 构建和部署 AI 代理，核心价值在于将自然语言意图转化为一套标准化、可重复、可观测的工程实践。它抽象了底层基础设施的复杂性，让开发者能更专注于代理本身的逻辑和效果优化。从“Caveman Compressor”这个简单示例出发，你可以探索更复杂的场景，例如为代理添加联网搜索工具、构建多代理协作系统、或者集成企业知识库进行检索增强生成，从而打造出真正解决实际业务问题的智能体。

🚀 30+款热门AI模型一站整合，DeepSeek/GLM/Qwen 随心用，限时 5 折。 👉 点击领海量免费额度