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

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

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

准备工作

  1. 启用 Agent Identity Connector API。

    启用 API 所需的角色

    如需启用 API，您需要拥有 Service Usage Admin IAM 角色 (roles/serviceusage.serviceUsageAdmin)，该角色包含 serviceusage.services.enable 权限。了解如何授予角色。

    启用 API

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

创建和部署代理

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

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

    pip install google-agents-cli uv
agents-cli setup

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

    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) 匹配：

    mv app AGENT_NAME

    然后，更新 agent.py 配置文件以反映新名称：

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

  4. 通过创建配置文件来启用代理身份：

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

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

    echo "httpx" > requirements.txt
echo "google-auth" >> requirements.txt
echo "google-adk[agent_engines,agent-identity]" >> requirements.txt
echo "google-cloud-aiplatform[agent_engines,adk]>=1.153.1" >> requirements.txt

  6. 验证项目目录结构：

    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

    在本地验证您的代理：

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

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

    1. 前往 http://localhost:8501。
    2. 在聊天界面中，发送测试提示以验证响应。

  7. 将您的代理部署到 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

  8. 从控制台中检索代理的 SPIFFE ID（代理身份）：Google Cloud

    1. 在 Google Cloud 控制台中，前往 Agent Platform 页面。
    2. 点击部署 标签页，然后选择已部署的代理。
    3. 复制代理身份 值（例如 principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID）。

后续步骤