エージェントの作成と管理

このガイドでは、Agent Platform で Managed Agents API を使用するカスタム エージェント リソースを作成、取得、一覧表示、更新、削除する方法と、エージェント環境、Model Context Protocol（MCP）サーバーツール、スキルを構成する方法について説明します。

始める前に

エージェントを構成する前に、環境を設定します。

  1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Cloud de Confiance project.

  3. Enable the Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. Make sure that you have the following role or roles on the project: Agent Platform User (roles/aiplatform.user) or Agent Platform Administrator (roles/aiplatform.admin)

    Check for the roles

    1. In the Cloud de Confiance console, go to the IAM page.

      Go to IAM
    2. Select the project.

    3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

    4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

    Grant the roles

    1. In the Cloud de Confiance console, go to the IAM page.

      Go to IAM
    2. Select the project.
    3. Click Grant access.

    4. In the New principals field, enter your user identifier. This is typically the identifier for a user in a workforce identity pool. For details, see Represent workforce pool users in IAM policies, or contact your administrator.

    5. Click Select a role, then search for the role.
    6. To grant additional roles, click Add another role and add each additional role.
    7. Click Save.
  5. エージェントで Cloud de Confiance by S3NS Model Context Protocol（MCP）ツールを使用する場合は、ユーザー アカウントと関連するサービス アカウントの両方に MCP ツールユーザー（roles/mcp.toolUser）ロールを付与します。

エージェントを作成する

新しいカスタム エージェントを作成するには、CreateAgent メソッドを使用します。これは長時間実行オペレーションです。

ベース エージェント

base_agent は、エージェントに推論機能と実行環境へのアクセスを提供するコア オーケストレーション ハーネスです。スキルとライブラリを環境に挿入でき、コード実行、ファイル システム オペレーション、グラウンディングによる検索のためのサービスサイド ツールにアクセスできます。

エージェントを作成する場合、base_agent でサポートされる値は antigravity-preview-05-2026 のみです。

基本的なエージェントを作成

デフォルトのツールと Google Cloud Storage マウント ターゲットを使用して基本エージェントを作成するには、POST リクエストを送信します。

REST

リクエスト変数

API を呼び出す前に、次のように置き換えます。

  • PROJECT_ID: 実際の Cloud de Confiance by S3NS プロジェクト ID。
  • LOCATION: エージェントのリージョン ロケーション。global リージョンのみがサポートされています。

  • AGENT_ID: 新しいエージェントの一意のカスタム識別子。カスタム エージェント ID は、次の制約に従う必要があります。

    • 1 ～ 63 文字で指定してください。
    • 使用できるのは小文字、数字、ハイフンのみです。
    • 先頭は英文字、末尾は英文字または数字にする必要があります。

  • BASE_AGENT: 拡張するベース エージェントの名前。antigravity-preview-05-2026 を使用します。

  • AGENT_DESCRIPTION: エージェントのスコープの簡単な概要。

  • INSTRUCTIONS: エージェントに設定するシステム指示またはペルソナ。

  • GCS_BUCKET: マウントされた Google Cloud Storage バケットのフォルダパス セグメント（例: gs://cymbal-bucket-name）。 注: 別のプロジェクトからバケットをマウントするには、プロジェクトのサービス アカウントに read と write のバケットへのアクセス権を付与します。

  • network: セキュリティ上の理由から、環境内のネットワーク アクセスはオフになっています。アクセスを有効にするには、allowlist を指定する必要があります。allowlist でドメインとして * を使用すると、すべてのドメインへの接続が許可され、無制限のネットワーク アクセスが提供されます。

HTTP メソッドと URL

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

リクエストの本文（JSON）

{
  "id": "AGENT_ID",
  "base_agent": "BASE_AGENT",
  "description": "AGENT_DESCRIPTION",
  "system_instruction": "INSTRUCTIONS",
  "tools": [
    {"type": "code_execution"},
    {"type": "filesystem"},
    {"type": "google_search"},
    {"type": "url_context"}
  ],
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "GCS_BUCKET",
        "target": "/.agent"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}

curl コマンド

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -d '{
      "id": "AGENT_ID",
      "base_agent": "antigravity-preview-05-2026",
      "description": "AGENT_DESCRIPTION",
      "system_instruction": "INSTRUCTIONS",
      "tools": [
          {"type": "code_execution"},
          {"type": "filesystem"},
          {"type": "google_search"},
          {"type": "url_context"}
      ],
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "gcs",
                  "source": "GCS_BUCKET",
                  "target": "/.agent"
              }
          ],
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

