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

代理身分可讓您使用 Agent CLI 和 Agent Development Kit (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 權限，才能啟用 API。如果您建立了專案，可能已透過擁有者角色 (roles/owner) 取得這項權限。否則，您可以透過 Service Usage 管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

    啟用 API

  2. 確認您具備專案的 Agent Platform 使用者 (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 ID：開頭必須是英文字母，且只能包含英文字母、數字和底線。

    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. 建立設定檔，啟用 Agent Identity：

    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 控制台中代理 Playground 的連結。

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

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

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

    2. 如要將代理的 SPIFFE ID 複製到剪貼簿，請找出已部署代理所在的資料列，然後在該列的「Identity」(身分) 欄中，按一下 「Copy to clipboard」(複製到剪貼簿)。身分大致如下：principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID。

後續步驟