Trasmettere le risposte in streaming utilizzando il recupero agentico

Questa pagina introduce il recupero con agent e spiega come utilizzarlo con il metodo stream answers.

Informazioni sul recupero agentico

Il recupero basato su agenti utilizzato con il metodo delle risposte in streaming può ottenere risultati migliori per determinati casi d'uso, ad esempio, per attivare il recupero multi-passaggio per le app con più data store o per personalizzare la generazione di risposte per diverse classi di query.

L'utilizzo del recupero autonomo aggiunge un po' di complessità alle tue app, ma in cambio offre un maggiore controllo sui risultati.

La ricerca dell'agente include un agente predefinito che puoi utilizzare per personalizzare il comportamento di un motore di ricerca. Ciò consente una personalizzazione maggiore rispetto a quella disponibile tramite l'interfaccia utente di configurazione dell'app o il metodo di risposta in streaming senza recupero agentico.

Ricerca ibrida con e senza recupero autonomo

Il recupero autonomo è particolarmente utile per le app di ricerca ibrida. Senza il recupero agente, la ricerca utilizza un fan-out a passaggio singolo che esegue query su tutti i tuoi archivi di dati contemporaneamente. Al contrario, il recupero agentico consente la ricerca multi-pass. L'agente pianifica ed esegue le ricerche in sequenza, scegliendo gli strumenti migliori per ogni passaggio. Può combinare i risultati di più archivi di dati di Agent Search e utilizzare anche strumenti come la Ricerca Google e Google Maps.

Ad esempio, hai archivi di dati separati per le politiche aziendali globali e i dettagli delle sedi regionali. Un utente chiede: "Quali sono le norme di conformità per il nostro ufficio di Tokyo?":

  • Senza recupero agentico: esegue query simultaneamente nell'archivio delle norme e nell'archivio dell'ufficio regionale con la stringa di query completa. In questo modo potresti ottenere risultati frammentati.

  • Con il recupero agentico: l'agente pianifica l'esecuzione. Recupera innanzitutto i dettagli dell'ufficio di Tokyo dallo store regionale. Poi, utilizzando questo contesto specifico, esegue una seconda ricerca mirata nello store dei criteri.

    L'agente sintetizza questi risultati in una risposta singola, coerente e più accurata.

Il recupero agentico ti consente anche di eseguire query di ricerca in più passaggi (domande di follow-up) nelle app di ricerca combinate. Senza il recupero agentico, la ricerca multi-turn funziona solo con app con un singolo datastore. Per mantenere il contesto della conversazione in più turni, accoppia facoltativamente il recupero agentico a una sessione della piattaforma agentica.

Classificazione delle query personalizzate

I metodi answer e streaming answer forniscono due tipi di classificazione delle query: ADVERSARIAL_QUERY e NON_ANSWER_SEEKING_QUERY.

Il recupero basato su agenti ti consente di definire tipi di classificazione aggiuntivi in base ai workflow della tua attività. Il sistema utilizza un classificatore per determinare l'intento dell'utente e indirizza la richiesta alla configurazione dell'agente appropriata.

Ad esempio, dalla query determini che l'intent è quello di monitorare un ordine e hai specificato una classificazione TRACK_ORDER. Anziché eseguire una ricerca generica in tutti i datastore, il sistema carica un agente specializzato dotato degli strumenti e dei dati necessari per recuperare lo stato della spedizione.

Modi per attivare e utilizzare il recupero autonomo

Esistono due modi per attivare il recupero autonomo:

  • Agente di risposta Google predefinito: se hai già un'app di ricerca in Agent Search, puoi attivare il recupero agentico impostando enable_agent_invocation=true nelle richieste API quando inviate query all'app. In questo caso, mantieni la configurazione di pubblicazione della ricerca esistente.

  • App in modalità AI personalizzata:quando crei un'app di ricerca dell'agente, definisci un tipo diverso di configurazione di pubblicazione, ovvero la configurazione di pubblicazione default_agent_answer. Questo motore potrebbe anche essere chiamato motore AI personalizzato perché "app" e "motore" vengono usati in modo intercambiabile in Agent Search.

Prima di iniziare

Prima di poter utilizzare il recupero con agenti, segui questi passaggi:

Configurare un motore di ragionamento per le sessioni multi-turno

Per mantenere il contesto della conversazione in più turni, devi creare un motore di Agent Runtime su Gemini Enterprise Agent Platform (chiamato anche motore di ragionamento).

