Appeler un agent spécifique avec l'API StreamAssist

Pour appeler un agent enregistré spécifique, fournissez le champ facultatif agentsSpec dans votre requête d'API REST streamAssist ou votre appel de bibliothèque cliente. L'API AgentsSpec définit la spécification des agents utilisés pour traiter la requête. L'assistant achemine les requêtes directement vers cet agent et préserve le contexte de la session entre les tours.

En bref

Spécification Détails
Méthode API projects.locations.collections.engines.assistants.streamAssist
Versions du point de terminaison v1alpha pour découvrir les ID d'agent ; v1 pour appeler streamAssist
Paramètre clé agentsSpec.agentSpecs[].agentId
Types d'agents compatibles Agents de chat Core Assistant, Deep Research et Agent Designer (anciennement low-code)
Autorisation IAM requise discoveryengine.assistants.assist
Champ d'application OAuth requis https://www.googleapis.com/auth/cloud-platform

Avant de commencer

  1. Activez l'API Discovery Engine (discoveryengine.googleapis.com) dans votre Google Cloud projet.
  2. Assurez-vous que votre compte principal (compte utilisateur ou compte de service) dispose d'un rôle qui accorde l'autorisation IAM discoveryengine.assistants.assist, par exemple Éditeur Discovery Engine (roles/discoveryengine.editor) ou Administrateur Gemini Enterprise (roles/discoveryengine.agentspaceAdmin).
  3. Vérifiez que votre application Gemini Enterprise (moteur) est créée et contient au moins un agent enregistré.
  4. Si vous vous authentifiez à l'aide des identifiants par défaut de l'application (ADC), assurez-vous que votre client envoie l'en-tête du projet de quota : -H "X-Goog-User-Project: PROJECT_ID".

Trouver l'ID et l'emplacement de votre application

L'URL streamAssist nécessite l'ID de votre moteur et son emplacement (global, us ou eu). Si vous ne connaissez que le nom à afficher de l'application, listez les moteurs de votre projet pour trouver l'ID sous-jacent :

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"

Dans la réponse, le format name du moteur est projects/{project}/locations/{location}/collections/default_collection/engines/{ENGINE_ID}. Le segment ENGINE_ID est l'APP_ID requis dans l'appel.

Trouver l'ID de l'agent

agentId est le dernier segment du nom complet de la ressource de l'agent dans l'API Discovery Engine :

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

Les agents enregistrés utilisent un long ID numérique (par exemple, 15492003793394502655) plutôt qu'un nom à afficher convivial. Ne fournissez que cette chaîne numérique finale {AGENT_ID} dans votre requête.

Pour lister les agents enregistrés dans votre application et découvrir leurs ID numériques, appelez la collection agents sur le point de terminaison v1alpha :

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"

Chaque ressource d'agent renvoyée inclut les champs suivants :

  • name : chemin d'accès complet à la ressource se terminant par {AGENT_ID}.
  • displayName : nom lisible affiché dans la Google Cloud console.
  • state : état opérationnel (par exemple, ENABLED ou PRIVATE).
  • Objet de définition indiquant le type d'agent (par exemple, a2aAgentDefinition ou lowCodeAgentDefinition).

Consultez la documentation de référence de l'API REST agents pour obtenir le schéma complet de la ressource d'agent.

Envoyer des requêtes aux agents

Pour envoyer des requêtes à un agent spécifique, vous devez créer votre requête avec le agentsSpec approprié et l'exécuter à l'aide de REST ou de bibliothèques clientes.

Structure du corps de la requête

Pour acheminer une requête vers un agent spécifique, incluez l'objet facultatif agentsSpec dans le corps de votre requête POST :

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

Référence de champ

  • agentsSpec (objet, facultatif) : spécification des agents utilisés pour traiter la requête.
  • agentsSpec.agentSpecs[] (tableau, facultatif): liste des spécifications de l'agent. Vous pouvez spécifier plusieurs agents dans ce tableau.
  • agentsSpec.agentSpecs[].agentId (chaîne, obligatoire dans la spécification): ID identifiant la ressource d'agent enregistrée. Doit être conforme à la norme RFC-1034 et ne pas dépasser 63 caractères.

Consultez la documentation de référence de l'API REST streamAssist pour obtenir le schéma complet de la requête.

Appeler streamAssist

REST

La commande curl suivante envoie une requête à un agent spécifique à l'aide de l'API REST :

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

