Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

Interactions API デベロッパーガイド

プレビュー

この機能は、サービス固有の規約の「一般サービス規約」セクションの「一般提供前サービス規約」と、生成 AI プレビュー版プロダクトに関する追加規約の対象となります。お客様はこの機能の個人データを Cloud のデータ処理に関する追加条項に記載されているとおりに処理できます。ただし、Google Cloud へのアクセスに関する契約に記載されている義務と制限事項が適用されます。pre-GA の機能は「現状のまま」で提供されるものであり、サポートが制限されることがあります。詳細については、リリースステージの説明をご覧ください。

Interactions API は、Gemini Enterprise Agent Platform 上の Gemini モデルと自律型エージェントを使用して生成 AI アプリケーションを構築するための統合されたステートフルインターフェースを提供します。Interactions API を使用して、マルチターンの会話を実行し、リアルタイムのレスポンスをストリーミングし、構造化された出力を適用し、関数呼び出しを実行し、長時間実行されるバックグラウンドタスクをオーケストレートします。

このガイドでは、Google Gen AI SDK をインストールし、クライアントを認証して、一般的なインタラクションワークフローを実装する方法について説明します。インタラクションライフサイクルのコンセプトの詳細については、Interactions API の概要をご覧ください。

始める前に

Interactions API にリクエストを送信する前に、 Google Cloudプロジェクトと開発環境を設定します。

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.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector
Verify that billing is enabled for your Google Cloud project.
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

Make sure that you have the following role or roles on the project: Agent Platform User (roles/aiplatform.user)
Check for the roles
1. In the Google Cloud 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 Google Cloud 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.

主なコンセプト

Interactions API が状態とレスポンスを管理する方法を理解するには、次のコンセプトを確認してください。

Interaction: Interactions API は、Interaction というコアリソースを中心に構成されています。Interaction は、会話またはタスクの完全なターンを表し、モデルの思考、ツール呼び出し、最終出力の時系列を追跡します。プロンプトとレスポンスのやり取りや、複雑なマルチステップのエージェントワークフローに統一されたエンベロープを提供します。
ステートフル保持: インタラクションはデフォルトでサーバーサイドに保存されます（Python では store=True、TypeScript/JavaScript では store: true）。保存されたインタラクションは 7 日間保持され、その後自動的に削除されます。store=False を設定すると、ステートレスモードが有効になり、サーバーサイドの保持が無効になり、ゼロデータ保持（ZDR）に準拠します。ステートレスモードでは、previous_interaction_id のチェーンと非同期実行（background=True）も無効になります。
レスポンスヘルパー: Google Gen AI SDK バージョン 2.3.0 以降では、interaction.output_text、interaction.output_image、interaction.output_audio などの便利なプロパティがインタラクションレスポンスに用意されています。ステップ配列（interaction.steps[-1].content[0].text など）に手動でインデックスを付けるのではなく、interaction.output_text を使用してテキストレスポンスを読み取ります。

要件

Interactions API と統合する前に、環境とリクエストが次の要件を満たしていることを確認してください。

SDK バージョンのサポート: 統合された Google Gen AI SDK（Python の場合は >= 2.3.0、TypeScript と JavaScript の場合は @google/genai >= 2.3.0）を使用します。
- レスポンスヘルパープロパティとエージェント機能にはバージョン 2.3.0 以降が必要ですが、バージョン 2.0.0 はベースの steps スキーマをサポートしています。
- 以前の SDK（google-cloud-aiplatform、@google-cloud/vertexai、google-generativeai）は Interactions API をサポートしていません。
サポートされているモデル: サポートされている Gemini 3 モデル以降を使用します。以前のモデルファミリーでは、この API はサポートされていません。サポートされているモデルの一覧については、サポートされているモデルと最新のモデルバージョンに移行するをご覧ください。
ターンスコープパラメータ: tools、system_instruction、generation_config などの構成パラメータは、現在のターンにのみ適用されます。ワークフローでマルチターンの会話全体でこれらのパラメータが必要な場合は、後続の各インタラクションターンでこれらのパラメータを渡します。

