Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

エージェントを操作する

このプロダクトは一般提供前サービスであり、サービス固有の規約の「一般サービス規約」セクションの「一般提供前サービス規約」、サービス固有の規約の「エージェント AI サービス」規約、生成 AI プレビュー版プロダクトに関する追加利用規約の対象となります。pre-GA のプロダクトと機能では、サポートが制限されることがあるほか、他の pre-GA のバージョンとの互換性のない変更が行われる場合があります。詳細については、リリースステージの説明をご覧ください。

これらの Pre-GA プロダクトは、内部テストとレビューのさまざまな段階にあります。そのため、これらのプロダクトで、機密情報やその他の機密データを使用しないでください。これらのプロダクトは、限定的なテストと評価のみを目的としてお客様に提供されるものであり、商用目的または本番環境での使用はできません。

このガイドでは、Interactions API を使用して、Agent Platform の Managed Agents API でデプロイされたエージェントを操作する方法について説明します。Agents API とビルド済みの Antigravity ベースエージェントを使用して構築されたカスタムエージェントを操作する方法（動的に構成する方法など）について学習します。また、環境 ID（env_id）を使用してサンドボックス環境を管理、再利用する方法や、インタラクション中に Model Context Protocol（MCP）サーバーなどの構成を動的にオーバーライドする方法についても説明します。

API の詳細については、Interaction API リファレンスドキュメントをご覧ください。

始める前に

エージェントとのやり取りを開始する前に、環境を設定します。

Google Cloud アカウントにログインします。 Google Cloudを初めて使用する場合は、アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

In the Google Cloud console, on the project selector page, select or create a Google Cloud 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

Verify that billing is enabled for your Google Cloud project.

Enable the Agent Platform API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

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

In the Google Cloud console, go to the IAM page.
Go to IAM
Select the project.
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.
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

In the Google Cloud console, go to the IAM page.
Go to IAM
Select the project.
Click Grant access.
In the New principals field, enter your user identifier. This is typically the email address for a Google Account.
Click Select a role, then search for the role.
To grant additional roles, click Add another role and add each additional role.
Click Save.

In the Google Cloud console, on the project selector page, select or create a Google Cloud 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

Verify that billing is enabled for your Google Cloud project.

Enable the Agent Platform API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

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

In the Google Cloud console, go to the IAM page.
Go to IAM
Select the project.
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.
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

In the Google Cloud console, go to the IAM page.
Go to IAM
Select the project.
Click Grant access.
In the New principals field, enter your user identifier. This is typically the email address for a Google Account.
Click Select a role, then search for the role.
To grant additional roles, click Add another role and add each additional role.
Click Save.

エージェントが Google Cloud Model Context Protocol（MCP）ツールを使用する場合は、ユーザーアカウントと関連付けられたサービスアカウントの両方に MCP ツールユーザー（roles/mcp.toolUser）ロールを付与します。

Antigravity エージェントを操作する

Agent Platform で Managed Agents API を使用する最も簡単な方法は、ファーストパーティの Antigravity ベースエージェントと直接やり取りすることです。カスタムエージェントリソースを作成する必要はありません。エージェントをオンザフライで呼び出すことができます。

インタラクションを開始するには、antigravity-preview-05-2026（または最新のプレビューバリアント）などのベースエージェントターゲットを指定し、オンザフライのリモート環境をリクエストします。

REST

リクエスト変数

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

PROJECT_ID: 実際の Google Cloud プロジェクト ID。
LOCATION: インタラクションのリージョンロケーション。global リージョンのみがサポートされています。

HTTP メソッドと URL

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

リクエストの本文（JSON）

{
  "stream": true,
  "background": true,
  "store": true,
  "agent": "antigravity-preview-05-2026",
  "environment": {
    "type": "remote"
  },
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "Who are you, can you execute python code? Show me an example."
        }
      ]
    }
  ]
}

`curl` コマンド

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "stream": true,
      "background": true,
      "store": true,
      "agent": "antigravity-preview-05-2026",
      "environment": {"type": "remote"},
      "input": [
          {
              "type": "user_input",
              "content": [
                  {
                      "type": "text",
                      "text": "Who are you, can you execute python code? Show me an example."
                  }
              ]
          }
      ]
  }'

レスポンスの例

最初のやり取りの後、サービスはストリーミングレスポンスを返します。interaction.complete データに含まれる interaction.id と environment_id は、後続の呼び出しでセッションの状態を維持するために使用できます。interaction.id は会話履歴を継続するために使用され、environment_id は同じサンドボックス環境を再利用するために使用されます。詳細については、セッションの状態を管理するをご覧ください。

