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

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

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

准备工作

  1. 启用 Agent Identity API。

    启用 API 所需的角色

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

    启用 API

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

创建和部署智能体

使用 agents-cli 创建示例智能体，并使用 Agent Identity 部署该智能体：

  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. 通过创建配置文件来启用 Agent Identity：

    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 会输出确认消息，以及 指向控制台中智能体 Playground 的链接。 Google Cloud

  8. 从控制台检索智能体的 SPIFFE ID (Agent Identity)：Google Cloud

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

后续步骤