Google Gen AI SDK をインストールする

使用する言語の Google Gen AI SDK（>= 2.3.0）をインストールまたはアップグレードします。

Python

pip install --upgrade "google-genai>=2.3.0"

TypeScript / JavaScript

npm install "@google/genai>=2.3.0"

担当するお客様の身元確認をしてください

Agent Platform の Interactions API に接続するには、次のいずれかの認証方法を使用します。

アプリケーションのデフォルト認証情報（ADC）を使用して Google Cloud プロジェクトに接続する

この認証方法は、 Google Cloudのエンタープライズワークロードと本番環境のデプロイで使用することをおすすめします。アプリケーションのデフォルト認証情報（ADC）で認証するには、次のプロパティを使用してクライアントを初期化します。

enterprise=True
project= Google Cloud project ID
location="global"

ローカル認証情報をまだ構成していない場合は、gcloud auth application-default login を実行します。

次のコードサンプルで、PROJECT_ID はGoogle Cloud プロジェクト ID に置き換えます。

Python

from google import genai

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

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain serverless computing in one sentence.",
)

print(interaction.output_text)

TypeScript / JavaScript

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

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

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Explain serverless computing in one sentence.",
});

console.log(interaction.output_text);

REST

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [{
      "role": "user",
      "content": [{
        "type": "text",
        "text": "Explain serverless computing in one sentence."
      }]
    }]
  }'

エクスプレスモード（API キー）を使用して接続する

この認証方法は、ラピッドプロトタイピング、軽量スクリプト、API キーで認証する環境で使用することをおすすめします。クライアントの初期化時または x-goog-api-key HTTP ヘッダーで API キーを渡します。

次のコードサンプルでは、API_KEY を API キーに置き換えます。

Python

from google import genai

client = genai.Client(
    enterprise=True,
    api_key="API_KEY",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain serverless computing in one sentence.",
)

print(interaction.output_text)

TypeScript / JavaScript

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

const ai = new GoogleGenAI({
    enterprise: true,
    apiKey: "API_KEY",
});

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Explain serverless computing in one sentence.",
});

console.log(interaction.output_text);

REST

curl -X POST "https://aiplatform.googleapis.com/v1beta1/locations/global/interactions" \
  -H "x-goog-api-key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [{
      "role": "user",
      "content": [{
        "type": "text",
        "text": "Explain serverless computing in one sentence."
      }]
    }]
  }'

一般的なインタラクションワークフロー

クライアントを構成したら、interactions.create メソッドを使用して、マルチターンの会話の構築、出力トークンのリアルタイムストリーミング、スキーマ検証済みの JSON の生成、外部関数の呼び出し、自律型エージェントの実行を行うことができます。

ステートフルマルチターンの会話を管理する

すべてのリクエストで完全なメッセージ履歴を再送信する必要があるステートレスチャット API とは異なり、Interactions API はデフォルトでサーバー上の会話状態を管理します（Python では store=True、TypeScript/JavaScript では store: true）。

既存の会話を続けるには、前のインタラクションの id を previous_interaction_id パラメータに渡します。Agent Platform は、保存された会話のコンテキストを自動的に取得し、新しいターンを追加します。store=False（TypeScript/JavaScript では store: false）を設定すると、サーバーサイドの永続性が無効になり、previous_interaction_id で後続のターンをチェーンできなくなります。

Python

# Turn 1: Start a conversation (store=True by default)
turn1 = client.interactions.create(
    model="gemini-3.8-flash",
    input="Hi! My name is John. I am working on AI agents.",
    store=True,
)
print(f"Turn 1: {turn1.output_text}")

# Turn 2: Reference the stored conversation state using previous_interaction_id
turn2 = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is my name?",
    previous_interaction_id=turn1.id,
)
print(f"Turn 2: {turn2.output_text}")

TypeScript / JavaScript