レスポンスの例

{
  "name": "projects/1234567890/locations/global/agents/my-first-agent/operations/234567890123",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.CreateAgentOperationMetadata",
    "genericMetadata": {
      "createTime": "2026-05-12T23:50:16.933752Z",
      "updateTime": "2026-05-12T23:50:16.933752Z"
    }
  }
}

Python

このコードを実行する前に、[REST] タブで説明されている変数を設定します。

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

agent = client.agents.create(
    id="AGENT_ID",
    base_agent="antigravity-preview-05-2026",
    description="AGENT_DESCRIPTION",
    system_instruction="INSTRUCTIONS",
    tools=[
        {"type": "code_execution"},
        {"type": "google_search"},
        {"type": "url_context"},
    ],
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "gcs",
                "source": "GCS_BUCKET",
                "target": "/.agent",
            }
        ],
        "network": {
            "allowlist": [{"domain": "*"}]
        },
    },
)

JavaScript

このコードを実行する前に、[REST] タブで説明されている変数を設定します。

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const agent = await client.agents.create({
    id: "AGENT_ID",
    base_agent: "antigravity-preview-05-2026",
    description: "AGENT_DESCRIPTION",
    system_instruction: "INSTRUCTIONS",
    tools: [
        { type: "code_execution" },
        { type: "google_search" },
        { type: "url_context" },
    ],
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "gcs",
                source: "GCS_BUCKET",
                target: "/.agent",
            },
        ],
        network: {
            allowlist: [{ domain: "*" }],
        },
    },
});

Google のファーストパーティ ツールを使用してエージェントを作成する

Google のファーストパーティ ツール（Google 検索によるグラウンディングや URL コンテキストなど）を使用してエージェントを作成するには、エージェント構成の tools リストにこれらのツールを追加します。

REST

リクエスト変数

API を呼び出す前に、次のように置き換えます。

  • PROJECT_ID: 実際の Cloud de Confiance by S3NS プロジェクト ID。
  • LOCATION: エージェントのリージョン ロケーション。global リージョンのみがサポートされています。

  • AGENT_ID: 新しいエージェントの一意のカスタム識別子。カスタム エージェント ID は、次の制約に従う必要があります。

    • 1 ～ 63 文字で指定してください。
    • 使用できるのは小文字、数字、ハイフンのみです。
    • 先頭は英文字、末尾は英文字または数字にする必要があります。

  • AGENT_DESCRIPTION: エージェントのスコープの簡単な概要。

リクエストの本文（JSON）