event: interaction.complete
data: {
  "interaction": {
    "id": "1234567890",
    "status": "completed",
    "usage": {
      "total_tokens": 51132,
      "total_input_tokens": 48984,
      "input_tokens_by_modality": [
        {
          "modality": "text",
          "tokens": 48984
        }
      ],
      "total_output_tokens": 769,
      "output_tokens_by_modality": [
        {
          "modality": "text",
          "tokens": 769
        }
      ],
      "total_thought_tokens": 1379
    },
    "created": "2026-05-15T22:26:05Z",
    "updated": "2026-05-15T22:26:05Z",
    "environment_id": "env_CAE1234567890",
    "object": "interaction"
  },
  "event_type": "interaction.complete"
}

Python

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

from google import genai

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

stream = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Who are you, can you execute python code? Show me an example.",
    environment={"type": "remote"},
    stream=True,
    background=True,
    store=True,
)

for event in stream:
    print(event)

ストリーミングレスポンスは InteractionSSEEvent オブジェクトを生成します。最後の interaction.complete イベントには environment_id とインタラクション id が含まれており、これらを後続の呼び出しで再利用して、セッション状態と会話履歴を維持できます。詳細については、セッションの状態を管理するをご覧ください。

JavaScript

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

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

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

const stream = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "Who are you, can you execute python code? Show me an example.",
    environment: { type: "remote" },
    stream: true,
    background: true,
    store: true,
});

for await (const event of stream) {
    console.log(event);
}

ストリーミングレスポンスはイベントオブジェクトを生成します。最後の interaction.complete イベントには environment_id とインタラクション id が含まれており、これらを後続の呼び出しで再利用して、セッション状態と会話履歴を維持できます。詳細については、セッションの状態を管理するをご覧ください。

Agents API を使用して作成されたカスタムエージェントを操作する

エージェントを作成して管理するで説明したように作成されたカスタムエージェントを操作するには、エージェント ID を使用して指定する必要があります。

カスタムエージェントを取得または一覧表示して ID を確認する方法については、エージェントを一覧表示するをご覧ください。

環境の構成と初期化

カスタムエージェントとやり取りする場合:

デフォルトの動作: デフォルトの環境でエージェントを作成する場合は、リクエストで AGENT_ID を指定します。
環境を明示的に定義する: エージェントの作成時に環境構成を定義しなかった場合は、最初のインタラクションリクエストの environment ブロックで環境を明示的に定義する必要があります。

次に例を示します。
```
"environment": {"type": "remote"}
```

特定のタスク要件を満たすために、最初の Interaction API 呼び出し時にサンドボックス環境で機能を動的に構成できます。次に例を示します。

Cloud Storage を使用してスキルをアタッチする: Cloud Storage バケットをアタッチして、大容量のデータや永続的なファイルディレクトリをコンテナファイルシステムに読み込みます。
スキルレジストリを使用してスキルを関連付ける: 特定の機能やランタイムワークフローを提供するためのカスタムツール、スクリプト、事前パッケージ化されたエージェントスキルのリストを指定します。スキルレジストリをご覧ください。

環境構成の構造のリストと、マルチターン会話の状態を維持する方法の例については、環境 ID を使用してセッションの状態を管理するをご覧ください。

カスタムエージェントにインタラクションを送信する

エージェント ID を指定して、カスタムエージェントにインタラクションを送信します。

REST

リクエスト変数

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

PROJECT_ID: 実際の Google Cloud プロジェクト ID。
LOCATION: global リージョンのみがサポートされています。
AGENT_ID: 登録済みエージェントリソースのカスタム識別子。カスタムエージェントを取得または一覧表示して ID を確認する方法については、エージェントを一覧表示するをご覧ください。

HTTP メソッドと URL

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

リクエストの本文（JSON）

{
  "stream": true,
  "background": true,
  "store": true,
  "agent": "AGENT_ID",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "Tell me the name of python packages used for data analysis."
        }
      ]
    }
  ]
}

`curl` コマンド

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "stream": true,
      "background": true,
      "store": true,
      "agent": "AGENT_ID",
      "input": [
          {
              "type": "user_input",
              "content": [
                  {
                      "type": "text",
                      "text": "Tell me the name of python packages used for data analysis."
                  }
              ]
          }
      ]
  }'

レスポンスの例

data: {
  "interaction": {
    "id": "1234567890",
    "status": "completed",
    "usage": {
      "total_tokens": 7558,
      "total_input_tokens": 6822,
      "input_tokens_by_modality": [
        {
          "modality": "text",
          "tokens": 6822
        }
      ],
      "total_output_tokens": 278,
      "output_tokens_by_modality": [
        {
          "modality": "text",
          "tokens": 278
        }
      ],
      "total_thought_tokens": 458
    },
    "created": "2026-05-15T22:38:56Z",
    "updated": "2026-05-15T22:38:56Z",
    "environment_id": "env_CAE1234567890",
    "object": "interaction"
  },
  "event_type": "interaction.complete"
}

Python

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

