Bestimmten Agent mit der StreamAssist API aufrufen

Wenn Sie einen bestimmten registrierten Agenten aufrufen möchten, geben Sie das optionale Feld agentsSpec in Ihrer streamAssist-REST API-Anfrage oder Ihrem Clientbibliotheksaufruf an. Die AgentsSpec API definiert die Spezifikation der Agenten, die zur Verarbeitung der Anfrage verwendet werden. Der Assistent leitet Abfragen direkt an diesen Agenten weiter und behält den Sitzungskontext über mehrere Züge 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
Hauptparameter	agentsSpec.agentSpecs[].agentId
Unterstützte Agententypen	Core Assistant, Deep Research, Workflow Builder-Chat-Agenten (ehemals 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. Achten Sie darauf, dass Ihr Hauptkonto (Nutzerkonto oder Dienstkonto) eine Rolle mit der IAM-Berechtigung discoveryengine.assistants.assist hat, z. B. Discovery Engine-Bearbeiter (roles/discoveryengine.editor) oder Gemini Enterprise-Administrator (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 Header für das Kontingentprojekt senden: -H "X-Goog-User-Project: PROJECT_ID".

App-ID und Standort ermitteln

Für die streamAssist-URL sind Ihre 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 Format des Engine-name die Form projects/{project}/locations/{location}/collections/default_collection/engines/{ENGINE_ID}. Das Segment ENGINE_ID ist die APP_ID, die im Aufruf erforderlich ist.

Hinweis: An den Anzeigenamen der Engine-ID wird in der Regel ein numerisches Suffix angehängt, z. B. (my-app_1234567890).

Agenten-ID ermitteln

Die agentId ist das letzte Segment des vollständigen Ressourcennamens des 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. Geben Sie in Ihrer Anfrage nur diese numerische Zeichenfolge {AGENT_ID} an.

Wenn Sie die für Ihre App 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"

Wichtig: Die Sammlung agents wird ausschließlich am Endpunkt v1alpha bereitgestellt. Wenn Sie diesen Listenendpunkt unter v1 oder v1beta aufrufen, wird ein HTTP-Fehler 404 Not Found zurückgegeben. Der Aufruf von streamAssist selbst erfolgt jedoch unter v1.

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

• name: Der vollständige Ressourcenpfad, der mit {AGENT_ID} endet.
• displayName: Der menschenlesbare Name, der in der Google Cloud Console angezeigt wird.
• state: Der Betriebsstatus (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.

Abfragen an Agenten senden

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

Hinweis: Wenn ein Agent auf interne Connectors oder Datenspeicher angewiesen ist (z. B. Document Q&A-Agenten), wird beim Aufrufen ohne konfigurierte Datenquellen eine Antwort mit dem Hinweis zurückgegeben, dass keine Datenquellen konfiguriert sind, anstatt eines API-Fehlers.

Struktur des Anfragetexts

Wenn Sie eine Abfrage an einen bestimmten Agenten weiterleiten möchten, fügen Sie das optionale Objekt agentsSpec in den Anfragetext 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 Agentenressource identifiziert. Muss RFC-1034 entsprechen und darf maximal 63 Zeichen lang sein.

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

streamAssist aufrufen

REST

Mit dem folgenden curl-Befehl wird eine Abfrage über die REST API an einen bestimmten Agenten 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 App am Standort global befindet, lassen Sie das Standortpräfix aus dem Hostnamen weg (discoveryengine.googleapis.com).
• PROJECT_ID: Projekt-ID von Google Cloud .
• APP_ID: Ihre Gemini Enterprise-Engine-ID (siehe App-ID und Standort ermitteln).
• AGENT_ID: Die numerische Agenten-ID (siehe Agenten-ID ermitteln).

Python

In diesem Python-Beispiel wird streamAssist mit der Clientbibliothek google-cloud-discoveryengine 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()
    

Streaming-Antwort verstehen

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

• Antworttext: Der inkrementelle Antworttext wird in answer.replies[].groundedContent.content.text zurückgegeben. Verketten Sie diese Textfragmente in der Reihenfolge des Empfangs, um die vollständige Antwort zu rekonstruieren.
• Begründungsfragmente: Fragmente, die mit "thought": true gekennzeichnet sind, stellen den internen Begründungsprozess des Modells dar. Filtern Sie diese Fragmente heraus, wenn Sie Endnutzern die endgültige Ausgabe präsentieren.
• Ausführungsstatus: Das answer.state Feld wechselt von IN_PROGRESS zu einem Endstatus:
  • SUCCEEDED: Die Anfrage wurde abgeschlossen und eine Antwort wurde generiert.
  • SKIPPED: Die Abfrage wurde ignoriert oder umgangen. Weitere Informationen finden Sie unter assistSkippedReasons (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 Ressourcennamen der Sitzung) und ein assistToken.

Unterhaltung in derselben Sitzung fortsetzen

Wenn Sie den Kontext über mehrere Züge hinweg beibehalten möchten, übergeben Sie die 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 im Workflow Builder ausführen möchten, senden Sie dieselbe Anfrage mit der ID des Workflows in agentsSpec.agentSpecs[].agentId. Bei jedem Aufruf wird eine manuelle Ausführung des Workflows gestartet.

• Ausgeführte Version: Wenn der Workflow veröffentlicht ist, wird bei dem Aufruf 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 bei dem Aufruf 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 fehl, wenn ein Workflow 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 der manuelle Trigger eine erforderliche Eingabe hat, 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 Eingabevariablen werden nicht ausgefüllt.

Beschränkungen

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

• Nicht unterstützte Agententypen: A2A- oder ADK-Agenten, die für eine Gemini Enterprise-App registriert sind, werden über streamAssist nicht unterstützt. Informationen zum direkten Aufrufen eines A2A-Agenten über den Registrierungsendpunkt finden Sie unter Agenten über den Registrierungs-A2A-Endpunkt aufrufen.
• Mutative Aktionen: Die streamAssist API ist für Unterhaltungsabfragen und Lesezugriff über Connectors optimiert. Die programmatische Ausführung mutativer Tools und Aktionen (z. B. E‑Mail-Entwürfe, Erstellung von Kalenderterminen oder Chatnachrichten) wird über streamAssist nicht unterstützt. Wenn Sie versuchen, einen Agenten-Workflow aufzurufen, der mutative Aktionen ausführt, kann dies zu stillen Fehlern oder nicht begrü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	agents wird am Endpunkt v1 oder v1beta aufgerufen.	Senden Sie die Listenanfrage stattdessen an den Endpunkt v1alpha.
Antwort sieht trotz Festlegung von agentsSpec allgemein aus	Ungültige numerische agentId oder die Abfrage ist zu allgemein, um das Domainverhalten auszulösen.	Prüfen Sie die genaue numerische ID in der Agentenliste v1alpha. Senden Sie eine domainspezifische Abfrage. Prüfen Sie den Antworttext auf agentspezifische Formulierungen.
Kein Fehler zurückgegeben, aber Zielagent wurde nicht ausgeführt	Eine fehlerhafte agentId hat zu einem stillen Fallback zur Standardorchestrierung geführt.	Prüfen Sie, ob die agentId nur aus Ziffern besteht und genau mit einer ID aus der Registrierungsliste übereinstimmt.
Antwortstatus gibt SKIPPED zurück	Die Eingabe wurde als Abfrage ohne Assistenzbedarf bewertet (z. B. eine kurze Begrüßung).	Senden Sie eine substanzielle Aufgabenabfrage. 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 ADC 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 nicht der Inhaber oder ein Administrator.	Veröffentlichen Sie den Workflow im Workflow Builder und geben Sie ihn für den Aufrufer frei.
HTTP 403 mit User does not have permission to access the Agent.	Der Workflow wurde nicht für den Aufrufer freigegeben.	Geben Sie den Workflow für den Aufrufer frei.
Workflow verhält sich wie eine ältere Version	Bei dem Aufruf wird die veröffentlichte Version ausgeführt, nicht unveröffentlichte Änderungen im Workflow Builder.	Veröffentlichen Sie den Workflow.
Workflow-Aufruf 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

• Suchergebnisse von StreamAssist abrufen
• REST API-Referenz für streamAssist
• Übersicht über Agenten