使用 Agent CLI 和代理身份创建和部署代理

本指南介绍了如何在启用了 Agent Identity 的 Gemini Enterprise Agent Platform 上的 Agent Runtime 中创建和部署代理。

Agent Identity 会为已部署的代理分配安全的 SPIFFE 身份。代理使用此身份向 服务 Google Cloud 进行身份验证，并从 Agent Identity 身份验证管理器检索凭据。

准备工作

  1. 启用 Agent Identity API、Agent Platform API、Agent Registry API 和 App Hub API API。

    启用 API 所需的角色

    如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您 创建了项目，则可能已通过 所有者角色 (roles/owner) 拥有此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。 了解如何授予角色。

    启用 API

  2. 确保您拥有项目的 Agent Platform User (roles/aiplatform.user) 角色。

创建和部署代理

使用 google-agents-cli 创建示例代理，并使用 Agent Identity 部署该代理：

  1. 安装 uv，然后运行 google-agents-cli 设置：

    pip install uv
uvx google-agents-cli setup

  2. 使用原型模板创建代理项目：

    uvx google-agents-cli create AGENT_PROJECT --prototype --yes

    将 AGENT_PROJECT 替换为新代理项目目录的名称（例如 maps-agent）。

    此命令会生成以下项目目录结构：

    AGENT_PROJECT/
├── app/                       # Core agent code
│   ├── agent.py               # Main agent logic
│   ├── fast_api_app.py        # Client application logic
│   └── app_utils/             # App utilities and helpers
├── tests/                     # Unit and integration tests
├── GEMINI.md                  # Development guide
└── pyproject.toml             # Project dependencies

  3. 将默认应用文件夹 (app) 重命名为与您的代理名称 (AGENT_NAME，例如 maps_agent) 匹配。代理名称必须是有效的 Python 标识符：它们必须以字母开头，并且只能包含字母、数字和下划线。

    cd AGENT_PROJECT
mv app AGENT_NAME

  4. 更新 agent.py 配置文件以反映新名称：

    # In AGENT_PROJECT/AGENT_NAME/agent.py
app = App(
    root_agent=root_agent,
    name="AGENT_NAME",
)

  5. 根据模型的 区域可用性，选择要使用的模型。 更新 agent.py 中的 MODEL 值，使其与您选择的模型匹配。

    仅在 global 区域提供的模型的解决方法

    如需使用仅在 global 区域提供的模型，您必须修改 agent.py，以便您的代理可以 访问该模型。

    1. 添加以下 import 命令：

      from functools import cached_property
from google.genai import Client

    2. 在 import 命令后添加以下子类：

      class GlobalGemini(Gemini):
    @cached_property
    def api_client(self) -> Client:
        return Client(enterprise=True, location="global")

    3. 找到以下代码：

      root_agent = Agent(
    name="root_agent",
    model=Gemini(

      将其更改为引用新的子类：

      root_agent = Agent(
    name="root_agent",
    model=GlobalGemini(

  6. 通过创建配置文件来启用 Agent Identity：

    echo '{ "identity_type": "AGENT_IDENTITY" }' > AGENT_NAME/.agent_engine_config.json

  7. 为部署依赖项创建 requirements.txt 文件：

    uv export \
    --no-emit-workspace \
    --no-hashes \
    --format requirements.txt \
    --output-file AGENT_NAME/requirements.txt

  8. 验证项目目录结构：

    AGENT_PROJECT/
├── AGENT_NAME/                 # Agent application folder
│   ├── .agent_engine_config.json # Agent Identity configuration
│   ├── agent.py                  # Main agent logic
│   ├── fast_api_app.py           # Client application logic
│   ├── requirements.txt          # Deployment dependencies
│   └── app_utils/                # App helpers
├── tests/                        # Tests
├── GEMINI.md                     # Development guide
└── pyproject.toml                # Project dependencies

  9. 在本地测试代理：

    uv run adk web . --port 8501 --reload_agents

    如需验证代理，请执行以下操作：

    1. 前往 http://localhost:8501。或者，如果您使用的是 Cloud Shell，请点击 Web 服务器输出提供的链接。

    2. 在聊天界面中，发送测试提示以验证响应。

  10. 使用 CTRL+C 终止服务器。

  11. 将代理部署到 Google Cloud：

    uv run adk deploy agent_engine AGENT_NAME \
    --project="PROJECT_ID" \
    --region="LOCATION"

    替换以下内容：

    • PROJECT_ID：您的 Google Cloud 项目 ID。

    • LOCATION：您要部署代理的 受支持区域 （例如 us-west1）。

    部署可能需要几分钟才能完成。完成后， CLI 会输出确认消息以及指向 控制台 Google Cloud 中代理 Playground 的链接。

  12. 检索代理的 SPIFFE ID (Agent Identity)：

    1. 在 Google Cloud 控制台中，前往部署页面。

      转到部署

    2. 如需将代理的 SPIFFE ID 复制到剪贴板，请找到已部署代理所在的行，然后在该行的 身份 列中，点击 复制到剪贴板。 身份类似于以下内容： principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID。

后续步骤