{
  "id": "AGENT_ID",
  "base_agent": "antigravity-preview-05-2026",
  "description": "AGENT_DESCRIPTION",
  "tools": [
    {
      "type": "google_search"
    },
    {
      "type": "url_context"
    }
  ],
  "base_environment": {
    "type": "remote",
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}

curl コマンド

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -d '{
      "id": "AGENT_ID",
      "base_agent": "antigravity-preview-05-2026",
      "description": "AGENT_DESCRIPTION",
      "tools": [
          {
              "type": "google_search"
          },
          {
              "type": "url_context"
          }
      ],
      "base_environment": {
          "type": "remote",
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

MCP 構成を使用してエージェントを作成する

Agent Platform の Managed Agents API を使用して、事前構成済みの MCP サーバーツールを使用するエージェントを作成できます。

始める前に

事前構成済みの MCP サーバーツールを使用してエージェントを作成する前に、次の操作を行います。

  • ユーザー アカウントと関連付けられたサービス アカウントの両方に、MCP ツールユーザー（roles/mcp.toolUser）の Identity and Access Management（IAM）ロールを付与します。

  • 構成内の MCP サーバーが、ツールのリスト表示と実行に標準の HTTP POST を介して通信することを確認します。Agent Platform の Managed Agents API では、リモート MCP サーバーがストリーミング可能な HTTP サーバーである必要があります。MCP サーバーは MCP ストリーミング可能な HTTP トランスポートを実装する必要があります。ここで、tools/list と tools/call は HTTP POST を介して JSON-RPC として送信されます。

    非推奨の 2 エンドポイント HTTP+SSE トランスポート（個別の長時間有効な GET /sse ストリーム）はサポートされていません。

Google がホストする MCP を認可する

Google がホストする MCP サーバー（BigQuery など）の認可に署名なしトークンを使用している場合は、次の手順を完了します。

  1. OAuth スコープを追加する: 必要な OAuth 2.0 スコープを認証トークンに追加します。たとえば、BigQuery MCP を使用するには、リクエストに関連する BigQuery スコープを含めます。
  2. アクセスを検証する: OAuth Playground で認証フローをテストして、新しく構成したスコープで MCP サーバーにアクセスできるかどうかを確認します。
  3. ヘッダーを使用する: BigQuery などの Google MCP の場合、headers マップにプロジェクト名に設定された X-Goog-User-Project ヘッダーを含める必要があります。

たとえば、BigQuery MCP を使用するエージェントを作成するために使用されるリクエスト JSON 本文は、次のようになります。

{
  "name": "projects/<projectname>/locations/global/agents/data-analyst",
  "id": "data-analyst",
  "system_instruction": "You are a data analyst. Use the provided tools and data to perform analysis.",
  "tools": [
    { "type": "code_execution" },
    { "type": "filesystem" },
    { "type": "google_search" },
    { "type": "url_context" },
    {
      "type": "mcp_server",
      "name": "bigquery-mcp",
      "url": "https://bigquery.googleapis.com/mcp",
      "headers": {
        "Authorization": "Bearer ya29.a0AQyyyy",
        "X-Goog-User-Project": "project-nameyyyy"
      }
    }
  ],
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "gs://agents-1",
        "target": "/.agent/agents-1"
      }
    ],
    "network": {
      "allowlist": [ { "domain": "*" } ]
    }
  },
  "base_agent": "antigravity-preview-05-2026",
  "object": "agent"
}

エージェントを作成する

事前構成済みの MCP サーバーツールを使用してエージェントを作成するには、tools セクションに詳細を追加します。

REST

リクエスト変数

API を呼び出す前に、次のように置き換えます。

  • PROJECT_ID: 実際の Cloud de Confiance by S3NS プロジェクト ID。
  • LOCATION: エージェントのリージョン ロケーション。global リージョンのみがサポートされています。

  • AGENT_ID: 新しいエージェントの一意のカスタム識別子。カスタム エージェント ID は、次の制約に従う必要があります。

    • 1 ～ 63 文字で指定してください。
    • 使用できるのは小文字、数字、ハイフンのみです。
    • 先頭は英文字、末尾は英文字または数字にする必要があります。

  • AGENT_DESCRIPTION: エージェントのスコープの簡単な概要。

  • MCP_SERVER_NAME: MCP ツールのわかりやすい名前。

  • MCP_SERVER_URL: MCP サーバーのリモート HTTP ゲートウェイ URL。

  • MCP_HEADER_KEY: 省略可。認証用のヘッダーの名前（例: Authorization）。

  • MCP_HEADER_VALUE: 省略可。認証署名なしトークン（例: Bearer <token>）。

リクエストの本文（JSON）

{
  "id": "AGENT_ID",
  "base_agent": "antigravity-preview-05-2026",
  "description": "AGENT_DESCRIPTION",
  "tools": [
    {
      "type": "mcp_server",
      "name": "MCP_SERVER_NAME",
      "url": "MCP_SERVER_URL",
      "headers": {
        "MCP_HEADER_KEY": "MCP_HEADER_VALUE"
      }
    }
  ]
}

curl コマンド

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -d '{
      "id": "AGENT_ID",
      "base_agent": "antigravity-preview-05-2026",
      "description": "AGENT_DESCRIPTION",
      "tools": [
          {
              "type": "mcp_server",
              "name": "MCP_SERVER_NAME",
              "url": "MCP_SERVER_URL",
              "headers": {
                  "MCP_HEADER_KEY": "MCP_HEADER_VALUE"
              }
          }
      ]
  }'

Python

このコードを実行する前に、[REST] タブで説明されている変数を設定します。

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

agent = client.agents.create(
    id="AGENT_ID",
    base_agent="antigravity-preview-05-2026",
    description="AGENT_DESCRIPTION",
    tools=[
        {
            "type": "mcp_server",
            "name": "MCP_SERVER_NAME",
            "url": "MCP_SERVER_URL",
            "headers": {
                "MCP_HEADER_KEY": "MCP_HEADER_VALUE"
            },
        }
    ],
)

