使用 Agent CLI 和 Agent Identity 建立及部署代理

本指南說明如何在 Gemini Enterprise Agent Platform 的 Agent Runtime 中建立及部署代理，並啟用代理身分。

代理身分會為已部署的代理指派安全的 SPIFFE 身分。代理程式會使用這個身分向 Google Cloud 服務進行驗證，並從代理程式身分驗證管理員擷取憑證。

事前準備

  1. 啟用 Agent Identity Connector API。

    啟用 API 時所需的角色

    如要啟用 API，您需要具備服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

    啟用 API

  2. 確認您具備專案的「Vertex AI 使用者」 (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. 從Google Cloud 控制台擷取代理的 SPIFFE ID (代理身分)：

    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)。

後續步驟