Diffuser des réponses à l'aide de la récupération agentique

Cette page présente la récupération agentique et explique comment l'utiliser avec la méthode stream answers.

À propos de la récupération agentique

La récupération agentique utilisée avec la méthode stream answers peut obtenir de meilleurs résultats pour certains cas d'utilisation. Par exemple, elle peut activer la récupération multipasse pour les applications comportant plusieurs datastores ou personnaliser la génération de réponses pour différentes classes de requêtes.

L'utilisation de la récupération agentique ajoute une certaine complexité à vos applications, mais offre en contrepartie plus de contrôle sur les résultats.

Agent Search inclut un agent prédéfini que vous pouvez utiliser pour personnaliser le comportement d'un moteur de recherche. Cela permet une plus grande personnalisation que celle disponible via l'interface utilisateur des configurations d'application ou la méthode de réponse en streaming sans récupération agentique.

Recherche combinée avec et sans récupération agentique

La récupération agentique est particulièrement utile pour les applications de recherche combinée. Sans récupération agentique, la recherche utilise une distribution ramifiée à passe unique qui interroge tous vos datastores en même temps. En revanche, la récupération agentique permet une recherche multipasse. L'agent planifie et exécute les recherches de manière séquentielle, en choisissant les meilleurs outils pour chaque étape. Il peut combiner les résultats de plusieurs datastores Agent Search et utiliser des outils tels que la recherche Google et Google Maps.

Par exemple, vous disposez de datastores distincts pour les règles d'entreprise mondiales et les informations sur les bureaux régionaux. Un utilisateur demande : "Quelles sont les règles de conformité pour notre bureau de Tokyo ?" :

  • Sans récupération agentique : interroge simultanément le magasin de règles et le magasin de bureaux régionaux avec la chaîne de requête complète. Cela peut renvoyer des résultats fragmentés.

  • Avec récupération agentique : l'agent planifie l'exécution. Il récupère d'abord des informations sur le bureau de Tokyo dans le magasin régional. Ensuite, à l'aide de ce contexte spécifique, il effectue une deuxième recherche ciblée dans le magasin de règles.

    L'agent synthétise ces résultats en une seule réponse cohérente et plus précise.

La récupération agentique vous permet également d'effectuer des requêtes de recherche multitours (questions de suivi) sur les applications de recherche combinée. Sans récupération agentique, la recherche multitours ne fonctionne qu'avec les applications à data store unique. Pour conserver le contexte de la conversation sur plusieurs tours, associez éventuellement la récupération agentique à une session Agent Platform.

Classification des requêtes personnalisées

Les méthodes answer et streaming answer fournissent deux types de classification des requêtes : ADVERSARIAL_QUERY et NON_ANSWER_SEEKING_QUERY.

La récupération agentique vous permet de définir des types de classification supplémentaires pour correspondre à vos workflows d'entreprise. Le système utilise un classificateur pour déterminer l'intention de l'utilisateur et achemine la requête vers la configuration d'agent appropriée.

Par exemple, à partir de la requête, vous déterminez que l'intention de la requête est de suivre une commande et vous avez spécifié une classification TRACK_ORDER. Au lieu d'exécuter une recherche générique dans tous vos datastores, le système charge un agent spécialisé équipé des outils et des données nécessaires pour récupérer l'état de la livraison.

Comment activer et utiliser la récupération agentique

Vous pouvez activer la récupération agentique de deux manières :

  • Agent de réponse Google prédéfini : si vous disposez déjà d'une application de recherche dans Agent Search, vous pouvez activer la récupération agentique en définissant enable_agent_invocation=true dans les requêtes API lorsque vous envoyez des requêtes à l'application. Dans ce cas, vous conservez la configuration de diffusion de recherche existante.

  • Application en mode IA personnalisé : lorsque vous créez une application Agent Search, vous définissez un autre type de configuration de diffusion, la configuration de diffusion default_agent_answer. On peut également parler de moteur en mode IA personnalisé, car les termes "application" et "moteur" sont utilisés de manière interchangeable dans Agent Search.