from google import genai

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

stream = client.interactions.create(
    agent="AGENT_ID",
    input="Tell me the name of python packages used for data analysis.",
    stream=True,
    background=True,
    store=True,
)

for event in stream:
    print(event)

JavaScript

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

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

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

const stream = await client.interactions.create({
    agent: "AGENT_ID",
    input: "Tell me the name of python packages used for data analysis.",
    stream: true,
    background: true,
    store: true,
});

for await (const event of stream) {
    console.log(event);
}

セッションの状態とマルチターンのインタラクションを管理する

デフォルトでは、特定の環境コンテナまたは会話履歴をターゲットにしない限り、インタラクションはステートレスです。マルチターンのアシスタントフローでは、会話間でローカルファイル、コード実行コンテキスト、システム変更、ランタイムインストールされたオープンソースソフトウェアライブラリ、会話履歴を保持できます。

会話を続けるには: 前回のやり取りの ID を previous_interaction_id パラメータに渡します。
作成した環境を引き続き使用するには: 前のやり取りで返された環境 ID を environment パラメータに渡します。

environment フィールドで次のパラメータを使用して、主要な環境構成を選択できます。

JSON 構造	説明
`"environment": {"type": "remote"}`	新しい標準サンドボックス環境をプロビジョニングします。このオプションは、最初のやり取りで使用します。
`"environment": "env_CAEQ..."`	既存の永続サンドボックスコンテナを再利用し、この環境 ID に関連付けられているすべてのライブラリ、スクリプト、ファイル、状態を保持します。
`"environment": {"type": "remote", "sources": [{"type": "gcs", "source": "gs://YOUR_BUCKET/YOUR_FILE", "target": "YOUR_TARGET_PATH"}]}`	新しいリモートサンドボックスをプロビジョニングし、指定された `sources`（Google Cloud Storage に保存されているものなど）のカスタムスキルまたはファイルでプリロードします。

同じサンドボックスコンテナを再利用して会話を継続する後続のインタラクションリクエストを送信するには、返された environment_id を environment フィールドに渡し、previous_interaction_id を指定します。次の例は、エージェントとやり取りするときにステートフルセッションを継続する方法を示しています。

REST

リクエスト変数

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

PROJECT_ID: 実際の Google Cloud プロジェクト ID。
LOCATION: global リージョンのみがサポートされています。
AGENT_ID: 登録済みエージェントリソース（または antigravity-preview-05-2026）のカスタム識別子。
PREVIOUS_INTERACTION_ID: 前回のインタラクションから返されたインタラクション ID。
ENV_ID: 前回のインタラクションから返された環境 ID。

HTTP メソッドと URL

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

リクエストの本文（JSON）

{
  "stream": true,
  "background": true,
  "store": true,
  "agent": "AGENT_ID",
  "previous_interaction_id": "PREVIOUS_INTERACTION_ID",
  "environment": "ENV_ID",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "What did I ask you before and what did you do?"
        }
      ]
    }
  ]
}

`curl` コマンド

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "stream": true,
      "background": true,
      "store": true,
      "agent": "AGENT_ID",
      "previous_interaction_id": "PREVIOUS_INTERACTION_ID",
      "environment": "ENV_ID",
      "input": [
          {
              "type": "user_input",
              "content": [
                  {
                      "type": "text",
                      "text": "What did I ask you before and what did you do?"
                  }
              ]
          }
      ]
  }'

Python

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

from google import genai

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

stream = client.interactions.create(
    agent="AGENT_ID",
    input="What did I ask you before and what did you do?",
    previous_interaction_id="PREVIOUS_INTERACTION_ID",
    environment="ENV_ID",
    stream=True,
    background=True,
    store=True,
)

for event in stream:
    print(event)

Python SDK で、既存のサンドボックスコンテナを再利用するには、environment_id 文字列を environment パラメータとして直接渡します。会話履歴を続けるには、previous_interaction_id を使用します。

JavaScript

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

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

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

const stream = await client.interactions.create({
    agent: "AGENT_ID",
    input: "What did I ask you before and what did you do?",
    previous_interaction_id: "PREVIOUS_INTERACTION_ID",
    environment: "ENV_ID",
    stream: true,
    background: true,
    store: true,
});

for await (const event of stream) {
    console.log(event);
}

JavaScript SDK では、既存のサンドボックスコンテナを再利用するために、environment_id 文字列を environment パラメータとして直接渡します。会話履歴を続けるには、previous_interaction_id を使用します。

インタラクション中に構成をオーバーライドする

通常、カスタムエージェント定義にはツール、スキル、サードパーティ接続のデフォルト構成が含まれますが、基盤となるエージェントリソース構成を変更することなく、インタラクションごとにこれらの定義を動的に調整できます。

