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

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

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

事前準備

  1. 啟用 Agent Identity API、Agent Platform API、Agent Registry API 和 App Hub API。

    啟用 API 時所需的角色

    如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「服務使用情形管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

    啟用 API

  2. 確認您具備專案的「Agent Platform 使用者」 (roles/aiplatform.user) 角色。

建立及部署代理程式

使用 google-agents-cli 建立範例代理，並透過 Agent Identity 部署：

  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. 新增下列匯入項目：

      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，請點選網路伺服器輸出內容提供的連結。

    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 控制台中服務專員遊樂區的連結。

  12. 擷取代理的 SPIFFE ID (代理身分)：

    1. 前往 Google Cloud 控制台的「Deployments」(部署作業) 頁面。

      前往「Deployments」(部署作業) 頁面

    2. 如要將代理程式的 SPIFFE ID 複製到剪貼簿，請找出已部署代理程式所在的資料列，然後點選該列「身分」欄中的 「複製到剪貼簿」。 身分看起來類似以下內容： principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID。

後續步驟