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

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

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

准备工作

  1. 启用 Agent Identity API、Agent Platform API、Agent Registry API 和 App Hub API（如果尚未启用）。

    启用 API 所需的角色

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

    启用 API

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

创建和部署代理

使用 google-agents-cli 创建示例代理，并使用代理身份信息部署该代理：

  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. 在导入内容后添加以下子类：

      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. 将代理部署到 Cloud de Confiance：

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

    替换以下内容：

    • PROJECT_ID：您的 Cloud de Confiance 项目 ID。

    • LOCATION：您希望在其中部署代理的受支持区域（例如 us-west1）。

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

  12. 检索代理的 SPIFFE ID（Agent Identity）：

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

      转到部署

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

后续步骤