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 und Chat-Agenten des Agent Designer (ehemals Low-Code)
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 ihr 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.

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 diesen letzten numerischen String {AGENT_ID} an.

Wenn Sie die in Ihrer 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"

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 oder lowCodeAgentDefinition.

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.

Struktur des Anfragetextes

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: Ihre Google Cloud Projekt-ID.
  • 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 die endgültige Ausgabe für Endnutzer 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 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.

Beschränkungen

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

  • Nicht unterstützte Agententypen:
    • Workflow-Agenten werden nicht unterstützt.
    • A2A- oder ADK-Agenten, die in einer 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 schreibgeschützten Abruf über Connectors optimiert. Die programmatische Ausführung mutativer Tools und Aktionen (z. B. E-Mail-Entwürfe, Kalendertermine erstellen 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 fundierten 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 am Endpunkt v1 oder v1beta aufrufen. Senden Sie die Listenanfrage stattdessen an den Endpunkt v1alpha.
Antwort erscheint trotz Einstellung von agentsSpec Ungültige numerische agentId oder die Abfrage ist zu allgemein, um das Domainverhalten auszulösen. Bestätigen Sie die genaue numerische ID aus 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 Eingabe als nicht assistenzbezogene Abfrage 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 die Berechtigung 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.

Nächste Schritte