JavaScript

このコードを実行する前に、[REST] タブで説明されている変数を設定します。

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const agent = await client.agents.create({
    id: "AGENT_ID",
    base_agent: "antigravity-preview-05-2026",
    description: "AGENT_DESCRIPTION",
    tools: [
        {
            type: "mcp_server",
            name: "MCP_SERVER_NAME",
            url: "MCP_SERVER_URL",
            headers: {
                "MCP_HEADER_KEY": "MCP_HEADER_VALUE",
            },
        },
    ],
});

エージェントにスキルをアタッチする

エージェントの作成時に再利用可能なスキルを直接読み込むには、base_environment.sources 内にマウントします。

スキルは、次のいずれかの方法でアタッチできます。

  • Skill Registry: Skill Registry でプロジェクトに登録されているスキルをアタッチします。

  • Google Cloud Storage: Cloud Storage バケットからカスタムスキルを直接アタッチします。

    ベスト プラクティスとして、エージェントがスキルを検出しやすくするために、環境の /.agent/skills フォルダにスキルをマウントすることをおすすめします。

CLI のスキル

開発者は、選択した CLI に特殊なスキルをインストールして、エージェントとインタラクションをプログラムで管理することもできます。

スキル レジストリからスキルをアタッチする

エージェントの作成時に、再利用可能なスキルをスキル レジストリから直接読み込むには:

REST

リクエスト変数

API を呼び出す前に、次のように置き換えます。

  • PROJECT_ID: 実際の Cloud de Confiance by S3NS プロジェクト ID。
  • LOCATION: エージェントのリージョン ロケーション。global リージョンのみがサポートされています。
  • AGENT_ID: 新しいエージェントの一意のカスタム識別子。カスタム エージェント ID は、次の制約に従う必要があります。
    • 1 ～ 63 文字で指定してください。
    • 使用できるのは小文字、数字、ハイフンのみです。
    • 先頭は英文字、末尾は英文字または数字にする必要があります。
  • SKILL_RESOURCE_NAME: マウントするスキルまたはスキルのリストのリソースパス。次のいずれかの形式を指定できます。
    • スキル（デフォルト バージョン）: projects/{projectID}/locations/{location}/skills/{skillName}
    • 特定のバージョン: projects/{projectID}/locations/{location}/skills/{skillName}/skill_versions/{skill_version}
    • スキルのリスト: projects/{projectID}/locations/{location}/skills。これにより、指定された project/location から最大 100 個のスキルがサンドボックス環境にマウントされます。
    詳細については、スキルを一覧表示するをご覧ください。
リクエストの本文（JSON）
{
  "id": "AGENT_ID",
  "base_agent": "antigravity-preview-05-2026",
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "skill_registry",
        "source": "SKILL_RESOURCE_NAME",
        "target": "/.agent/skills"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}
curl コマンド
curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -d '{
      "id": "AGENT_ID",
      "base_agent": "antigravity-preview-05-2026",
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "skill_registry",
                  "source": "SKILL_RESOURCE_NAME",
                  "target": "/.agent/skills"
              }
          ],
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

Python

このコードを実行する前に、[REST] タブで説明されている変数を設定します。

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

agent = client.agents.create(
    id="AGENT_ID",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "skill_registry",
                "source": "SKILL_RESOURCE_NAME",
                "target": "./skills",
            }
        ],
        "network": {
            "allowlist": [{"domain": "*"}]
        },
    },
)

JavaScript

このコードを実行する前に、[REST] タブで説明されている変数を設定します。

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const agent = await client.agents.create({
    id: "AGENT_ID",
    base_agent: "antigravity-preview-05-2026",
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "skill_registry",
                source: "SKILL_RESOURCE_NAME",
                target: "./skills",
            },
        ],
        network: {
            allowlist: [{ domain: "*" }],
        },
    },
});

Google Cloud Storage からスキルを添付する

または、エージェントの作成時に Google Cloud Storage バケットからカスタムスキルを直接アタッチすることもできます。

