注: このドキュメントセットは、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 つ保持します。