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

エージェント ID を使用すると、Agent CLI と Agent Development Kit（ADK）を使用して、Gemini Enterprise Agent Platform の Agent Runtime で作成してデプロイするエージェントにマネージド ID をプロビジョニングできます。デプロイされたエージェントは、手動で認証情報を管理することなく、Google Cloud サービスに対して認証を行い、Agent Identity Auth Manager から認証情報を取得できます。

始める前に

  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 リージョンでのみ使用可能なモデルを使用するには、エージェントがアクセスできるように 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 コンソール内のエージェントのプレイグラウンドへのリンクが出力されます。

  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 のようになります。

次のステップ