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

本指南介绍了如何在启用智能体身份的 Gemini Enterprise Agent Platform 上的 Agent Runtime 中创建和部署智能体。

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

准备工作

  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. 通过创建配置文件来启用代理身份：

    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（代理身份）：

    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。

后续步骤