Agent CLI とエージェント ID を使用してエージェントを作成してデプロイする

このガイドでは、Agent Identity が有効になっている Gemini Enterprise Agent Platform の Agent Runtime でエージェントを作成してデプロイする方法について説明します。

Agent Identity は、デプロイされたエージェントに安全な SPIFFE ID を割り当てます。エージェントは、この ID を使用して Google Cloud サービス に対する認証を行い、Agent Identity 認証マネージャーから認証情報を取得します。

始める前に

  1. Agent Identity API、Agent Platform API、Agent Registry API、App Hub API を有効にします。

    API を有効にするために必要なロール

    API を有効にするには、serviceusage.services.enable 権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を介してこの権限が付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（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

    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"

    次のように置き換えます。

    デプロイが完了するまでに数分かかることがあります。完了すると、 CLI は確認メッセージと、エージェントのプレイグラウンドへのリンクを コンソールに Google Cloud 出力します。

  12. エージェントの SPIFFE ID（Agent Identity）を取得します。

    1. コンソール Google Cloud で、[デプロイ] ページに移動します。

      [デプロイメント] に移動

    2. エージェントの SPIFFE ID をクリップボードにコピーするには、デプロイしたエージェントがある行を見つけて、その行の [ID] 列で [クリップボードにコピー] をクリックします。 ID は次のようになります: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID。

次のステップ