Nota:Vertex AI Search verrà rinominato Agent Search. Stiamo aggiornando i contenuti per riflettere il nuovo brand.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Trasmettere le risposte in streaming utilizzando il recupero agentico

Questa pagina presenta il recupero agentico e spiega come utilizzarlo con il metodo stream answers.

Informazioni sul recupero agentico

Il recupero agentico utilizzato con il metodo stream answers può ottenere risultati migliori per determinati casi d'uso, ad esempio per abilitare il recupero multi-pass per le app con più datastore o per personalizzare la generazione di risposte per diverse classi di query.

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

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

Ricerca combinata con e senza recupero agentico

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

Ad esempio, hai datastore separati per le norme aziendali globali e i dettagli degli uffici regionali. Un utente chiede: "Quali sono le norme di conformità per il nostro ufficio di Tokyo?":

Senza recupero agentico: esegue query simultaneamente sia sul negozio di norme sia sul negozio dell'ufficio regionale con la stringa di query completa. Potrebbe restituire risultati frammentati.
Con il recupero agentico: l'agente pianifica l'esecuzione. Innanzitutto, recupera i dettagli dell'ufficio di Tokyo dal negozio regionale. Poi, utilizzando questo contesto specifico, esegue una seconda ricerca mirata nel negozio di norme.

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) sulle app di ricerca combinata. Senza il recupero agentico, la ricerca in più passaggi funziona solo con le app di un singolo datastore. Per mantenere il contesto della conversazione in più passaggi, puoi abbinare il recupero agentico a una sessione di Agent Platform.

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 agentico ti consente di definire tipi di classificazione aggiuntivi in base ai tuoi flussi di lavoro aziendali. 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'intento della query è 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.

Modalità di attivazione e utilizzo del recupero agentico

Esistono due modi per attivare il recupero agentico:

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 invii query all'app. In questo caso, mantieni la configurazione di pubblicazione della ricerca esistente.
App in modalità AI personalizzata: quando crei un'app di Agent Search, definisci un tipo diverso di configurazione di pubblicazione, la configurazione di pubblicazione default_agent_answer. Questa configurazione potrebbe essere definita anche motore in modalità AI personalizzato perché "app" e "motore" vengono utilizzati in modo intercambiabile in Agent Search.

Prima di iniziare

Prima di poter utilizzare il recupero agentico:

Configura un motore di ragionamento per le sessioni in più passaggi
(Facoltativo) Configura un'app in modalità AI personalizzata

Configura un motore di ragionamento per le sessioni in più passaggi

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

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

Attiva Agent Platform nel tuo Google Cloud progetto.
Crea un'istanza di Agent Runtime (chiamata anche motore di ragionamento) utilizzando l'API REST di 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
```
Concedi all'agente di servizio di Discovery Engine l'accesso al motore di ragionamento concedendo il ruolo roles/aiplatform.reasoningEngineServiceAgent al account di servizio di 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.
Esamina le quote applicabili. Le sessioni supportate da Agent Runtime utilizzano le quote dell'API Agent Platform. Le quote di interesse sono:
- aiplatform.googleapis.com/session_write_requests : crea, elimina o aggiorna le sessioni di Agent Runtime al minuto.
- aiplatform.googleapis.com/session_event_append_requests : aggiungi eventi alle sessioni di Agent Runtime al minuto.
Per saperne di più, consulta Quote di Agent Engine di Gemini Enterprise Agent Platform.
Prendi nota del nome della risorsa di Agent Runtime perché devi passarlo come campo reasoningEngine nella richiesta streamAnswer.

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

Per impostazione predefinita, il recupero agentico utilizza l'agente di risposta Google predefinito. Questo classifica le query in intent 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 utilizzati dall'agente per gestirla.

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

La configurazione è strutturata come segue:

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"

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
```
Per assistenza nella progettazione o nella registrazione di un'app in modalità AI personalizzata, contatta l'assistenza.

Trasmetti in streaming una risposta utilizzando il recupero agentico

Il seguente comando mostra come chiamare il metodo di risposta 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 relativo nome della risorsa nel campo reasoningEngine per mantenere la sessione in più passaggi.

REST

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

Esegui il seguente 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 di Agent Search su cui vuoi eseguire query.
SERVING_CONFIG_ID: per utilizzare un'app in modalità AI personalizzata, 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 in più passaggi, questo è il nome della risorsa della sessione restituito nella risposta del passaggio 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 località del motore di ragionamento, ad esempio us-central1.
REASONING_ENGINE_ID: l'ID dell'istanza di Agent Engine che hai creato.

Esempio di comando e risultato parziale

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/servingConfigs/default_serving_config:streamAnswer" \
  -d '{
        "query": { "text": "3 bedroom house in new haven" },
        "session": "projects/123456/locations/global/collections/default_collection/engines/my-app/sessions/-",
        "enableAgentInvocation": true,
        "userPseudoId": "user-1",
        "reasoningEngine": "projects/123456/locations/us-central1/reasoningEngines/6732301450535239680"
      }'