Remplacez les espaces réservés suivants :

  • LOCATION: région multiple pour le nom d'hôte et le chemin d'accès à la ressource (global, us ou eu). Si votre application réside dans l'emplacement global, omettez le préfixe d'emplacement du nom d'hôte (discoveryengine.googleapis.com).
  • PROJECT_ID: ID du projet Google Cloud .
  • APP_ID: ID de votre moteur Gemini Enterprise (découvert dans Trouver l'ID et l'emplacement de votre application).
  • AGENT_ID : ID numérique de l'agent (découvert dans Trouver l'ID de l'agent).

Python

Cet exemple Python appelle streamAssist à l'aide de la bibliothèque cliente google-cloud-discoveryengine :

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

Comprendre la réponse de streaming

Le point de terminaison streamAssist renvoie un flux de blocs JSON sur REST ou un itérateur d'objets de réponse dans les bibliothèques clientes :

  • Texte de réponse : le texte de réponse incrémentiel arrive dans answer.replies[].groundedContent.content.text. Concaténez ces fragments de texte dans l'ordre de réception pour reconstruire la réponse complète.
  • Reasoning fragments : les fragments marqués avec "thought": true représentent le processus de raisonnement interne du modèle. Filtrez ces fragments lorsque vous présentez le résultat final aux utilisateurs finaux.
  • État d'exécution : le champ answer.state passe de IN_PROGRESS à un état final :
    • SUCCEEDED : la requête a été traitée et une réponse a été générée.
    • SKIPPED : la requête a été ignorée ou contournée. Inspectez assistSkippedReasons pour plus de détails (par exemple, NON_ASSIST_SEEKING_QUERY_IGNORED pour les brèves salutations).
    • FAILED : l'invocation a rencontré une erreur d'exécution.
  • Continuité de la session : le bloc de terminaison inclut sessionInfo.session (nom de la ressource de session) et un assistToken.

Poursuivre la conversation dans la même session

Pour conserver le contexte entre les tours, transmettez la session chaîne de sessionInfo dans les requêtes suivantes :

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

Si vous omettez le champ session ou spécifiez - comme ID de session, l'API génère automatiquement une session isolée.

Limites

Les limites suivantes s'appliquent lorsque vous appelez des agents avec streamAssist :

  • Types d'agents non compatibles:
  • Actions mutatives : l'API streamAssist est optimisée pour les requêtes conversationnelles et la récupération en lecture seule via des connecteurs. L'exécution programmatique d'outils et d'actions mutatifs (tels que la rédaction d'e-mails, la création d'événements d'agenda ou la messagerie instantanée) n'est pas compatible avec streamAssist. Toute tentative d'invocation d'un workflow d'agent qui exécute des actions mutatives peut entraîner des échecs silencieux ou des boucles d'exécution non fondées.

Dépannage

Utilisez le tableau suivant pour résoudre les erreurs d'invocation streamAssist courantes :

Problème constaté Cause probable Solution
Erreur HTTP 404 lors de la liste des agents Appel de agents sur le point de terminaison v1 ou v1beta. Envoyez plutôt la requête de liste au point de terminaison v1alpha.
La réponse semble générique malgré la définition de agentsSpec agentId numérique non valide ou requête trop générique pour déclencher un comportement de domaine. Vérifiez l'ID numérique exact dans la liste des agents v1alpha, envoyez une requête spécifique au domaine et vérifiez que le texte de la réponse contient une formulation spécifique à l'agent.
Aucune erreur n'est renvoyée, mais l'agent cible ne s'est pas exécuté agentId mal formé a entraîné un retour silencieux à l'orchestration par défaut. Vérifiez que agentId ne contient que des chiffres et qu'il correspond exactement à un ID de la liste de registre.
L'état de la réponse renvoie SKIPPED L'entrée a été évaluée comme une requête ne nécessitant pas d'assistance (par exemple, une brève salutation). Envoyez une requête de tâche substantielle et inspectez assistSkippedReasons dans la charge utile de la réponse.
HTTP 401 ou HTTP 403 Permission Denied Champ d'application OAuth manquant, rôle IAM insuffisant ou en-tête de projet de quota manquant. Vérifiez que l'appelant dispose de discoveryengine.assistants.assist, assurez-vous que le champ d'application OAuth inclut cloud-platform et ajoutez -H "X-Goog-User-Project: PROJECT_ID" si vous utilisez ADC.

Étape suivante