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	Assistant principal, Deep Research, agents de chat Workflow Builder (anciennement low-code) et workflows Workflow Builder (voir Appeler un workflow)
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 accordant l'autorisation IAM discoveryengine.assistants.assist, tel que É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.

Remarque : L'ID du moteur est généralement suivi d'un suffixe numérique ajouté au nom à afficher (par exemple, my-app_1234567890).

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"

Important : La collection agents est diffusée exclusivement sur le point de terminaison v1alpha. L'appel de ce point de terminaison de liste sur v1 ou v1beta renvoie une erreur HTTP 404 Not Found error. Toutefois, l'appel d'invocation streamAssist lui-même fonctionne sur v1.

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 par l'humain affiché dans la Google Cloud console.
• state : état opérationnel (tel que ENABLED ou PRIVATE).
• Objet de définition indiquant le type d'agent (tel que a2aAgentDefinition, lowCodeAgentDefinition ou workflowAgentDefinition).

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 bibliothèques REST ou clientes.

Remarque : Si un agent s'appuie sur des connecteurs ou des magasins de données internes (tels que les agents de questions-réponses sur les documents), l'invocation sans sources de données configurées génère une réponse "aucune source de données configurée" plutôt qu'une erreur d'API.

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érences 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 avec une longueur maximale de 63 caractères.

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

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 se trouve 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 la 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.
• Fragments de raisonnement : les fragments marqués avec "thought": true représentent le processus de raisonnement interne du modèle. Filtrez ces fragments lorsque vous présentez la sortie finale 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 en savoir plus (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.

Appeler un workflow

Pour exécuter un workflow Workflow Builder, envoyez la même requête avec l'ID du workflow dans agentsSpec.agentSpecs[].agentId. Chaque appel démarre une exécution manuelle du workflow.

• Version exécutée : si le workflow est publié, l'appel exécute sa version publiée. Les modifications enregistrées dans Workflow Builder, mais pas encore publiées, n'affectent pas les appelants d'API tant que vous ne les publiez pas. Si le workflow n'a jamais été publié, l'appel exécute son brouillon.
• Qui peut l'appeler : le propriétaire et les administrateurs du workflow peuvent l'appeler. Les autres utilisateurs peuvent appeler un workflow publié après qu'il a été partagé avec eux. Seul le propriétaire ou un administrateur peut appeler un workflow qui n'a jamais été publié ; les autres appelants reçoivent HTTP 403.
• Déclencheurs : le workflow ne doit comporter qu'un seul déclencheur manuel. Les appels échouent pour un workflow qui combine un déclencheur manuel avec un autre déclencheur, ou qui comporte plusieurs déclencheurs manuels.
• Entrées : vous ne pouvez pas définir les variables d'entrée du déclencheur manuel via streamAssist. Si le déclencheur manuel comporte une entrée obligatoire, l'exécution échoue, même si l'entrée a une valeur par défaut. Les entrées facultatives sont vides et leurs valeurs par défaut ne sont pas appliquées. Le texte de la requête est transmis aux nœuds LLM du workflow. Vous pouvez donc y inclure des données, mais cela ne remplit pas les variables d'entrée.

Limites

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

• Types d'agents non compatibles : les agents A2A ou ADK enregistrés dans une application Gemini Enterprise ne sont pas compatibles avec streamAssist. Pour appeler directement un agent A2A à l'aide de son point de terminaison de registre, consultez Appeler un agent à l'aide de son point de terminaison A2A de registre.
• 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 agentique 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
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 ; vérifiez le texte de la réponse pour obtenir une formulation spécifique à l'agent.
Aucune erreur 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 est é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 ; 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 ; ajoutez -H "X-Goog-User-Project: PROJECT_ID" si vous utilisez ADC.
HTTP 403 avec Only the agent owner or an admin can run a draft of this agent.	Le workflow n'a jamais été publié et l'appelant n'est ni son propriétaire ni un administrateur.	Publiez le workflow dans Workflow Builder et partagez-le avec l'appelant.
HTTP 403 avec User does not have permission to access the Agent.	Le workflow n'est pas partagé avec l'appelant.	Partagez le workflow avec l'appelant.
Le workflow se comporte comme une ancienne version	L'appel exécute la version publiée, et non les modifications non publiées dans Workflow Builder.	Publiez le workflow.
L'appel de workflow se termine par answer.state FAILED et une erreur INTERNAL	Le workflow comporte un déclencheur manuel plus un autre déclencheur, ou plusieurs déclencheurs manuels.	Conservez un seul déclencheur manuel.

Étape suivante

• Obtenir des résultats de recherche à partir de StreamAssist
• Documentation de référence de l'API REST streamAssist
• Présentation des agents