answer  {
  name: "projects/123456/locations/global/collections/default_collection/engines/my-app/sessions/7813433670721451971/answers/7813433670721454054"
  state: SUCCEEDED
  answer_text: "I found several 3-bedroom properties in New Haven, CT, that might interest you. Here are the top three results along with their nearby schools:\n\n### 1. 37 Emerson Street, New Haven, CT\n*   **Price:** $415,061\n*   **Details:** 3 Bedrooms, 1.5 Bathrooms, 1,961 sq. ft.\n*   **Description:** An elegant multi-family residence with a two-car garage, offering classic charm and modern convenience near universities.\n*   **Nearby Schools:**\n    *   **Elementary:** Edgewood Magnet School (Rating: 3.9/5)\n    *   **Middle:** Betsy Ross Arts Magnet School (Rating: 4.1/5)\n    *   **High:** Hillhouse High School (Rating: 3.2/5)\n\n### 2. 248 West Hazel Street, New Haven, CT\n*   **Price:** $374,255\n*   **Details:** 3 Bedrooms, 2 Bathrooms, 1,835 sq. ft.\n*   **Description:** A meticulously maintained multi-family home with a two-car garage, ideal for investment or multi-generational living.\n*   **Nearby Schools:**\n    *   **Elementary:** Worthington Hooker School (Rating: 4.4/5)\n    *   **Middle:** Engineering - Science University Magnet School (Rating: 4.2/5)\n    *   **High:** Hillhouse High School (Rating: 3.2/5)\n\n### 3. 378 Central Avenue, New Haven, CT\n*   **Price:** $581,120\n*   **Details:** 3 Bedrooms, 2 Bathrooms, 1,966 sq. ft.\n*   **Description:** A distinguished three-family residence with a garage, located in a vibrant neighborhood with easy access to culinary and cultural spots.\n*   **Nearby Schools:**\n    *   **Elementary:** Edgewood Magnet School (Rating: 3.9/5)\n    *   **Middle:** Betsy Ross Arts Magnet School (Rating: 4.1/5)\n    *   **High:** Wilbur Cross High School (Rating: 3.5/5)\n\nWould you like more details on any of these listings, or would you like to schedule a tour?"
  references {
    structured_document_info {
      document: "projects/123456/locations/global/collections/default_collection/dataStores/housing-ct-20260406/branches/0/documents/34325"
      struct_data {
        fields {
          key: "address"
          value {
            string_value: "53 EMERSON STREET"
          }
        }
        fields {
          key: "bathrooms"
          value {
            number_value: 1.5
          }
        }
        fields {
          key: "bedrooms"
          value {
            number_value: 3.0
          }
        }
        fields {
          key: "garages"
          value {
            number_value: 2.0
          }
        }
        fields {
          key: "generated_description"
          value {
            string_value: "53 Emerson Street, New Haven, CT \342\200\223 An exceptional opportunity awaits in the heart of New Haven. This elegant three-family residence offers a rare blend of classic charm and modern convenience. Spanning 1,961 square feet, this property presents a versatile layout with 3 well-appointed bedrooms and 1.5 baths, catering to a variety of living arrangements or investment strategies. A coveted amenity in urban settings, a spacious two-car garage provides secure parking and additional storage. Situated in a desirable New Haven neighborhood, this address offers easy access to the city\'s vibrant cultural scene, esteemed universities, and burgeoning culinary landscape. Anticipate a 2025 valuation of $415,061. An astute investment for the discerning buyer."
          }
        }
        fields {
          key: "location"
          value {
            struct_value {
              fields {
                key: "latitude"
                value {
                  number_value: 41.32836
                }
              }
              fields {
                key: "longitude"
                value {
                  number_value: -72.96519
                }
              }
            }
          }
        }
        fields {
          key: "price"
          value {
            number_value: 415061.0
          }
        }
        fields {
          key: "residential_type"
          value {
            string_value: "Three Family"
          }
        }
        fields {
          key: "square_footage"
          value {
            number_value: 1961.0
          }
        }
        fields {
          key: "town"
          value {
            string_value: "New Haven"
          }
        }
      }
    }
    queries: "3 bedroom house in New Haven"
  }
  references {
  ...
  }
  references {
  ...
  }
  related_questions: "Schedule a tour for 248 West Hazel Street"
  related_questions: "Are there any 3 bedroom houses in New Haven under $350k?"
  related_questions: "What are the best-rated elementary schools in New Haven?"
  related_questions: "Find 4 bedroom houses in New Haven"
}
session {
  name: "projects/123456/locations/global/collections/default_collection/engines/my-app/sessions/7813433670721451971"
  state: IN_PROGRESS
  user_pseudo_id: "user-1"
  turns {
    query {
      text: "3 bedroom house in new haven"
    }
    answer: "projects/123456/locations/global/collections/default_collection/engines/my-app/sessions/7813433670721451971/answers/7813433670721454054"
  }
  start_time {
    seconds: 1778556129
    nanos: 731866398
  }
  metadata {
    key: "google.consumer_agent_session_id"
    value: "5099640345302401024"
  }
}
answer_query_token: "NMwKDAjeuYrQBhCq9aTMAhIkNmEwMzNjNjQtMDAwMC0yZjMzLWIxYzYtZjQwMzA0M2FlYmQ0"

Python

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

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 in più passaggi.

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

Scarica la versione di anteprima dell'SDK Discovery Engine

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

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

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

Contatta l'assistenza per accedere alla cartella di Google Drive dell'SDK di anteprima.
Scarica il pacchetto per la tua lingua.

Modifiche all'API

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

Campi del corpo della richiesta

enableAgentInvocation (booleano): imposta true per passare all'elaborazione agentica con la configurazione di pubblicazione 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, nel formato projects/*/locations/*/reasoningEngines/*.

Campi di risposta

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

queries (stringa ripetuta): l'elenco delle query emesse dall'agente per produrre il riferimento.

Servizio sessioni

L'API REST del servizio Session 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 in più passaggi. Tuttavia, supporta le altre operazioni del servizio: List, Get e Delete sulle risorse di sessione utilizzate per le conversazioni in più passaggi.