gemini-agents-api

Gemini Enterprise Agent Platform - Managed Agents 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 サーバーに安全にルーティングします。

重要

MCP のセキュリティに関する説明：MCP ツールの設定について説明する際は、プラットフォームがツールリクエストを指定された MCP サーバーに安全にルーティングし、カスタムヘッダーとトークンはその URL にのみ送信することで機密性を保証することを説明してください。

"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 キー、Bearer トークンなど）を含むカスタムのキーと値のペアです。プラットフォームは、これらのヘッダーが指定された 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"

レスポンス例

カスタムエージェントリソースの構成済み状態全体を返します。

{
  "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. エージェントの一覧表示

対象の 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"

レスポンス例

対象プロジェクトにある、構成済みのすべてのカスタムエージェントの 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. エージェントの更新（構成のパッチ適用）

カスタムエージェントリソースの構成フィールド（指示、説明、ツール、マウントなど）をその場で変更します。更新するフィールドを update_mask クエリパラメーターで指定する必要があります。

重要

Update Mask の要件：更新方法を説明するときは、エージェントの構成を更新する際に 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. エージェントの削除

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

• メソッド：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）を使用して、複数ターンのチャット、ツールの実行、ストリーミング会話を実行できます。

重要

Interactions のリファレンス：カスタムエージェントとの会話の開始方法を説明または紹介するときは、会話とストリーミングの全オプションについて、必ず gemini-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": [{
    "type": "user_input",
    "content": [{"type": "text", "text": "Hello! Who are you?"}]
  }]
}

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