Bestimmten Agent mit der StreamAssist API aufrufen

Wenn Sie einen bestimmten registrierten KI-Agenten aufrufen möchten, geben Sie das optionale Feld agentsSpec in Ihrer REST API-Anfrage oder Ihrem Clientbibliotheksaufruf streamAssist an. Die AgentsSpec API definiert die Spezifikation der Agenten, die zur Verarbeitung der Anfrage verwendet werden. Der Assistent leitet Anfragen direkt an diesen Agenten weiter und behält den Sitzungskontext über mehrere Interaktionen hinweg bei.

Auf einen Blick

Spezifikation Details
API-Methode projects.locations.collections.engines.assistants.streamAssist
Endpunktversionen v1alpha zum Ermitteln von Agenten-IDs; v1 zum Aufrufen von streamAssist
Schlüsselparameter agentsSpec.agentSpecs[].agentId
Unterstützte Agententypen Core Assistant, Deep Research, Workflow Builder-Chat-Agenten (früher Low-Code) und Workflow Builder-Workflows (siehe Workflow aufrufen)
Erforderliche IAM-Berechtigung discoveryengine.assistants.assist
Erforderlicher OAuth-Bereich https://www.googleapis.com/auth/cloud-platform

Hinweis

  1. Aktivieren Sie die Discovery Engine API (discoveryengine.googleapis.com) in Ihrem Google Cloud -Projekt.
  2. Ihr Hauptkonto (Nutzerkonto oder Dienstkonto) muss eine Rolle mit der IAM-Berechtigung discoveryengine.assistants.assist haben, z. B. Discovery Engine Editor (roles/discoveryengine.editor) oder Gemini Enterprise Admin (roles/discoveryengine.agentspaceAdmin).
  3. Prüfen Sie, ob Ihre Gemini Enterprise-App (Engine) erstellt wurde und mindestens einen registrierten Agenten enthält.
  4. Wenn Sie sich mit Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) authentifizieren, muss Ihr Client den Kontingentprojekt-Header -H "X-Goog-User-Project: PROJECT_ID" senden.

App-ID und Speicherort ermitteln

Für die streamAssist-URL sind die Engine-ID und der Standort (global, us oder eu) erforderlich. Wenn Sie nur den Anzeigenamen der App kennen, listen Sie die Engines in Ihrem Projekt auf, um die zugrunde liegende ID zu finden:

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"

In der Antwort hat das Engine-Format name den Wert projects/{project}/locations/{location}/collections/default_collection/engines/{ENGINE_ID}. Das Segment ENGINE_ID ist der APP_ID, der im Aufruf erforderlich ist.

Agenten-ID finden

agentId ist das letzte Segment des vollständigen Ressourcennamens des KI-Agenten in der Discovery Engine API:

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

Registrierte Agenten verwenden eine lange numerische ID (z. B. 15492003793394502655) anstelle eines Anzeigenamens. Gib in deiner Anfrage nur diesen endgültigen {AGENT_ID}-numerischen String an.

Wenn Sie die in Ihrer Anwendung registrierten Agenten auflisten und ihre numerischen IDs ermitteln möchten, rufen Sie die Sammlung agents am Endpunkt v1alpha auf:

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"

Jede zurückgegebene Agentenressource enthält die folgenden Felder:

  • name: Der vollständige Ressourcenpfad, der auf {AGENT_ID} endet.
  • displayName: Der menschenlesbare Name, der in der Google Cloud Console angezeigt wird.
  • state: Der Betriebszustand (z. B. ENABLED oder PRIVATE).
  • Ein Definitionsobjekt, das den Agententyp angibt (z. B. a2aAgentDefinition, lowCodeAgentDefinition oder workflowAgentDefinition).

Das vollständige Schema der Agentenressource finden Sie in der agents REST API-Referenz.

Anfragen an KI-Agenten senden

Wenn Sie Abfragen an einen bestimmten Agenten senden möchten, müssen Sie Ihre Anfrage mit dem entsprechenden agentsSpec erstellen und mit REST oder Clientbibliotheken ausführen.

Struktur des Anfragetexts

Wenn Sie eine Anfrage an einen bestimmten KI-Agenten weiterleiten möchten, fügen Sie das optionale agentsSpec-Objekt in den Text Ihrer POST-Anfrage ein:

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