Avant de commencer

Avant de pouvoir utiliser la récupération agentique, procédez comme suit :

Configurer un moteur de raisonnement pour les sessions multitours

Pour conserver le contexte de la conversation sur plusieurs tours, vous devez créer un Agent Runtime sur la plate-forme Gemini Enterprise Agent engine (également appelé reasoning engine).

Lorsque vous effectuez une requête streamAnswer, vous transmettez le nom de ressource de l'Agent Runtime en tant que champ reasoningEngine dans la requête streamAnswer.

  1. Activez le Agent Platform sur votre Google Cloud projet.

  2. Créez une instance Agent Runtime (également appelée moteur de raisonnement) à l'aide de l'API REST Agent Engine (ou d' Agent Development Kit). L'instance héberge les sessions utilisées par la méthode streamAnswer.

    Le nom de ressource de l'instance est au format suivant :

    projects/PROJECT_NUMBER/locations/LOCATION_ID/reasoningEngines/REASONING_ENGINE_ID

  3. Accordez à l'agent de service Discovery Engine l'accès au moteur de raisonnement en attribuant le rôle roles/aiplatform.reasoningEngineServiceAgent au compte de service Discovery Engine :

    service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com

    où PROJECT_NUMBER est le numéro du projet qui héberge le moteur de raisonnement. Cette autorisation permet au backend de réponse en streaming de créer, de lire et d'ajouter des événements aux sessions en votre nom.

  4. Consultez les quotas applicables. Les sessions soutenues par Agent Runtime consomment des quotas de l'API Agent Platform. Les quotas qui nous intéressent sont les suivants :

    • aiplatform.googleapis.com/session_write_requests : créer, supprimer ou mettre à jour des sessions Agent Runtime par minute.

    • aiplatform.googleapis.com/session_event_append_requests : ajouter un événement aux sessions Agent Runtime par minute.

    Pour en savoir plus, consultez Quotas d'Agent Engine de Gemini Enterprise Agent Platform.

  5. Notez le nom de ressource Agent Runtime, car vous devez le transmettre en tant que champ reasoningEngine dans la requête streamAnswer.

Facultatif : configurer une application en mode IA personnalisé

Par défaut, la récupération agentique utilise l'agent de réponse Google prédéfini. Cela classe les requêtes en intentions DEFAULT_ANSWER_SEEKING et DO_NOT_ANSWER. Vous pouvez créer une application en mode IA personnalisé lorsque vous souhaitez personnaliser des outils ou ajouter la prise en charge de nouvelles classes d'intentions de requête. Chaque intention personnalisée (ou frame) déclare les conditions dans lesquelles l'agent classe une requête dans l'intention, ainsi que les instructions et les outils que l'agent utilise pour la gérer.

  1. Créez le moteur via la méthode REST engines.create avec un bloc engine_config.answer_agent.

    La configuration est structurée comme suit :

    engine {
 name: "YOUR_AI_MODE_ENGINE"
 display_name: "YOUR_AI_MODE_ENGINE_DISPLAY_NAME"
 engine_config {
   answer_agent {
     frames {
       vertical_intent: "YOUR_CUSTOM_INTENT"
       vertical_intent_prompt {
         instructions: "Instructions for when to classify a user query as YOUR_CUSTOM_INTENT."
       }
       initial_prompt {
         instructions: "Instructions for the agent on how to process a user query classified as YOUR_CUSTOM_INTENT."
         tools {
           discovery_engine_search_tool_config {
             serving_config: "YOUR_SEARCH_SERVING_CONFIG_1"
             page_size: 10
           }
           tool_description: "This tool can help search corpus 1."
         }
         tools {
           discovery_engine_search_tool_config {
             serving_config: "YOUR_SEARCH_SERVING_CONFIG_2"
             page_size: 10
           }
           tool_description: "This tool can help search corpus 2."
         }
       }
     }
   }
 }
}
engine_id: "SAMPLE_MULTI_SEARCH_RETRIEVAL"

  2. Une fois le moteur créé, acheminez les requêtes via sa configuration de diffusion default_agent_answer :

    projects/*/locations/*/collections/*/engines/YOUR_AI_MODE_ENGINE/servingConfigs/default_agent_answer

  3. Pour obtenir de l'aide concernant la conception ou l'enregistrement d'une application en mode IA personnalisé, contactez l'assistance.

Diffuser une réponse à l'aide de la récupération agentique

La commande suivante montre comment appeler la méthode de réponse en streaming answer avec la récupération agentique activée. Comme pour la sortie sans récupération agentique, cet appel diffuse une réponse générée sous la forme d'une série de réponses JSON.

Si vous avez configuré un moteur de raisonnement, incluez son nom de ressource dans le champ reasoningEngine pour conserver la session sur plusieurs tours.

REST

Pour rechercher et obtenir des résultats avec une réponse générée en streaming, procédez comme suit :

  1. Exécutez la commande Curl suivante :

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/SERVING_CONFIG_ID:streamAnswer" \
  -d '{
        "query": { "text": "QUERY" },
        "session": "SESSION",
        "enableAgentInvocation": true,
        "userPseudoId": "USER_PSEUDO_ID",
        "reasoningEngine": "projects/PROJECT_NUMBER/locations/LOCATION_ID/reasoningEngines/REASONING_ENGINE_ID"
      }'

    Remplacez les éléments suivants :

    • PROJECT_ID : ID de votre Google Cloud projet.
    • APP_ID: ID de l'application Agent Search que vous souhaitez interroger.
    • SERVING_CONFIG_ID : pour utiliser une application en mode IA personnalisé, définissez cette valeur sur default_agent_answer. Pour utiliser l'agent de réponse Google prédéfini, définissez cette valeur sur default_search.
    • PROJECT_NUMBER : numéro du projet qui héberge le moteur de raisonnement.
    • QUERY: chaîne de texte libre contenant la question ou la requête de recherche.
    • SESSION : si vous poursuivez une conversation multitours, il s'agit du nom de ressource de la session renvoyé dans la réponse du tour précédent, par exemple projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/sessions/SESSION_ID. Si vous ne poursuivez pas une conversation, définissez cette valeur sur - (tiret).
    • USER_PSEUDO_ID : identifiant unique utilisé pour suivre le visiteur.
    • LOCATION_ID : emplacement de votre moteur de raisonnement, par exemple us-central1.
    • REASONING_ENGINE_ID : ID de l'instance Agent Engine que vous avez créée.

Python

Pour en savoir plus, consultez la documentation de référence sur l'API Agent Search.Python

Pour vous authentifier auprès d'Agent Search, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

L'exemple suivant utilise le client Discovery Engine Python (v1alpha) pour appeler stream_answer_query avec l'appel d'agent activé. Transmettez le champ reasoning_engine pour les sessions multitours.

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1alpha


def run_stream_answer_query():
    PROJECT_ID = "YOUR_PROJECT_ID"
    LOCATION = "global"  # or a specific region
    COLLECTION_ID = "default_collection"
    ENGINE_ID = "YOUR_ENGINE_ID"
    # Use "default_search" for the predefined Google answer agent, or
    # "default_agent_answer" if you have configured a custom AI_MODE app.
    SERVING_CONFIG_ID = "default_search"
    USER_ID = "user-id"
    QUERY_TEXT = "YOUR_QUERY_TEXT"
    REASONING_ENGINE_ID = "YOUR_REASONING_ENGINE_ID"
    # Use "-" to start a new session, or pass the sessionId returned in
    # the previous turn's response to continue an existing session.
    SESSION_ID = "-"

    SESSION_REF = (
        f"projects/{PROJECT_ID}/locations/{LOCATION}/collections/"
        f"{COLLECTION_ID}/engines/{ENGINE_ID}/sessions/{SESSION_ID}"
    )
    SERVING_CONFIG_ENGINE = (
        f"projects/{PROJECT_ID}/locations/{LOCATION}/collections/"
        f"{COLLECTION_ID}/engines/{ENGINE_ID}/servingConfigs/{SERVING_CONFIG_ID}"
    )
    REASONING_ENGINE = (
        f"projects/{PROJECT_ID}/locations/{LOCATION}/"
        f"reasoningEngines/{REASONING_ENGINE_ID}"
    )

    client_options = ClientOptions(
        api_endpoint="discoveryengine.googleapis.com"
    )

    client = discoveryengine_v1alpha.ConversationalSearchServiceClient(
        client_options=client_options
    )

    request = discoveryengine_v1alpha.AnswerQueryRequest(
        query=discoveryengine_v1alpha.Query(text=QUERY_TEXT),
        serving_config=SERVING_CONFIG_ENGINE,
        user_pseudo_id=USER_ID,
        enable_agent_invocation=True,
        session=SESSION_REF,
        reasoning_engine=REASONING_ENGINE,
    )

    print(f"Starting StreamAnswerQuery agentic session with: {request}")
    stream = client.stream_answer_query(request)

    try:
        for response in stream:
            print(f"Received response: {response}")
    except Exception as e:
        print(f"Error during streaming: {e}")


if __name__ == "__main__":
    run_stream_answer_query()

Obtenir la version Preview du SDK Discovery Engine

Le SDK Discovery Engine facilite l'interaction avec Google Cloud les services à partir de vos applications. Le SDK facilite la gestion des exceptions et l'authentification, et fournit des fonctionnalités telles que les nouvelles tentatives automatiques, la gestion de la pagination et la gestion des opération de longue durée.

Étant donné que la fonctionnalité de récupération agentique figure sur une liste d'autorisation, le SDK dont vous avez besoin pour utiliser cette fonctionnalité est différent des bibliothèques clientes Discovery Engine généralement disponibles.

Pour obtenir la version Preview du SDK Discovery Engine, procédez comme suit :

  1. Contactez l'assistance pour accéder au dossier Google Drive du SDK en preview.

  2. Téléchargez le package pour votre langue.

Modifications apportées à l'API

Étant donné que cette fonctionnalité figure sur une liste d'autorisation, la documentation de référence de l'API de la page de la méthode de réponse en streaming n'affiche pas tous les champs disponibles et nécessaires pour utiliser la récupération agentique avec la méthode de réponse en streaming. Les champs manquants sont documentés comme suit.

Champs du corps de la requête

  • enableAgentInvocation (booléen) : définissez la valeur sur true pour passer au traitement agentique avec la configuration de diffusion de recherche existante. Ce champ est facultatif si vous spécifiez une configuration de diffusion answer_agent avec une application en mode IA personnalisé.

  • reasoningEngine (chaîne) : nom de ressource de l' Agent Runtime qui héberge les sessions d'agent, au format projects/*/locations/*/reasoningEngines/*.

Champs de réponse

Lorsque la récupération agentique est activée, chaque élément généré Answer.Reference inclut les éléments suivants :

  • queries (chaîne répétée) : liste des requêtes émises par l'agent pour produire la référence.

Service de sessions

L'API REST du service de sessions n'est pas compatible avec les méthodes create ni update. Toutefois, elle est compatible avec les autres méthodes : list, get et delete.

L'API RPC du service de sessions n'est pas compatible avec les opérations Update ni Create sur les ressources de session utilisées pour les conversations multitours. Toutefois, elle est compatible avec les autres services : opérations List, Get et Delete sur les ressources de session utilisées pour les conversations multitours.