// Turn 1: Start a conversation (store: true by default)
const turn1 = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Hi! My name is John. I am working on AI agents.",
    store: true,
});
console.log(`Turn 1: ${turn1.output_text}`);

// Turn 2: Reference the stored conversation state using previous_interaction_id
const turn2 = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "What is my name?",
    previous_interaction_id: turn1.id,
});
console.log(`Turn 2: ${turn2.output_text}`);

回答をリアルタイムでストリーミングする

インタラクティブなアプリケーションで認識されるレイテンシを短縮するには、モデルのレスポンスを生成時にストリーミングします。interactions.create を呼び出すときに stream=True（TypeScript/JavaScript では stream: true）を設定して、サーバー送信イベントの反復可能なストリームを受信します。step.delta イベントをフィルタして、増分テキストチャンクが到着するたびにレンダリングします。

Python

response = client.interactions.create(
    model="gemini-3.8-flash",
    input="Write a short poem about debugging.",
    stream=True,
)

for event in response:
    if event.event_type == "step.delta" and hasattr(event.delta, "text"):
        print(event.delta.text, end="", flush=True)
print()

TypeScript / JavaScript

const responseStream = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Write a short poem about debugging.",
    stream: true,
});

for await (const event of responseStream) {
    if (event.event_type === "step.delta" && event.delta && "text" in event.delta) {
        process.stdout.write(event.delta.text);
    }
}
console.log();

構造化出力を生成する

アプリケーションで予測可能な機械可読形式のレスポンスが必要な場合は、特定の JSON スキーマに一致するようにモデル出力を制約できます。ターゲットスキーマ（Python の Pydantic モデル JSON スキーマや TypeScript/JavaScript の Type スキーマオブジェクトなど）を、ポリモーフィック response_format パラメータに直接渡します。

Python

from pydantic import BaseModel, Field

class Book(BaseModel):
    title: str = Field(description="The title of the book")
    author: str = Field(description="The book's author")
    year_published: int

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Recommend one famous sci-fi book.",
    response_format=Book.model_json_schema(),
)

# The output text is valid JSON matching the Book schema
print(interaction.output_text)

TypeScript / JavaScript

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

const BookSchema = {
    type: Type.OBJECT,
    properties: {
        title: { type: Type.STRING, description: "The title of the book" },
        author: { type: Type.STRING, description: "The book's author" },
        yearPublished: { type: Type.INTEGER },
    },
    required: ["title", "author", "yearPublished"],
};

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Recommend one famous sci-fi book.",
    response_format: BookSchema,
});

console.log(interaction.output_text);

関数呼び出し（ツール使用）を使用する

関数呼び出しを使用すると、モデルはカスタム関数または外部 API の実行をリクエストして、最終的なレスポンスを作成する前に情報を収集できます。ステートフルなインタラクションワークフローでは、関数呼び出しは 2 ターンのパターンに従います。

ツールを宣言して渡す: 最初のリクエストの tools パラメータで関数宣言を指定します。
実行して結果を返す: function_call ステップのレスポンスステップ（interaction.steps）を検査し、モデルから提供された arguments を使用してローカル関数を実行し、call_id と previous_interaction_id でリンクされた function_result アイテムを含むフォローアップインタラクションを送信します。

Python

# Define a declarative function tool schema
stock_tool = {
    "type": "function",
    "name": "get_stock_price",
    "description": "Gets the stock price for a given ticker symbol.",
    "parameters": {
        "type": "object",
        "properties": {
            "ticker": {"type": "string", "description": "The stock ticker symbol"}
        },
        "required": ["ticker"],
    },
}

def get_stock_price(ticker: str) -> float:
    """Executes the local tool function."""
    if ticker.upper() == "GOOG":
        return 175.50
    return 100.0

# Turn 1: Pass the tool declaration to the model
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is the stock price of GOOG?",
    tools=[stock_tool],
)

