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

プレビュー

この機能は、サービス固有規約の「一般サービス規約」セクションの「一般提供前のサービス規約」の対象となります。pre-GA の機能は「現状のまま」で提供されるものであり、サポートが制限されることがあります。 詳細については、リリース ステージの説明をご覧ください。

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

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

始める前に

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 を使用してサンプル エージェントを作成し、エージェント ID でデプロイします。

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. 構成ファイルを作成して、エージェント ID を有効にします。

   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

   注: Cloud Shell でテストする場合は、CORS の問題を回避するために --allow_origins="*" フラグを追加する必要があります。

   エージェントを検証するには、次の操作を行います。

   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（エージェント ID）を取得します。

    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

次のステップ

• エージェント ID の概要
• エージェント ID 認証マネージャーの概要
• 認証マネージャーで 3-legged OAuth を使用して認証する
• 認証マネージャーで 2-legged OAuth を使用して認証する
• 認証マネージャーで API キーを使用して認証する
• エージェント ID 認証プロバイダを管理する