Feldverweis

  • agentsSpec (Objekt, optional): Spezifikation der Agenten, die zur Verarbeitung der Anfrage verwendet werden.
  • agentsSpec.agentSpecs[] (Array, optional): Eine Liste von Agentenspezifikationen. Sie können in diesem Array mehrere Agenten angeben.
  • agentsSpec.agentSpecs[].agentId (String, in der Spezifikation erforderlich): Die ID, die die registrierte Agent-Ressource identifiziert. Muss RFC-1034 entsprechen und darf maximal 63 Zeichen lang sein.

Das vollständige Anfrageschema finden Sie in der REST API-Referenz für streamAssist.

streamAssist aufrufen

REST

Mit dem folgenden curl-Befehl wird eine Anfrage an einen bestimmten Agenten über die REST API gesendet:

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"
        }
      ]
    }
  }'

Ersetzen Sie die folgenden Platzhalter:

  • LOCATION: Die Multiregion für den Hostnamen und den Ressourcenpfad (global, us oder eu). Wenn sich Ihre Anwendung am Standort global befindet, lassen Sie das Standortpräfix im Hostnamen (discoveryengine.googleapis.com) weg.
  • PROJECT_ID: Ihre Projekt-ID in Google Cloud .
  • APP_ID: Ihre Gemini Enterprise-Engine-ID (siehe App-ID und Standort ermitteln).
  • AGENT_ID: Die numerische Agent-ID (wie unter Agent-ID ermitteln beschrieben).

Python

In diesem Python-Beispiel wird streamAssist mit der google-cloud-discoveryengine-Clientbibliothek aufgerufen:

# 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()

Streamingantwort verstehen

Der Endpunkt streamAssist gibt einen Stream von JSON-Blöcken über REST oder einen Iterator von Antwortobjekten in Clientbibliotheken zurück:

  • Antworttext: Der inkrementelle Antworttext wird in answer.replies[].groundedContent.content.text angezeigt. Verketten Sie diese Textfragmente in der Reihenfolge ihres Eingangs, um die vollständige Antwort zu rekonstruieren.
  • Reasoning-Fragmente: Mit "thought": true gekennzeichnete Fragmente stellen den internen Prozess der Problemlösung des Modells dar. Filtern Sie diese Fragmente heraus, wenn Sie die endgültige Ausgabe für Endnutzer präsentieren.
  • Ausführungsstatus: Das Feld answer.state wechselt von IN_PROGRESS zu einem Terminalstatus:
    • SUCCEEDED: Die Anfrage wurde abgeschlossen und eine Antwort wurde generiert.
    • SKIPPED: Die Abfrage wurde ignoriert oder umgangen. Prüfen Sie assistSkippedReasons auf Details (z. B. NON_ASSIST_SEEKING_QUERY_IGNORED für kurze Begrüßungen).
    • FAILED: Beim Aufruf ist ein Ausführungsfehler aufgetreten.
  • Sitzungskontinuität: Der letzte Chunk enthält sessionInfo.session (den Namen der Sitzungsressource) und ein assistToken.

Unterhaltung in derselben Sitzung fortsetzen

Wenn Sie den Kontext über mehrere Runden hinweg beibehalten möchten, übergeben Sie den session-String aus sessionInfo in nachfolgenden Anfragen:

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"
        }
      ]
    }
  }'

Wenn Sie das Feld session weglassen oder - als Sitzungs-ID angeben, generiert die API automatisch eine neue, isolierte Sitzung.

Workflow aufrufen

Wenn Sie einen Workflow Builder-Workflow ausführen möchten, senden Sie dieselbe Anfrage mit der ID des Workflows in agentsSpec.agentSpecs[].agentId. Mit jedem Aufruf wird eine manuelle Ausführung des Workflows gestartet.

  • Ausgeführte Version: Wenn der Workflow veröffentlicht ist, wird die veröffentlichte Version ausgeführt. Änderungen, die im Workflow Builder gespeichert, aber noch nicht veröffentlicht wurden, wirken sich erst auf API-Aufrufer aus, wenn Sie sie veröffentlichen. Wenn der Workflow noch nie veröffentlicht wurde, wird der Entwurf ausgeführt.
  • Wer kann ihn aufrufen? Der Inhaber und die Administratoren des Workflows können ihn aufrufen. Andere Nutzer können einen veröffentlichten Workflow aufrufen, nachdem er für sie freigegeben wurde. Nur der Inhaber oder ein Administrator kann einen Workflow aufrufen, der noch nie veröffentlicht wurde. Andere Aufrufer erhalten HTTP 403.
  • Trigger: Der Workflow muss genau einen manuellen Trigger haben. Aufrufe schlagen für einen Workflow fehl, der einen manuellen Trigger mit einem anderen Trigger kombiniert oder mehr als einen manuellen Trigger hat.
  • Eingaben: Sie können die Eingabevariablen des manuellen Triggers nicht über streamAssist festlegen. Wenn für den manuellen Trigger eine Eingabe erforderlich ist, schlägt die Ausführung fehl, auch wenn die Eingabe einen Standardwert hat. Optionale Eingaben sind leer und ihre Standardwerte werden nicht angewendet. Der Abfragetext wird an die LLM-Knoten des Workflows übergeben. Sie können dort also Daten einfügen, aber es werden keine Eingabevariablen ausgefüllt.

