注: このドキュメントセットは、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、および Agent Designer チャットエージェント（以前はローコード）
必要な 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 など）。

完全なエージェントリソーススキーマについては、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: クエリは無視またはバイパスされました。詳細については、assistSkippedReasons を確認してください（簡単な挨拶の場合は NON_ASSIST_SEEKING_QUERY_IGNORED など）。
- 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 は新しい独立したセッションを自動的に生成します。

制限事項

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

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

トラブルシューティング

次の表を使用して、一般的な 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"` を追加します。