Cloud Storage からスキルをマウントする場合は、次の要件に注意してください。

  • アップロードの要件: スキルフォルダ全体をバケットにアップロードする必要があります。
  • コンテンツの検証なし: バックエンドは、マウント前にフォルダのコンテンツを検証しません。標準のフォルダ アップロードと同様に動作します。
  • サイズ制限: 添付されたすべてのファイルは、サンドボックス環境のメモリ制限（合計で最大 4 GiB の RAM）の対象となります。
  • ベスト プラクティス: スキルの品質を最適化するには、agentskills.io/home に記載されている規則に従って、スキルフォルダ内のファイルを構成して準備します。

エージェントの作成時に Google Cloud Storage からスキルをアタッチするには:

REST

リクエスト変数

API を呼び出す前に、次のように置き換えます。

  • PROJECT_ID: 実際の Cloud de Confiance by S3NS プロジェクト ID。
  • LOCATION: エージェントのリージョン ロケーション。global リージョンのみがサポートされています。
  • AGENT_ID: 新しいエージェントの一意のカスタム識別子。カスタム エージェント ID は、次の制約に従う必要があります。
    • 1 ～ 63 文字で指定してください。
    • 使用できるのは小文字、数字、ハイフンのみです。
    • 先頭は英文字、末尾は英文字または数字にする必要があります。
  • GCS_SOURCE_PATH: スキルフォルダを含む Google Cloud Storage バケットのパス（例: gs://cymbal-bucket-name/my-skill-folder）。
リクエストの本文（JSON）
{
  "id": "AGENT_ID",
  "base_agent": "antigravity-preview-05-2026",
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "GCS_SOURCE_PATH",
        "target": "/.agent/skills"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}
curl コマンド
curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -d '{
      "id": "AGENT_ID",
      "base_agent": "antigravity-preview-05-2026",
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "gcs",
                  "source": "GCS_SOURCE_PATH",
                  "target": "./skills"
              }
          ],
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

Python

このコードを実行する前に、[REST] タブで説明されている変数を設定します。

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

agent = client.agents.create(
    id="AGENT_ID",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "gcs",
                "source": "GCS_SOURCE_PATH",
                "target": "./skills",
            }
        ],
        "network": {
            "allowlist": [{"domain": "*"}]
        },
    },
)

JavaScript

このコードを実行する前に、[REST] タブで説明されている変数を設定します。

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const agent = await client.agents.create({
    id: "AGENT_ID",
    base_agent: "antigravity-preview-05-2026",
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "gcs",
                source: "GCS_SOURCE_PATH",
                target: "./skills",
            },
        ],
        network: {
            allowlist: [{ domain: "*" }],
        },
    },
});

エージェントのリスト表示

プロジェクトに保存されているすべてのエージェントを一覧表示するには、GET リクエストを送信します。オプションのページ分けを使用して、ページあたりの結果数を制御できます。

REST

リクエスト変数

API を呼び出す前に、次のように置き換えます。

  • PROJECT_ID: 実際の Cloud de Confiance by S3NS プロジェクト ID。
  • LOCATION: エージェントを一覧表示するリージョン ロケーション。global リージョンのみがサポートされています。
  • PAGE_SIZE: 省略可。ページごとに返すエージェントの最大数。デフォルト値は 10、最大値は 100 です。
  • PAGE_TOKEN: 省略可。前回の ListAgents レスポンスから受け取ったページトークン。結果の次のページを取得するには、このトークンを指定します。

返されるエージェントの数が PAGE_SIZE より大きい場合、ListAgents レスポンスには nextPageToken フィールドが含まれます。エージェントの次のページを取得するには、次の ListAgents リクエストでこの nextPageToken の値を PAGE_TOKEN パラメータとして渡します。レスポンスに nextPageToken フィールドが返されなくなるまで、このプロセスを繰り返します。

HTTP メソッドと URL

GET https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents?page_size=PAGE_SIZE&page_token=PAGE_TOKEN

curl コマンド

curl -X GET "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents?page_size=PAGE_SIZE&page_token=PAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

レスポンスの例

{
  "agents": [
    {
      "name": "projects/1234567890/locations/global/agents/my-first-agent",
      "id": "my-first-agent",
      "created": "2026-05-12T23:50:16.933Z",
      "updated": "2026-05-12T23:50:21.159Z",
      "systemInstruction": "You are a helpful assistant to user."
    }
  ],
  "nextPageToken": "ABCDEFGHIJKLMNOPQRSTUVWXYZ=="
}

Python