一般的なユースケースは、実行時に Model Context Protocol（MCP）サーバーへの接続を動的にオーバーライドすることです。インタラクションリクエストの本文で指定されたツールまたは MCP サーバーは、そのインタラクションターン中、エージェントの事前構成済みツールを完全にオーバーライドします。

インタラクション時に MCP サーバーをオーバーライドまたは定義するには、インタラクションリクエストの tools リスト内に mcp_server タイプのツールを追加します。

REST

リクエスト変数

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

PROJECT_ID: 実際の Google Cloud プロジェクト ID。
LOCATION: インタラクションのロケーション。global リージョンのみがサポートされています。
AGENT_ID: エージェントリソースのカスタム識別子。
MCP_SERVER_URL: 新しい MCP サーバーのリモート HTTP ゲートウェイ URL。
MCP_SERVER_NAME: ターゲット MCP ホストドメインの説明ラベル。
MCP_HEADER_KEY: 省略可。ヘッダーキー名（Authorization など）。
MCP_HEADER_VALUE: 省略可。認証情報の値（例: Bearer <token>）。

HTTP メソッドと URL

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

リクエストの本文（JSON）

{
  "stream": true,
  "background": true,
  "store": true,
  "agent": "agents/AGENT_ID",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "Analyze our database and summarize recent purchase events."
        }
      ]
    }
  ],
  "tools": [
    {
      "type": "mcp_server",
      "url": "MCP_SERVER_URL",
      "name": "MCP_SERVER_NAME",
      "headers": {
        "MCP_HEADER_KEY": "MCP_HEADER_VALUE"
      }
    }
  ]
}

`curl` コマンド

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
     "stream": true,
     "background": true,
     "store": true,
     "agent": "agents/AGENT_ID",
     "input": [
         {
             "type": "user_input",
             "content": [
                 {
                     "type": "text",
                     "text": "Analyze our database and summarize recent purchase events."
                 }
             ]
         }
     ],
     "tools": [
         {
             "type": "mcp_server",
             "url": "MCP_SERVER_URL",
             "name": "MCP_SERVER_NAME",
             "headers": {
                 "MCP_HEADER_KEY": "MCP_HEADER_VALUE"
             }
         }
     ]
  }'

Python

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

from google import genai

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

stream = client.interactions.create(
    agent="AGENT_ID",
    input="Analyze our database and summarize recent purchase events.",
    tools=[
        {
            "type": "mcp_server",
            "url": "MCP_SERVER_URL",
            "name": "MCP_SERVER_NAME",
            "headers": {
                "MCP_HEADER_KEY": "MCP_HEADER_VALUE"
            },
        }
    ],
    stream=True,
    background=True,
    store=True,
)

for event in stream:
    print(event)

JavaScript

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

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

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

const stream = await client.interactions.create({
    agent: "AGENT_ID",
    input: "Analyze our database and summarize recent purchase events.",
    tools: [
        {
            type: "mcp_server",
            url: "MCP_SERVER_URL",
            name: "MCP_SERVER_NAME",
            headers: {
                "MCP_HEADER_KEY": "MCP_HEADER_VALUE",
            },
        },
    ],
    stream: true,
    background: true,
    store: true,
});

for await (const event of stream) {
    console.log(event);
}

次のステップ

概要

Agent Platform の Managed Agents API の概要

Agent Platform の Managed Agents API について説明します。これは、自律型エージェントを構築するための構成駆動型の REST ファースト環境です。

リファレンス

Agent Platform サンドボックス環境の Managed Agents API

分離されたサンドボックスコンテナ、権限、プリインストールされたパッケージ/ツールについて学習します。

エージェントを操作する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

Check for the roles

Grant the roles

Check for the roles

Grant the roles

Antigravity エージェントを操作する

REST

リクエスト変数

HTTP メソッドと URL

リクエストの本文（JSON）

curl コマンド

レスポンスの例

Python

JavaScript

Agents API を使用して作成されたカスタム エージェントを操作する

環境の構成と初期化

カスタム エージェントにインタラクションを送信する

REST

リクエスト変数

HTTP メソッドと URL

リクエストの本文（JSON）

curl コマンド

レスポンスの例

Python

JavaScript

セッションの状態とマルチターンのインタラクションを管理する

REST

リクエスト変数

HTTP メソッドと URL

リクエストの本文（JSON）

curl コマンド

Python

JavaScript

インタラクション中に構成をオーバーライドする

REST

リクエスト変数

HTTP メソッドと URL

リクエストの本文（JSON）

curl コマンド

Python

JavaScript

次のステップ

Agent Platform の Managed Agents API の概要

Agent Platform サンドボックス環境の Managed Agents API

エージェントを操作する

`curl` コマンド

Agents API を使用して作成されたカスタムエージェントを操作する

カスタムエージェントにインタラクションを送信する

`curl` コマンド

`curl` コマンド

`curl` コマンド