gemini-managed-agents-api

Gemini Enterprise Agent Platform - マネージドエージェント API スキル

このスキルでは、Gemini Enterprise Agent Platform（Agent Platform）上のカスタム Agent リソースをプログラムから管理するための手順、REST リクエストのエンドポイント、JSON ペイロードの構造をすべて説明します。

Managed Agents API は、プラットフォームのコントロールプレーンを構成します。この API を使用すると、システム指示、サンドボックス化されたファイル、カスタムスキルレジストリ、ローカル／リモートツールを備えた、個別に設定されたステートフルなエージェントコンテナをプロビジョニング、取得、更新、削除できます。

1. 認証とセットアップ

コントロールプレーンへのすべての REST リクエストには、Application Default Credentials（ADC）から取得した Bearer トークンを含め、本番環境のグローバルエンドポイントを指定する必要があります。

1. 環境変数を設定する

リクエストを実行する前に、必要なプロジェクト変数とアクセストークンを設定します。

export PROJECT_ID="your-project-id"
export LOCATION="global"
export ACCESS_TOKEN=$(gcloud auth print-access-token)

重要

API のロケーションサポート： LOCATION 環境変数には、Gemini Enterprise Agent Platform のManaged Agents APIがサポートされているリージョンのロケーションを設定する必要があります（例：global、または利用可能なその他のリージョンエンドポイント）。

2. エンドポイント URL

本番環境の Agents コントロールプレーンエンドポイントは次のとおりです。

https://aiplatform.googleapis.com/v1beta1/projects/{PROJECT_ID}/locations/{LOCATION}/agents

---

2. エージェントのプログラムによる管理（コントロールプレーン CRUD）

1. エージェントの作成（長時間実行オペレーション）

新しいエージェントリソースを作成するには、カスタム構成を指定して POST リクエストを送信します。リモートのファイル、フォルダー、スキルをGoogle Cloud Storage バケットからエージェントコンテナのワークスペースに直接マウントできます。エージェントの作成は長時間実行オペレーション（LRO）であり、非同期ジョブが起動します。

• メソッド：POST
• エンドポイント：https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents

リクエストペイロード

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "id": "my-custom-agent",
    "base_agent": "antigravity-preview-05-2026",
    "description": "A professional agent configured with remote tools and mounted Cloud Storage directories.",
    "system_instruction": "You are a helpful, domain-expert assistant.",
    "tools": [
      {"type": "code_execution"},
      {"type": "filesystem"},
      {"type": "google_search"},
      {"type": "url_context"}
    ],
    "base_environment": {
      "type": "remote",
      "sources": [
        {
          "type": "gcs",
          "source": "gs://your-agent-bucket-name/skills",
          "target": "/.agent/skills"
        }
      ],
      "network": {
        "allowlist": [
          { "domain": "*" }
        ]
      }
    }
  }'

LRO オペレーションのレスポンス

エージェントのプロビジョニングには少し時間がかかるため、エンドポイントはオペレーション追跡オブジェクトをすぐに返します。

{
  "name": "projects/1234567890/locations/global/operations/operation-987654321-abcde",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.CreateAgentOperationMetadata",
    "genericMetadata": {
      "createTime": "2026-05-14T19:00:00.123456Z",
      "updateTime": "2026-05-14T19:00:01.654321Z"
    }
  }
}

［上級］スキルレジストリのリソースをマウントする

Cloud Storage ではなく Skill Registry サービスからスキルを直接マウントするには、ペイロード内の Cloud Storage ソース項目を置き換えます。

"sources": [
  {
    "type": "skill_registry",
    "source": "projects/your-project-id/locations/global/skills/my-math-skill/revisions/123456789012",
    "target": "/.agent/skills"
  }
]

［上級］Model Context Protocol（MCP）サーバーの設定

エージェントにサードパーティ製 MCP サーバーを設定するには、作成リクエストの "tools" パラメーター配列にサーバーのメタデータを直接追加します。プラットフォームは、ツール実行リクエストを外部 MCP サーバーに安全にルーティングします。

"tools": [
  {
    "type": "mcp",
    "name": "my-mcp-server",
    "url": "https://mcp.yourcompany.com/api",
    "headers": {
      "Authorization": "Bearer YOUR_MCP_AUTH_TOKEN"
    }
  }
]

• name：MCP サーバーの説明的な名前です。
• url：外部 MCP サーバーのエンドポイント URL です。
• headers：（任意）サーバーへの呼び出しに必要な認証トークン（API キー、ベアラートークンなど）を含むカスタムのキーと値のペアです。これらのヘッダーは、指定された MCP サーバー URL にのみ送信されることがプラットフォームによって保証されます。

ヒント

インタラクション時の MCP のオーバーライド（データプレーン）： interactions.create の "tools" ペイロード内に "type": "mcp_server" を渡すことで、会話インタラクションの作成時（データプレーン）に MCP ツールを動的にオーバーライドしたり、直接指定したりできます。詳細は、Interactions API のドキュメントを参照してください。

---

2. LRO ステータスのポーリング