このコードを実行する前に、[REST] タブで説明されている変数を設定します。

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

response = client.agents.list()

for agent in response.agents:
    print(agent)

JavaScript

このコードを実行する前に、[REST] タブで説明されている変数を設定します。

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const response = await client.agents.list();

if (response.agents) {
    for (const agent of response.agents) {
        console.log(agent);
    }
}

エージェントを取得する

指定したエージェントの完全な構成を取得するには、GET リクエストを使用します。

REST

リクエスト変数

API を呼び出す前に、次のように置き換えます。

  • PROJECT_ID: 実際の Cloud de Confiance by S3NS プロジェクト ID。

  • LOCATION: エージェントのリージョン ロケーション。global リージョンのみがサポートされています。

  • AGENT_ID: リクエストするカスタム エージェント構成の一意の ID。

HTTP メソッドと URL

GET https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID

curl コマンド

curl -X GET "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

レスポンスの例

{
  "name": "projects/vertex-agent-fishfood/locations/global/agents/my-first-agent",
  "id": "my-first-agent",
  "created": "2026-05-12T23:50:16.933Z",
  "updated": "2026-05-12T23:50:21.159Z",
  "systemInstruction": "You are a helpful assistant to user.",
  "tools": [
    {"type": "code_execution"},
    {"type": "filesystem"},
    {"type": "google_search"},
    {"type": "url_context"}
  ],
  "description": "A demo agent showcasing Environment and Skills use case.",
  "baseEnvironment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "gs://agents-api-sample-skills",
        "target": "/.agent"
      }
    ],
    "network": {
      "allowlist": [
        {"domain": "*"}
      ]
    }
  },
  "baseAgent": "antigravity-preview-05-2026",
  "object": "agent"
}

Python

このコードを実行する前に、[REST] タブで説明されている変数を設定します。

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

agent = client.agents.get(id="AGENT_ID")
print(agent)

JavaScript

このコードを実行する前に、[REST] タブで説明されている変数を設定します。

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const agent = await client.agents.get("AGENT_ID");
console.log(agent);

エージェントを更新する

既存のエージェントの構成を更新するには、PATCH リクエストを送信します。エージェントの ID は不変ですが、指示、ツール、環境変数などのパラメータは変更できます。update_mask クエリ パラメータを使用して、更新するフィールドを正確に指定します。これにより、変更するフィールドのみが影響を受け、他の構成は保持されます。

基本的なエージェントを更新する

エージェントのシステム指示を更新するには、update_mask=system_instruction を含む PATCH リクエストを送信します。

REST

リクエスト変数

API を呼び出す前に、次のように置き換えます。

  • PROJECT_ID: 実際の Cloud de Confiance by S3NS プロジェクト ID。
  • LOCATION: エージェントのリージョン。global リージョンのみがサポートされています。
  • AGENT_ID: パッチ更新のターゲット エージェント構成。
  • NEW_INSTRUCTIONS: 置き換える更新された指示構造または説明。

HTTP メソッドと URL

PATCH https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=system_instruction

リクエストの本文（JSON）

{
  "name": "AGENT_ID",
  "system_instruction": "NEW_INSTRUCTIONS"
}

curl コマンド

curl -X PATCH "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=system_instruction" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "system_instruction": "NEW_INSTRUCTIONS"
  }'

Python

JavaScript

Google のファースト パーティ製ツールを使用してエージェントを更新する

エージェントを更新して Google ファーストパーティ（1P）ツール（Google 検索によるグラウンディングや URL コンテキストなど）を有効にするには、update_mask=tools を含む PATCH リクエストを送信します。

REST

リクエスト変数

API を呼び出す前に、次のように置き換えます。

  • PROJECT_ID: 実際の Cloud de Confiance by S3NS プロジェクト ID。
  • LOCATION: エージェントのリージョン。global リージョンのみがサポートされています。
  • AGENT_ID: ターゲット エージェント ID。

リクエストの本文（JSON）

{
  "name": "AGENT_ID",
  "tools": [
    {
      "type": "google_search"
    },
    {
      "type": "url_context"
    }
  ]
}

curl コマンド

curl -X PATCH "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=tools" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "tools": [
          {
              "type": "google_search"
          },
          {
              "type": "url_context"
          }
      ]
  }'

MCP 構成でエージェントを更新する

エージェントに接続されている MCP ツールを変更するには、update_mask=tools を指定して PATCH リクエストを送信します。