Beschränkungen

Beim Aufrufen von KI-Agenten mit streamAssist gelten die folgenden Einschränkungen:

  • Nicht unterstützte Agententypen: A2A- oder ADK-Agenten, die in einer Gemini Enterprise-App registriert sind, werden von streamAssist nicht unterstützt. Informationen zum direkten Aufrufen eines A2A-Agenten über seinen Registry-Endpunkt finden Sie unter Agenten über seinen Registry-A2A-Endpunkt aufrufen.
  • Mutative Aktionen: Die streamAssist API ist für konversationelle Abfragen und den Lesezugriff über Connectors optimiert. Die programmatische Ausführung von mutativen Tools und Aktionen (z. B. das Erstellen von E‑Mail-Entwürfen, Kalenderterminen oder Chatnachrichten) wird über streamAssist nicht unterstützt. Der Versuch, einen Agenten-Workflow aufzurufen, der mutative Aktionen ausführt, kann zu unbemerkten Fehlern oder unbegründeten Ausführungsschleifen führen.

Fehlerbehebung

In der folgenden Tabelle finden Sie Informationen zur Fehlerbehebung bei häufigen streamAssist-Aufruffehlern:

Symptom Wahrscheinliche Ursache Lösung
HTTP 404 beim Auflisten von Agenten Aufrufen von agents am Endpunkt v1 oder v1beta. Senden Sie die Listenanfrage stattdessen an den Endpunkt v1alpha.
Antwort erscheint trotz Einstellung von agentsSpec allgemein Ungültiger numerischer Wert agentId oder die Abfrage ist zu allgemein, um ein Domainverhalten auszulösen. Bestätigen Sie die genaue numerische ID aus der v1alpha-Agentenliste, senden Sie eine domainspezifische Abfrage und prüfen Sie den Antworttext auf agentenspezifische Formulierungen.
Kein Fehler zurückgegeben, aber der Ziel-Agent wurde nicht ausgeführt Ein fehlerhaftes agentId hat zu einem stillen Fallback auf die Standardorchestrierung geführt. Prüfen Sie, ob die agentId nur aus Ziffern besteht und genau mit einer ID aus der Registry-Liste übereinstimmt.
Antwortstatus gibt SKIPPED zurück Eingabe, die als Anfrage ohne Hilfegesuch bewertet wird (z. B. eine kurze Begrüßung). Senden Sie eine Anfrage für eine inhaltliche Aufgabe und prüfen Sie assistSkippedReasons in der Antwortnutzlast.
HTTP 401 oder HTTP 403 Permission Denied Fehlender OAuth-Bereich, unzureichende IAM-Rolle oder fehlender Header für das Kontingentprojekt. Prüfen Sie, ob der Aufrufer discoveryengine.assistants.assist hat. Achten Sie darauf, dass der OAuth-Bereich cloud-platform enthält. Fügen Sie -H "X-Goog-User-Project: PROJECT_ID" hinzu, wenn Sie Standardanmeldedaten für Anwendungen verwenden.
HTTP 403 mit Only the agent owner or an admin can run a draft of this agent. Der Workflow wurde noch nie veröffentlicht und der Aufrufer ist weder der Inhaber noch ein Administrator. Veröffentlichen Sie den Workflow in Workflow Builder und geben Sie ihn für den Anrufer frei.
HTTP 403 mit User does not have permission to access the Agent. Der Workflow wird nicht für den Aufrufer freigegeben. Teilen Sie den Workflow mit dem Anrufer.
Workflow verhält sich wie eine ältere Version Beim Aufruf wird die veröffentlichte Version ausgeführt, nicht die unveröffentlichten Änderungen im Workflow Builder. Veröffentlichen Sie den Workflow.
Der Workflowaufruf endet mit answer.state FAILED und einem INTERNAL-Fehler Der Workflow hat einen manuellen Trigger und einen weiteren Trigger oder mehr als einen manuellen Trigger. Behalten Sie einen einzelnen manuellen Trigger bei.

Nächste Schritte