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

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

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

始める前に

  1. Agent Identity API を有効にします。

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

    API を有効にするには、serviceusage.services.enable 権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を通じてこの権限が付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（roles/serviceusage.serviceUsageAdmin）を通じてこの権限を取得できます。ロールを付与する方法をご覧ください。

    API の有効化

  2. プロジェクトに対するVertex AI ユーザー （roles/aiplatform.user）ロールがあることを確認します。

エージェントを作成してデプロイする

agents-cli を使用してサンプル エージェントを作成し、Agent Identity でデプロイします。

  1. google-agents-cli と uv をインストールし、セットアップを実行します。

    pip install google-agents-cli uv
agents-cli setup

  2. プロトタイプ テンプレートを使用して新しいエージェント プロジェクトを作成します。

    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 など）に変更します。

    mv app AGENT_NAME

    次に、新しい名前を反映するように agent.py 構成ファイルを更新します。

    # In AGENT_PROJECT/AGENT_NAME/agent.py
app = App(
    root_agent=root_agent,
    name="AGENT_NAME",
)

  4. 構成ファイルを作成して Agent Identity を有効にします。

    echo '{ "identity_type": "AGENT_IDENTITY" }' > .agent_engine_config.json

  5. デプロイの依存関係の requirements.txt ファイルを作成します。

    echo "httpx" > requirements.txt
echo "google-auth" >> requirements.txt
echo "google-adk[agent_engines,agent-identity]" >> requirements.txt
echo "google-cloud-aiplatform[agent_engines,adk]>=1.153.1" >> requirements.txt

  6. プロジェクト ディレクトリ構造を確認します。

    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

    ローカルでエージェントを確認します。

    uv run adk web . --port 8501 --reload_agents

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

    1. http://localhost:8501 に移動します。
    2. チャット インターフェースでテスト プロンプトを送信して、レスポンスを確認します。

  7. エージェントを Google Cloudにデプロイします。

    uv run adk deploy agent_engine AGENT_NAME \
    --project="PROJECT_ID" \
    --region="LOCATION"

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

    • PROJECT_ID：プロジェクト ID。 Google Cloud
    • LOCATION: エージェントをデプロイするリージョン（us-west1 など）。

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

  8. コンソールからエージェントの SPIFFE ID（Agent Identity）を取得します。Google Cloud

    1. コンソールで、[Agent Platform] ページに移動します。 Google Cloud
    2. [デプロイ] タブをクリックし、デプロイしたエージェントを選択します。
    3. [Agent Identity] の値（principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID など）をコピーします。

次のステップ