REST

リクエスト変数

API を呼び出す前に、次のように置き換えます。

  • PROJECT_ID: 実際の Cloud de Confiance by S3NS プロジェクト ID。
  • LOCATION: エージェントのリージョン。global リージョンのみがサポートされています。
  • AGENT_ID: ターゲット エージェント ID。
  • NEW_MCP_SERVER_NAME: MCP ツールの更新されたラベル。
  • NEW_MCP_SERVER_URL: サーバーの新しい URL エンドポイント パラメータ。
  • NEW_MCP_HEADER_KEY: 省略可。認証用のヘッダーの名前（例: Authorization）。
  • NEW_MCP_HEADER_VALUE: 省略可。認証署名なしトークン（例: Bearer <token>）。

リクエストの本文（JSON）

{
  "name": "AGENT_ID",
  "tools": [
    {
      "type": "mcp_server",
      "name": "NEW_MCP_SERVER_NAME",
      "url": "NEW_MCP_SERVER_URL",
      "headers": {
        "NEW_MCP_HEADER_KEY": "NEW_MCP_HEADER_VALUE"
      }
    }
  ]
}

curl コマンド

curl -X PATCH "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=tools" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "tools": [
          {
              "type": "mcp_server",
              "name": "NEW_MCP_SERVER_NAME",
              "url": "NEW_MCP_SERVER_URL",
              "headers": {
                  "NEW_MCP_HEADER_KEY": "NEW_MCP_HEADER_VALUE"
              }
          }
      ]
  }'

Python

JavaScript

エージェントにスキルをアタッチする

エージェントの更新中に base_environment.sources 内のスキルをアタッチまたは変更するには、update_mask=base_environment を使用して PATCH リクエストを送信します。

スキルをアタッチするには、次のいずれかの方法を使用します。

  • Skill Registry: Skill Registry でプロジェクト内に登録されているスキルをアタッチします。

  • Google Cloud Storage: Cloud Storage バケットからカスタムスキルを直接アタッチします。

スキル レジストリからスキルをアタッチする

スキル レジストリに登録されているスキルをアタッチするには:

REST

リクエスト変数

API を呼び出す前に、次のように置き換えます。

  • PROJECT_ID: 実際の Cloud de Confiance by S3NS プロジェクト ID。
  • LOCATION: エージェントのリージョン。global リージョンのみがサポートされています。
  • AGENT_ID: ターゲット エージェント ID。
  • NEW_SKILL_RESOURCE_NAME: マウントするスキルまたはスキルリストのリソースパス。次のいずれかの形式を指定できます。
    • スキル（デフォルト バージョン）: projects/{projectID}/locations/{location}/skills/{skillName}
    • スキル バージョン（特定のバージョンに固定）: projects/{projectID}/locations/{location}/skills/{skillName}/skill_versions/{skill_version}
    • ListSkills（すべてのスキルをマウント）: projects/{projectID}/locations/{location}/skills。これにより、プロジェクト/ロケーション内の最大 100 個のスキルがサンドボックス環境にマウントされます。
    NEW_SKILL_RESOURCE_NAME の name 値を確認する方法については、スキルを一覧表示するをご覧ください。
リクエストの本文（JSON）
{
  "name": "AGENT_ID",
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "skill_registry",
        "source": "NEW_SKILL_RESOURCE_NAME",
        "target": "/.agent/skills"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}
curl コマンド
curl -X PATCH "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=base_environment" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "skill_registry",
                  "source": "NEW_SKILL_RESOURCE_NAME",
                  "target": "/.agent/skills"
              }
          ],
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

Python

JavaScript

Google Cloud Storage からスキルを添付する

または、エージェントの作成時に Google Cloud Storage バケットからカスタムスキルを直接アタッチすることもできます。

Cloud Storage からスキルをマウントする場合は、次の要件に注意してください。

  • アップロードの要件: スキルフォルダ全体をバケットにアップロードする必要があります。
  • コンテンツの検証なし: バックエンドは、マウント前にフォルダのコンテンツを検証しません。標準のフォルダ アップロードと同様に動作します。
  • サイズ制限: 添付されたすべてのファイルは、サンドボックス環境のメモリ制限（合計で最大 4 GiB の RAM）の対象となります。
  • ベスト プラクティス: スキルの品質を最適化するには、agentskills.io/home に記載されている規則に従って、スキルフォルダ内のファイルを構成して準備します。

