注: このドキュメントセットは、Gemini Enterprise の Standard、Plus、従量課金、Frontline エディションを対象としています。Business エディションのドキュメントについては、Gemini Enterprise - Business エディションのヘルプセンターをご覧ください。

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

StreamAssist API を使用して特定のエージェントを呼び出す

特定の登録済みエージェントを呼び出すには、streamAssist REST API リクエストまたはクライアントライブラリ呼び出しで、オプションの agentsSpec フィールドを指定します。AgentsSpec API は、リクエストの処理に使用されるエージェントの仕様を定義します。アシスタントはクエリをそのエージェントに直接転送し、ターン間でセッションコンテキストを保持します。

概要

仕様	詳細
API メソッド	`projects.locations.collections.engines.assistants.streamAssist`
エンドポイントのバージョン	エージェント ID を検出するための `v1alpha`、`streamAssist` を呼び出すための `v1`
主なパラメータ	`agentsSpec.agentSpecs[].agentId`
サポートされているエージェントタイプ	Core Assistant、Deep Research、Workflow Builder チャットエージェント（以前のローコード）、Workflow Builder ワークフロー（ワークフローを呼び出すを参照）
必要な IAM 権限	`discoveryengine.assistants.assist`
必要な OAuth スコープ	`https://www.googleapis.com/auth/cloud-platform`

始める前に

Google Cloud プロジェクトで Discovery Engine API（discoveryengine.googleapis.com）を有効にします。
プリンシパル（ユーザーアカウントまたはサービスアカウント）に、discoveryengine.assistants.assist IAM 権限を付与するロール（Discovery Engine 編集者（roles/discoveryengine.editor）や Gemini Enterprise 管理者（roles/discoveryengine.agentspaceAdmin）など）があることを確認します。
Gemini Enterprise app（エンジン）が作成され、少なくとも 1 つの登録済みエージェントが含まれていることを確認します。
アプリケーションのデフォルト認証情報（ADC）を使用して認証する場合は、クライアントが割り当てプロジェクトヘッダー -H "X-Goog-User-Project: PROJECT_ID" を送信していることを確認してください。

アプリ ID と場所を確認する

streamAssist URL には、エンジン ID とそのロケーション（global、us、eu）が必要です。アプリの表示名しかわからない場合は、プロジェクト内のエンジンを一覧表示して、基盤となる ID を見つけます。

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines"

レスポンスでは、エンジン name の形式は projects/{project}/locations/{location}/collections/default_collection/engines/{ENGINE_ID} です。ENGINE_ID セグメントは、呼び出しで必要な APP_ID です。

エージェント ID を確認する

agentId は、Discovery Engine API のエージェントの完全なリソース名の最後のセグメントです。

projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/assistants/{assistant}/agents/{AGENT_ID}

登録済みエージェントは、わかりやすい表示名ではなく、長い数値 ID（15492003793394502655 など）を使用します。リクエストでは、この最終的な {AGENT_ID} 数値文字列のみを指定してください。

アプリに登録されているエージェントを一覧表示し、その数値 ID を確認するには、v1alpha エンドポイントで agents コレクションを呼び出します。

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents"

返される各エージェントリソースには、次のフィールドが含まれます。

name: {AGENT_ID} で終わる完全なリソースパス。
displayName: Google Cloud コンソールに表示される、人が読める形式の名前。
state: 動作状態（ENABLED、PRIVATE など）。
エージェントタイプ（a2aAgentDefinition、lowCodeAgentDefinition、workflowAgentDefinition など）を示す定義オブジェクト。

完全なエージェントリソーススキーマについては、agents REST API リファレンスをご覧ください。

エージェントにクエリを送信する

特定のエージェントにクエリを送信するには、適切な agentsSpec を使用してリクエストを作成し、REST またはクライアントライブラリを使用して実行する必要があります。

リクエスト本文の構造

クエリを特定のエージェントにルーティングするには、POST リクエスト本文にオプションの agentsSpec オブジェクトを含めます。

{
  "query": {
    "text": "QUERY_TEXT"
  },
  "session": "SESSION_RESOURCE_NAME",
  "agentsSpec": {
    "agentSpecs": [
      {
        "agentId": "AGENT_ID"
      }
    ]
  }
}

フィールドリファレンス

agentsSpec （オブジェクト、省略可）: リクエストの処理に使用されるエージェントの仕様。
agentsSpec.agentSpecs[] （配列、省略可）: エージェント仕様のリスト。この配列には複数のエージェントを指定できます。
agentsSpec.agentSpecs[].agentId （文字列、仕様内で必須）: 登録済みエージェントリソースを識別する ID。RFC-1034 に準拠している必要があり、最大長は 63 文字です。