Quando effettui una richiesta streamAnswer, trasmetti il nome della risorsa di Agent Runtime come campo reasoningEngine nella richiesta streamAnswer.

  1. Abilita la piattaforma per agenti nel tuo progetto Google Cloud .

  2. Crea un'istanza di Agent Runtime (chiamata anche motore di ragionamento) utilizzando l'API REST Agent Engine (o l'Agent Development Kit). L'istanza ospita le sessioni utilizzate dal metodo streamAnswer.

    Il nome della risorsa dell'istanza ha il formato:

    projects/PROJECT_NUMBER/locations/LOCATION_ID/reasoningEngines/REASONING_ENGINE_ID

  3. Concedi all'agente di servizio Discovery Engine l'accesso al motore di ragionamento concedendo il ruolo roles/aiplatform.reasoningEngineServiceAgent account di serviziount Discovery Engine:

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

    dove PROJECT_NUMBER è il numero del progetto che ospita il motore di ragionamento. Questa autorizzazione consente al backend di risposta in streaming di creare, leggere e aggiungere eventi alle sessioni per tuo conto.

  4. Esamina le quote applicabili. Le sessioni supportate da Agent Runtime consumano quote dall'API Agent Platform. Le quote di interesse sono:

    • aiplatform.googleapis.com/session_write_requests: crea, elimina o aggiorna le sessioni di runtime dell'agente al minuto.

    • aiplatform.googleapis.com/session_event_append_requests: aggiungi un evento alle sessioni di Agent Runtime al minuto.

    Per saperne di più, consulta Quote di Gemini Enterprise Agent Platform Agent Engine.

  5. Prendi nota del nome della risorsa Agent Runtime perché devi passarlo come campo reasoningEngine nella richiesta streamAnswer.

(Facoltativo) Configura un'app in modalità AI personalizzata

Per impostazione predefinita, il recupero con agenti utilizza l'agente di risposta Google predefinito. Questa classifica le query in intenti DEFAULT_ANSWER_SEEKING e DO_NOT_ANSWER. Puoi creare un'app in modalità AI personalizzata quando vuoi personalizzare gli strumenti o aggiungere il supporto per nuove classi di intent di query. Ogni intent personalizzato (o frame) dichiara le condizioni in base alle quali l'agente classifica una query nell'intent e le istruzioni e gli strumenti che l'agente utilizza per gestirla.

  1. Crea il motore tramite il metodo REST engines.create con un blocco engine_config.answer_agent.

    La configurazione è strutturata nel seguente modo:

    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. Dopo aver creato il motore, indirizza le richieste tramite la relativa configurazione di pubblicazione default_agent_answer:

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

  3. Per ricevere assistenza nella progettazione o nella registrazione di un'app in modalità AI personalizzata, contatta l'assistenza.

Trasmettere in streaming una risposta utilizzando il recupero agentico

Il seguente comando mostra come chiamare il metodo streaming answer con il recupero agentico abilitato. Analogamente all'output senza recupero agentico, questa chiamata trasmette in streaming una risposta generata sotto forma di una serie di risposte JSON.

Se hai configurato un motore di ragionamento, includi il nome della risorsa nel campo reasoningEngine per mantenere la sessione durante i turni.

REST

Per cercare e ottenere risultati con una risposta generata in streaming:

  1. Esegui questo comando curl:

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

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo Google Cloud progetto.
    • APP_ID: l'ID dell'app Agent Search che vuoi interrogare.
    • SERVING_CONFIG_ID: per utilizzare un'app personalizzata in modalità AI, imposta questo valore su default_agent_answer. Per utilizzare l'agente di risposta Google predefinito, imposta questo valore su default_search.
    • PROJECT_NUMBER: il numero del progetto che ospita il motore di ragionamento.
    • QUERY: una stringa di testo libero che contiene la domanda o la query di ricerca.
    • SESSION: se continui una conversazione multi-turn, questo è il nome della risorsa sessione restituito nella risposta del turno precedente, ad esempio projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/sessions/SESSION_ID. Se non continui una conversazione, imposta questo valore su -, un trattino.
    • USER_PSEUDO_ID: un identificatore univoco utilizzato per monitorare il visitatore.
    • LOCATION_ID: la posizione del motore di ragionamento, ad esempio us-central1.
    • REASONING_ENGINE_ID: l'ID dell'istanza di Agent Engine che hai creato.

Python

Per saperne di più, consulta la documentazione di riferimento dell'API Agent Search Python.

Per eseguire l'autenticazione in Agent Search, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

L'esempio seguente utilizza il client Python di Discovery Engine (v1alpha) per chiamare stream_answer_query con l'invocazione dell'agente abilitata. Passa il campo reasoning_engine per le sessioni multiturno.

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

Ottenere la versione di anteprima dell'SDK Discovery Engine

L'SDK Discovery Engine semplifica l'interazione con i servizi Google Cloud dalle tue applicazioni. L'SDK aiuta a gestione degli errori e l'autenticazione e fornisce funzionalità come nuovi tentativi automatici, gestione della paginazione e gestionoperazione a lunga esecuzionene.

Poiché la funzionalità di recupero con agente è inclusa in una lista consentita, l'SDK che devi utilizzare con questa funzionalità è diverso dalle librerie client di Discovery Engine generalmente disponibili.

Per ottenere la versione di anteprima dell'SDK Discovery Engine:

  1. Contatta l'assistenza per accedere alla cartella Google Drive dell'SDK di anteprima.

  2. Scarica il pacchetto per la tua lingua.

Modifiche alle API

Poiché questa funzionalità è inclusa in una lista consentita, la documentazione di riferimento dell'API nella pagina del metodo streaming answer non mostra tutti i campi disponibili e necessari per utilizzare il recupero agentico con il metodo stream answer. I campi mancanti sono documentati come segue.

Campi del corpo della richiesta

  • enableAgentInvocation (booleano) — Imposta true per passare all'elaborazione con agente con la configurazione di gestione della ricerca esistente. Questo campo è facoltativo se stai specificando una configurazione di pubblicazione answer_agent con un'app in modalità AI personalizzata.

  • reasoningEngine (stringa): il nome della risorsa di Agent Runtime che ospita le sessioni dell'agente, formattato come projects/*/locations/*/reasoningEngines/*.

Campi di risposta

Quando il recupero agentico è abilitato, ogni Answer.Reference generato include:

  • queries (stringa ripetuta) - L'elenco delle query emesse dall'agente per produrre il riferimento.

Servizio di sessione

L'API REST del servizio di sessione non supporta i metodi create o update. Tuttavia, supporta gli altri metodi: list, get e delete.

L'API RPC del servizio Session non supporta le operazioni Update o Create sulle risorse di sessione utilizzate per le conversazioni multi-turno. Tuttavia, supporta l'altro servizio: List, Get e Delete operazioni sulle risorse di sessione utilizzate per le conversazioni multi-turn.