# Inspect the interaction steps for function call requests
for step in interaction.steps:
    if step.type == "function_call" and step.name == "get_stock_price":
        ticker_arg = step.arguments.get("ticker")
        price = get_stock_price(ticker_arg)

        # Turn 2: Submit the function execution result to the conversation
        final_turn = client.interactions.create(
            model="gemini-3.8-flash",
            input=[{
                "type": "function_result",
                "call_id": step.id,
                "result": {"price": price},
            }],
            previous_interaction_id=interaction.id,
        )
        print(final_turn.output_text)

TypeScript / JavaScript

// Define a declarative function tool schema
const stockTool = {
    type: "function",
    name: "getStockPrice",
    description: "Gets the stock price for a given ticker symbol.",
    parameters: {
        type: "object",
        properties: {
            ticker: { type: "string", description: "The stock ticker symbol" },
        },
        required: ["ticker"],
    },
};

function getStockPrice({ ticker }: { ticker: string }): number {
    if (ticker.toUpperCase() === "GOOG") return 175.50;
    return 100.00;
}

// Turn 1: Pass the tool declaration to the model
const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "What is the stock price of GOOG?",
    tools: [stockTool],
});

// Inspect the interaction steps for function call requests
for (const step of interaction.steps ?? []) {
    if (step.type === "function_call" && step.name === "getStockPrice") {
        const tickerArg = step.arguments.ticker as string;
        const price = getStockPrice({ ticker: tickerArg });

        // Turn 2: Submit the function execution result to the conversation
        const finalTurn = await ai.interactions.create({
            model: "gemini-3.8-flash",
            input: [{
                type: "function_result",
                call_id: step.id,
                result: { price },
            }],
            previous_interaction_id: interaction.id,
        });
        console.log(finalTurn.output_text);
    }
}

エージェントと長時間実行のバックグラウンドタスクを実行する

Interactions API では、基盤モデルに加えて、agent パラメータを使用して特殊な自律型エージェントを呼び出すことができます。

antigravity-preview-05-2026: 安全なサンドボックス化された Linux 環境でコード実行、ファイル管理、ウェブブラウジングを行う汎用マネージドエージェント。詳しくは、エージェントを操作するをご覧ください。
deep-research-preview-04-2026: Gemini Deep Research エージェント。複数ステップのウェブリサーチタスクを計画して実行し、複数のソースからの調査結果を統合して包括的なレポートを作成します。詳細については、Gemini Deep Research エージェントを使用するをご覧ください。
カスタムエージェント: client.agents.create() で構成およびプロビジョニングされたカスタムエージェントリソース。

エージェントワークフローは完了までに数分かかることが多いため、background=True を設定してバックグラウンドで非同期的に実行します。API は、interaction.status が completed に移行するまで client.interactions.get() を使用してポーリングできる id を含む Interaction オブジェクトをすぐに返します。

このサンプルを試す前に、PROJECT_ID を実際のGoogle Cloud プロジェクト ID に置き換えてください。

import time
from google import genai

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

interaction = client.interactions.create(
    input="Analyze competitive positioning for solar energy providers.",
    agent="deep-research-preview-04-2026",
    background=True,
)

print(f"Research started: {interaction.id}")

while True:
    interaction = client.interactions.get(interaction.id)
    if interaction.status == "completed":
        print(interaction.output_text)
        break
    elif interaction.status in ("failed", "cancelled"):
        print(f"Research ended with status: {interaction.status}")
        break
    time.sleep(10)

アップロードされた Cloud Storage ファイルにアクセスする

Interactions API を使用して、アップロードされた Cloud Storage ファイルにアクセスできます。次の例をご覧ください。

from google import genai

# Credentials must belong to an identity with storage.objects.get permissions
client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": "Summarize the attached document:"},
        {
            "type": "document",
            "uri": "gs://my-secure-bucket/quarterly_report.pdf",
            "mime_type": "application/pdf"
        }
    ],
)

print(interaction.output_text)

