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

借助Agent Identity，您可以使用 Agents CLI 和智能体开发套件 (ADK) 为您在 Gemini Enterprise Agent Platform 上的 Agent Runtime 中创建和部署的智能体预配代管式身份。然后，您部署的智能体可以向Google Cloud 服务进行身份验证，并从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. 通过创建配置文件来启用代理身份：

    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。

后续步骤