Appeler un agent spécifique avec l'API StreamAssist

Pour appeler un agent enregistré spécifique, indiquez le champ agentsSpec facultatif dans votre requête API REST streamAssist ou votre appel de bibliothèque cliente. L'API AgentsSpec définit la spécification des agents utilisés pour diffuser la requête. L'assistant achemine les requêtes directement vers cet agent et conserve le contexte de la session d'un tour à l'autre.

En bref

Spécification	Détails
Méthode API	projects.locations.collections.engines.assistants.streamAssist
Versions de point de terminaison	v1alpha pour découvrir les ID d'agent ; v1 pour appeler streamAssist
Paramètre de 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 projet Google Cloud .
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 localiser 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 du moteur name est projects/{project}/locations/{location}/collections/default_collection/engines/{ENGINE_ID}. Le segment ENGINE_ID est le APP_ID requis dans l'appel.

Remarque : L'ID du moteur comporte généralement 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 ID numérique long (par exemple, 15492003793394502655) plutôt qu'un nom à afficher convivial. Ne fournissez que cette chaîne numérique {AGENT_ID} finale 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. 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 console Google Cloud .
• state : état opérationnel (par exemple, ENABLED ou PRIVATE).
• Objet de définition indiquant le type d'agent (par exemple, 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 REST ou de bibliothèques clientes.

Remarque : Si un agent s'appuie sur des connecteurs ou des datastores internes (comme les agents de questions-réponses sur les documents), l'appeler 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 agentsSpec facultatif 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 diffuser la requête.
• agentsSpec.agentSpecs[] (tableau, facultatif) : liste de spécifications d'agents. 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é. 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 de requête complet.

Assistance aux appels

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 : emplacement multirégional 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 de votre 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 en streaming

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

• Texte de la réponse : le texte de la réponse incrémentielle arrive dans answer.replies[].groundedContent.content.text. Concaténez ces fragments de texte dans l'ordre de réception pour reconstituer la réponse complète.
• Fragments de raisonnement : les fragments marqués par "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 abouti et a généré une réponse.
  • 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 salutations brèves).
  • FAILED : l'appel a rencontré une erreur d'exécution.
• Continuité de la session : le fragment terminal inclut sessionInfo.session (le nom de la ressource de session) et un assistToken.

Poursuivre la conversation dans la même session

Pour conserver le contexte d'un tour à l'autre, transmettez la chaîne session 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 nouvelle 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 avez pas publiées. 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é une fois 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 doit comporter exactement un 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 il ne remplit pas les variables d'entrée.

Limites

Les limites suivantes s'appliquent lors de l'appel d'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 de mutation : 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 de mutation (comme la rédaction d'e-mails, la création d'événements d'agenda ou l'envoi de messages de chat) n'est pas compatible avec streamAssist. Tenter d'appeler un workflow agentique qui exécute des actions de mutation peut entraîner des échecs silencieux ou des boucles d'exécution non ancrées.

Dépannage

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

Problème constaté	Cause probable	Solution
Erreur HTTP 404 lors de l'affichage de la liste des agents	Appeler agents sur le point de terminaison v1 ou v1beta.	Envoyez la requête de liste au point de terminaison v1alpha à la place.
La réponse semble générique malgré le paramètre agentsSpec	agentId numérique non valide, ou la requête est trop générique pour déclencher le comportement du domaine.	Confirmez 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é	Un agentId incorrect a entraîné un remplacement silencieux par l'orchestration par défaut.	Vérifiez que l'ID agentId ne contient que des chiffres et correspond exactement à un ID de la liste du registre.
L'état de la réponse renvoie SKIPPED	Entrée évaluée comme une requête ne demandant pas d'aide (par exemple, une salutation brève).	Envoyez une requête de tâche substantielle, puis 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.
HTTP 403 par 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'en est pas le propriétaire ni un administrateur.	Publiez le workflow dans Workflow Builder et partagez-le avec l'appelant.
HTTP 403 par 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 et un autre déclencheur, ou plusieurs déclencheurs manuels.	Conservez un seul déclencheur manuel.

Étapes suivantes

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