Cloud Storage URI（gs://bucket-name/path/to/file など）を Interactions API に渡すと、リクエストはエンドユーザー認証情報（EUC）を使用して評価されます。この API は、バックグラウンドプロジェクトサービスエージェントではなく、認証された呼び出し元の ID を使用して Cloud Storage オブジェクトを取得します。

インタラクションリクエストで Cloud Storage ファイルを渡すには、呼び出し元のプリンシパル（ユーザーアカウント、サービスアカウント、またはフェデレーション ID）が、参照されるすべてのオブジェクトに対する storage.objects.get 権限を持っている必要があります。

Cloud Storage ファイルにアクセスするための IAM ロールを構成する

storage.objects.get 権限を含む標準の事前定義ロールのいずれかを付与します。

Storage オブジェクト閲覧者（roles/storage.objectViewer）: オブジェクトに対する読み取りアクセス権（推奨）。
Storage オブジェクトユーザー（roles/storage.objectUser）: オブジェクトに対する読み取り / 書き込みアクセス権。

Google Cloud CLI を使用してユーザーアカウントにアクセス権を付与するには、次のコマンドを使用します。

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member="user:user-email@example.com" \
    --role="roles/storage.objectViewer"

特定の呼び出しサービスアカウントにアクセス権を付与するには、次のコマンドを使用します。

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member="serviceAccount:sa-name@PROJECT_ID." \
    --role="roles/storage.objectViewer"

Cloud Storage ファイルアクセスのトラブルシューティング

呼び出し元のプリンシパルに十分な権限がない場合、Interactions API は次のような 403 Forbidden エラーを返します。

Access error:
PERMISSION_DENIED - 403 Forbidden: Calling principal lacks
storage.objects.get on one or more GCS URIs.

この問題を解決するには、バケットまたはオブジェクトに対する Storage オブジェクト閲覧者ロール（roles/storage.objectViewer）を認証済み呼び出し元に付与します。

指定されたオブジェクトが存在しない場合、またはバケット権限によって呼び出し元がオブジェクトの存在を確認できない場合、Interactions API は次のような 404 Not Found エラーを返します。

Access error:
NOT_FOUND - 404 Not Found: The object does not exist, or bucket
permissions prevent revealing object existence.

この問題を解決するには、Cloud Storage URI が正しいことを確認し、認証された呼び出し元にバケットへの読み取りアクセス権があることを確認します。

高度な REST ワークフロー

シェルベースの自動化、CI/CD パイプライン、Python または TypeScript/JavaScript ランタイムのない環境では、curl を使用して HTTP 経由で Interactions API を直接呼び出すことができます。

REST エンドポイント

POST リクエストを次の Interactions API エンドポイントに送信します。

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

リクエストの次の変数を置き換えます。

PROJECT_ID: 実際の Google Cloud プロジェクト ID。
LOCATION: global に設定します（構成で必要な場合は、サポートされているカスタムリージョン）。

環境変数と認証を設定する

次のセクションの curl の例を実行する前に、プロジェクト ID、ターゲットモデルまたはエージェント ID、アプリケーションのデフォルト認証情報から生成された OAuth 2.0 アクセストークンをエクスポートします。

PROJECT_ID="PROJECT_ID"
MODEL_ID="gemini-3.8-flash"
AGENT_ID="deep-research-preview-04-2026"
ACCESS_TOKEN=$(gcloud auth print-access-token)

同期レスポンスの形式

同期 POST リクエストは、一意のインタラクション id、実行 status、会話 steps、トークン usage のメタデータを含む JSON interaction オブジェクトを返します。

{
  "id": "your-interaction-id",
  "status": "completed",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Serverless computing is a cloud execution model where the cloud provider dynamically manages the allocation and provisioning of servers, charging customers based on actual usage rather than pre-purchased capacity."
        }
      ]
    }
  ],
  "usage": {
    "total_tokens": 24751,
    "total_input_tokens": 23894,
    "total_output_tokens": 857
  },
  "created": "2026-05-08T10:44:43Z",
  "updated": "2026-05-08T10:44:43Z",
  "environment_id": "your-environment-id",
  "object": "interaction"
}