完全なリクエストスキーマについては、streamAssist REST API リファレンスをご覧ください。

streamAssist を呼び出す

REST

次の curl コマンドは、REST API を使用して特定のエージェントにクエリを送信します。

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant:streamAssist" \
  -d '{
    "query": {
      "text": "List all contact cards."
    },
    "agentsSpec": {
      "agentSpecs": [
        {
          "agentId": "AGENT_ID"
        }
      ]
    }
  }'

各プレースホルダを次のように置き換えます。

LOCATION: ホスト名とリソースパスの両方のマルチリージョン（global、us、eu）。アプリが global ロケーションにある場合は、ホスト名（discoveryengine.googleapis.com）からロケーション接頭辞を省略します。
PROJECT_ID: Google Cloud プロジェクト ID。
APP_ID: Gemini Enterprise エンジン ID（アプリ ID とロケーションを確認するで確認）。
AGENT_ID: 数値のエージェント ID（エージェント ID を確認するで確認）。

Python

この Python の例では、google-cloud-discoveryengine クライアントライブラリを使用して streamAssist を呼び出します。

# Install library: pip install google-cloud-discoveryengine
from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Replace placeholder values with your project and agent details.
project_id = "PROJECT_ID"
location = "LOCATION"          # For example: "us", "eu", or "global"
engine_id = "APP_ID"
agent_id = "AGENT_ID"          # The numeric agent ID
query_text = "List all contact cards."

client_options = (
    ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
    if location != "global"
    else None
)
client = discoveryengine.AssistantServiceClient(client_options=client_options)

assistant_path = client.assistant_path(
    project=project_id,
    location=location,
    collection="default_collection",
    engine=engine_id,
    assistant="default_assistant",
)

request = discoveryengine.StreamAssistRequest(
    name=assistant_path,
    query=discoveryengine.Query(text=query_text),
    agents_spec=discoveryengine.StreamAssistRequest.AgentsSpec(
        agent_specs=[
            discoveryengine.StreamAssistRequest.AgentsSpec.AgentSpec(
                agent_id=agent_id,
            )
        ]
    ),
)

for response in client.stream_assist(request=request):
    for reply in response.answer.replies:
        # Filter out model reasoning fragments (thought: true)
        if hasattr(reply, "grounded_content") and reply.grounded_content.content:
            print(reply.grounded_content.content.text, end="", flush=True)

print()

ストリーミングレスポンスについて

streamAssist エンドポイントは、REST 経由で JSON チャンクのストリームを返すか、クライアントライブラリでレスポンスオブジェクトのイテレータを返します。

回答テキスト: 増分レスポンステキストが answer.replies[].groundedContent.content.text に届きます。これらのテキストフラグメントを受信順に連結して、完全な回答を再構成します。
推論フラグメント: "thought": true でマークされたフラグメントは、モデルの内部推論プロセスを表します。エンドユーザーに最終的な出力を提示する際は、これらのフラグメントを除外します。
実行状態: answer.state フィールドは IN_PROGRESS からターミナル状態に移行します。
- SUCCEEDED: リクエストが完了し、回答が生成されました。
- SKIPPED: クエリが無視またはバイパスされました。詳細（簡単な挨拶の NON_ASSIST_SEEKING_QUERY_IGNORED など）については、assistSkippedReasons をご覧ください。
- FAILED: 呼び出しで実行エラーが発生しました。
セッションの継続性: ターミナルチャンクには、sessionInfo.session（セッションリソース名）と assistToken が含まれます。

同じセッションで会話を続ける

ターン間でコンテキストを維持するには、後続のリクエストで sessionInfo から session 文字列を渡します。

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant:streamAssist" \
  -d '{
    "session": "projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/sessions/SESSION_ID",
    "query": {
      "text": "Who is John Doe?"
    },
    "agentsSpec": {
      "agentSpecs": [
        {
          "agentId": "AGENT_ID"
        }
      ]
    }
  }'

session フィールドを省略するか、セッション ID として - を指定すると、API は新しい分離されたセッションを自動的に生成します。

ワークフローを呼び出す

Workflow Builder ワークフローを実行するには、agentsSpec.agentSpecs[].agentId にワークフローの ID を指定して同じリクエストを送信します。各呼び出しにより、ワークフローの手動実行が開始されます。