Google Cloud Storage からスキルをアタッチするには:

REST

リクエスト変数

API を呼び出す前に、次のように置き換えます。

  • PROJECT_ID: 実際の Cloud de Confiance by S3NS プロジェクト ID。
  • LOCATION: エージェントのリージョン。global リージョンのみがサポートされています。
  • AGENT_ID: ターゲット エージェント ID。
  • NEW_GCS_SOURCE_PATH: スキルフォルダを含む Google Cloud Storage バケットのパス（例: gs://cymbal-bucket-name/my-skill-folder）。
リクエストの本文（JSON）
{
  "name": "AGENT_ID",
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "NEW_GCS_SOURCE_PATH",
        "target": "/.agent/skills"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}
curl コマンド
curl -X PATCH "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=base_environment" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "gcs",
                  "source": "NEW_GCS_SOURCE_PATH",
                  "target": "/.agent/skills"
              }
          ],
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

Python

JavaScript

エージェントを削除する

特定のカスタム エージェント構成を削除するには、DELETE リクエストを送信します。これは長時間実行オペレーションであり、構成を完全に削除します。Agent Runtime を削除すると、Agent Identity が無効になります。そのプリンシパルに権限を付与する IAM 統合アクセス ポリシー（UAP）は、ルールに無効なプリンシパルを保持します。さらに、ポリシー バインディングは有効なままです。機能していないプリンシパルを削除するには、UAP を更新して、ルールからプリンシパルを削除します。ポリシーにアクティブなプリンシパルが含まれていない場合は、ポリシー バインディングを削除します。

エージェントを削除する場合は、URL に必要な情報をすべて指定し、JSON リクエスト本文は含めないでください。

REST

リクエスト変数

API を呼び出す前に、次のように置き換えます。

  • PROJECT_ID: 実際の Cloud de Confiance by S3NS プロジェクト ID。
  • LOCATION: エージェントのリージョン。global リージョンのみがサポートされています。
  • AGENT_ID: 削除するエージェントの ID。

HTTP メソッドと URL

DELETE https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID

curl コマンド

curl -X DELETE "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

レスポンスの例

{
  "name": "projects/1234567890/locations/global/operations/234567890123",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.DeleteOperationMetadata",
    "genericMetadata": {
      "createTime": "2026-05-13T02:15:45.936287Z",
      "updateTime": "2026-05-13T02:15:45.936287Z"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

Python

このコードを実行する前に、[REST] タブで説明されている変数を設定します。

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

response = client.agents.delete(id="AGENT_ID")
print(response)

JavaScript

このコードを実行する前に、[REST] タブで説明されている変数を設定します。

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const response = await client.agents.delete("AGENT_ID");
console.log(response);

長時間実行オペレーションの詳細を取得する

CreateAgent、UpdateAgent、DeleteAgent などのオペレーションは非同期です。最初の API レスポンスは、オペレーション ID を含む name フィールドを返します。この ID で GetOperation を使用して、進行状況をポーリングします。

REST

リクエスト変数

API を呼び出す前に、次のように置き換えます。

  • PROJECT_ID: 実際の Cloud de Confiance by S3NS プロジェクト ID。
  • LOCATION: オペレーションのリージョン ロケーション。global リージョンのみがサポートされています。
  • OPERATION_ID: 最初の LRO レスポンスの name フィールドから抽出されたオペレーション ID。

HTTP メソッドと URL

GET https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID

curl コマンド

curl -X GET "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

Python

JavaScript

ネットワーク アクセスを構成する

デフォルトでは、Agents API を使用してエージェントを作成すると、サンドボックスはネットワーク アクセスを無効にします。無制限のアクセスを許可するには、* を使用します。

たとえば、次のコードに示すように allowlist で * を使用すると、すべてのドメインにアクセスできます。

"base_environment": {
    "type": "remote",
    "sources": [
        {
            "type": "skill_registry",
            "source": "SKILL_RESOURCE_NAME",
            "target": "./skills"
        }
    ],
    "network": {
        "allowlist": [{"domain": "*"}]
    }
}

次のステップ

ガイド

実行時にエージェントとやり取りする方法、セッション状態を管理する方法、構成を動的にオーバーライドする方法について説明します。