マルチターンのステートフルなやり取りを継続する

REST で保存された会話を続行するには、前のレスポンスの id を JSON リクエスト本文の previous_interaction_id フィールドに渡します。

このサンプルを試す前に、PREVIOUS_INTERACTION_ID を前のインタラクションで返された id に置き換えます。

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/interactions" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${MODEL_ID}"'",
    "store": true,
    "previous_interaction_id": "PREVIOUS_INTERACTION_ID",
    "input": [{
      "role": "user",
      "content": [{
        "type": "text",
        "text": "Can you elaborate on that?"
      }]
    }]
  }'

サーバー送信イベントで出力をストリーミングする

REST 経由で増分更新をストリーミングするには、JSON リクエストの本文に "stream": true を含めます。

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/interactions" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${MODEL_ID}"'",
    "stream": true,
    "input": [{
      "role": "user",
      "content": [{
        "type": "text",
        "text": "Write a long story about space travel."
      }]
    }]
  }'

"stream": true が設定されている場合、サーバーは Transfer-Encoding: chunked と Content-Type: text/event-stream（Server-Sent Events）で応答します。ストリーム内の各イベントには、event_type とステップの差分コンテンツを含む JSON ペイロードを含む data: 接頭辞が含まれます。curl は、インタラクションが完了するまで HTTP 接続を自動的に開いたままにし、受信したチャンクを stdout にリアルタイムで書き込みます。

マネージドエージェントをバックグラウンドで実行する

REST 経由で長時間実行されるマネージドエージェントタスクを非同期で開始するには、ターゲット agent を指定し、"background": true を設定して、"environment": "remote" を構成します。

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/interactions" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "'"${AGENT_ID}"'",
    "environment": "remote",
    "background": true,
    "input": [{
      "role": "user",
      "content": [{
        "type": "text",
        "text": "Analyze competitive positioning for commercial solar energy providers."
      }]
    }]
  }'

次のステップ

主なコンセプトについて詳しくは、Interactions API の概要をご覧ください。
Interactions API リファレンスでリクエストとレスポンスのスキーマを確認する。
マネージドエージェントを操作する方法と、Gemini Deep Research エージェントを使用する方法を学習します。

Interactions API デベロッパー ガイド コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

Check for the roles

Grant the roles

主なコンセプト

要件

Google Gen AI SDK をインストールする

Python

TypeScript / JavaScript

担当するお客様の身元確認をしてください

アプリケーションのデフォルト認証情報（ADC）を使用して Google Cloud プロジェクトに接続する

Python

TypeScript / JavaScript

REST

エクスプレス モード（API キー）を使用して接続する

Python

TypeScript / JavaScript

REST

一般的なインタラクション ワークフロー

ステートフル マルチターンの会話を管理する

Python

TypeScript / JavaScript

回答をリアルタイムでストリーミングする

Python

TypeScript / JavaScript

構造化出力を生成する

Python

TypeScript / JavaScript

関数呼び出し（ツール使用）を使用する

Python

TypeScript / JavaScript

エージェントと長時間実行のバックグラウンド タスクを実行する

アップロードされた Cloud Storage ファイルにアクセスする

Cloud Storage ファイルにアクセスするための IAM ロールを構成する

Cloud Storage ファイル アクセスのトラブルシューティング

高度な REST ワークフロー

REST エンドポイント

環境変数と認証を設定する

同期レスポンスの形式

マルチターンのステートフルなやり取りを継続する

サーバー送信イベントで出力をストリーミングする

マネージド エージェントをバックグラウンドで実行する

次のステップ

Interactions API デベロッパーガイド

エクスプレスモード（API キー）を使用して接続する

一般的なインタラクションワークフロー

ステートフルマルチターンの会話を管理する

エージェントと長時間実行のバックグラウンドタスクを実行する

Cloud Storage ファイルアクセスのトラブルシューティング

マネージドエージェントをバックグラウンドで実行する