実行されるバージョン: ワークフローが公開されている場合、呼び出しは公開されたバージョンを実行します。Workflow Builder で保存された変更は、公開されるまで API 呼び出し元に影響しません。ワークフローが公開されていない場合、呼び出しはドラフトを実行します。
呼び出し可能なユーザー: ワークフローのオーナーと管理者が呼び出すことができます。公開されたワークフローは、他のユーザーと共有された後に呼び出すことができます。公開されたことがないワークフローを呼び出すことができるのは、オーナーまたは管理者のみです。他の呼び出し元は HTTP 403 を受け取ります。
トリガー: ワークフローには手動トリガーが 1 つだけ必要です。手動トリガーを他のトリガーと組み合わせたワークフロー、または複数の手動トリガーがあるワークフローでは、呼び出しが失敗します。
入力: streamAssist を使用して手動トリガーの入力変数を設定することはできません。手動トリガーに必須の入力がある場合、入力にデフォルト値があっても実行は失敗します。省略可能な入力が空で、デフォルト値が適用されていません。クエリテキストはワークフローの LLM ノードに渡されるため、そこにデータを含めることはできますが、入力変数は入力されません。

制限事項

streamAssist でエージェントを呼び出す場合は、次の制限事項が適用されます。

サポートされていないエージェントタイプ: Gemini Enterprise アプリに登録されている A2A エージェントまたは ADK エージェントは、streamAssist ではサポートされていません。レジストリエンドポイントを使用して A2A エージェントを直接呼び出すには、レジストリ A2A エンドポイントを使用してエージェントを呼び出すをご覧ください。
変更アクション: streamAssist API は、コネクタを介した会話型クエリと読み取り専用の取得用に最適化されています。streamAssist では、変更を伴うツールやアクション（メールの下書き、カレンダーの予定の作成、チャットメッセージなど）のプログラムによる実行はサポートされていません。変更を伴うアクションを実行する Agentic Workflows を呼び出そうとすると、サイレントエラーや根拠のない実行ループが発生する可能性があります。

トラブルシューティング

次の表を使用して、一般的な streamAssist 呼び出しエラーのトラブルシューティングを行います。

症状	考えられる原因	解決策
エージェントの一覧表示時に HTTP 404 が返される	`v1` または `v1beta` エンドポイントで `agents` を呼び出す。	代わりに、リストリクエストを `v1alpha` エンドポイントに送信します。
`agentsSpec` を設定したにもかかわらず、回答が一般的であるように見える	数値 `agentId` が無効であるか、クエリが一般的すぎてドメインの動作をトリガーできません。	`v1alpha` エージェントリストから正確な数値 ID を確認し、ドメイン固有のクエリを送信して、エージェント固有の文言がレスポンステキストに含まれていることを確認します。
エラーは返されないが、ターゲットエージェントが実行されなかった	`agentId` の形式が正しくないため、デフォルトのオーケストレーションにサイレントフォールバックされました。	`agentId` が数字のみで構成され、レジストリリストの ID と完全に一致していることを確認します。
レスポンスの状態が `SKIPPED` を返す	アシストを求めるクエリではないと評価された入力（簡単な挨拶など）。	実質的なタスククエリを送信し、レスポンスペイロードの `assistSkippedReasons` を調べます。
`HTTP 401` または `HTTP 403 Permission Denied`	OAuth スコープがない、IAM ロールが不十分、または割り当てプロジェクトヘッダーがない。	呼び出し元に `discoveryengine.assistants.assist` があることを確認します。OAuth スコープに `cloud-platform` が含まれていることを確認します。ADC を使用している場合は `-H "X-Goog-User-Project: PROJECT_ID"` を追加します。
`Only the agent owner or an admin can run a draft of this agent.`の`HTTP 403`	ワークフローが公開されておらず、呼び出し元がそのオーナーまたは管理者ではない。	Workflow Builder でワークフローを公開し、呼び出し元と共有します。
`User does not have permission to access the Agent.`の`HTTP 403`	このワークフローは発信者と共有されません。	発信者とワークフローを共有します。
ワークフローが古いバージョンのように動作する	この呼び出しでは、Workflow Builder で公開されていない変更ではなく、公開済みのバージョンが実行されます。	ワークフローを公開します。
ワークフロー呼び出しが `answer.state` `FAILED` と `INTERNAL` エラーで終了する	ワークフローに手動トリガーと別のトリガーがあるか、複数の手動トリガーがあります。	手動トリガーを 1 つだけ保持します。