エージェント作成のステータスを追跡し、最終的に準備完了したリソースを取得するには、作成レスポンスの name フィールドで返されるオペレーション URL をポーリングします。

• メソッド：GET
• エンドポイント：https://aiplatform.googleapis.com/v1beta1/{OPERATION_NAME}

curl -X GET "https://aiplatform.googleapis.com/v1beta1/projects/1234567890/locations/global/operations/operation-987654321-abcde" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json"

処理中のレスポンス

{
  "name": "projects/1234567890/locations/global/operations/operation-987654321-abcde",
  "metadata": { ... }
}

完了時の成功レスポンス

コンテナの準備が完了すると、"done": true が設定され、完了した Agent リソースの説明が "response" 内に格納されます。

{
  "name": "projects/1234567890/locations/global/operations/operation-987654321-abcde",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.Agent",
    "name": "projects/your-project-id/locations/global/agents/my-custom-agent",
    "base_agent": "antigravity-preview-05-2026",
    "description": "A professional agent configured with remote tools and mounted Cloud Storage directories.",
    "system_instruction": "You are a helpful, domain-expert assistant."
  }
}

---

3. エージェントの取得

既存のカスタムエージェントの構成メタデータ、ツール、環境設定を取得します。

• メソッド：GET
• エンドポイント：https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents/{AGENT_ID}

curl -X GET "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/agents/my-custom-agent" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json"

レスポンス例

カスタム Agent リソースの設定済み状態をすべて返します。

{
  "name": "projects/your-project-id/locations/global/agents/my-custom-agent",
  "base_agent": "antigravity-preview-05-2026",
  "description": "A professional agent configured with remote tools and mounted Cloud Storage directories.",
  "system_instruction": "You are a helpful, domain-expert assistant.",
  "tools": [
    {"type": "code_execution"},
    {"type": "filesystem"},
    {"type": "google_search"},
    {"type": "url_context"}
  ],
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "gs://your-agent-bucket-name/skills",
        "target": "/.agent/skills"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}

---

4. Agent の一覧表示

対象の Google Cloud プロジェクト配下にある、設定済みのすべてのカスタムエージェントの一覧を取得します。

• メソッド: GET
• エンドポイント: https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents

curl -X GET "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/agents" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json"

レスポンス例

対象プロジェクト配下にある、設定済みのすべてのカスタム Agent の JSON リストを返します。

{
  "agents": [
    {
      "name": "projects/your-project-id/locations/global/agents/my-custom-agent",
      "base_agent": "antigravity-preview-05-2026",
      "description": "A professional agent configured with remote tools and mounted Cloud Storage directories.",
      "system_instruction": "You are a helpful, domain-expert assistant."
    },
    {
      "name": "projects/your-project-id/locations/global/agents/my-telecom-agent",
      "base_agent": "antigravity-preview-05-2026",
      "description": "A highly specialized telecom support agent.",
      "system_instruction": "You are a professional telecom support agent. Follow system policies carefully."
    }
  ]
}

---

5. Agent の更新（設定のパッチ適用）

カスタムエージェントリソースの設定フィールド（指示、説明、ツール、マウントなど）をその場で変更します。更新するフィールドは、update_mask クエリパラメーターを使用して必ず指定してください。

• メソッド: PATCH
• エンドポイント: https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents/{AGENT_ID}?update_mask=system_instruction

curl -X PATCH "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/agents/my-custom-agent?update_mask=system_instruction" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-custom-agent",
    "system_instruction": "You are a highly specialized telecom support agent. Follow system policies carefully."
  }'

---

6. Agent の削除

不要になったカスタム Agent リソースを削除して、バックエンドのワークスペースコンテナを解放します。

• メソッド: DELETE
• エンドポイント: https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents/{AGENT_ID}

curl -X DELETE "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/agents/my-custom-agent" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

レスポンス例

削除リクエストが成功すると、HTTP ステータス 200 OK とともに空の JSON レスポンスボディが返されます。

{}

---

3. カスタムエージェントとのやり取り（データプレーン）

コントロールプレーン（このスキル）を使用してカスタムのステートフルエージェントをプログラムで作成、プロビジョニングしたら、データプレーン（Interactions API）を使用して、複数ターンのチャット、ツールの実行、ストリーミング会話を行えます。

カスタムエージェントとやり取りするには：

1. エージェントのリソースパス名を取得します（例：projects/{PROJECT_ID}/locations/global/agents/{AGENT_ID}）。
2. データプレーンの会話リクエスト内の**agent**パラメーターに、このリソースパスを直接渡します。

Python の例

interaction = client.interactions.create(
    agent="projects/your-project-id/locations/global/agents/my-custom-agent",
    input="Hello! Who are you?"
)

REST / curl の例

{
  "agent": "projects/your-project-id/locations/global/agents/my-custom-agent",
  "input": [{
    "role": "user",
    "content": [{"type": "text", "text": "Hello! Who are you?"}]
  }]
}

プロビジョニング済みエージェントとの会話を実行するための詳しい手順、Python および TS/JS のコードブロック、ストリーミングの設定については、gemini-interactions-api スキルガイド（../gemini-interactions-api/SKILL.md）を参照してください。