Transmite respuestas con la recuperación basada en agentes

En esta página, se presenta la recuperación con agentes y se explica cómo usarla con el método stream answers.

Acerca de la recuperación con agentes

La recuperación con agentes que se usa con el método stream answers puede obtener mejores resultados para ciertos casos de uso, por ejemplo, para habilitar la recuperación de varias pasadas para apps con varios almacenes de datos o para personalizar la generación de respuestas para diferentes clases de consultas.

El uso de la recuperación con agentes agrega cierta complejidad a tus apps, pero, a cambio, ofrece más control sobre los resultados.

La Búsqueda con agentes incluye un agente predefinido que puedes usar para personalizar el comportamiento de un motor de búsqueda. Esto permite una mayor personalización que la que está disponible a través de la IU de configuraciones de la app o el método de respuesta de transmisión sin recuperación con agentes.

Búsqueda combinada con y sin recuperación con agentes

La recuperación con agentes es particularmente útil para las apps de búsqueda combinada. Sin la recuperación con agentes, la búsqueda usa un fan-out de una sola pasada que consulta todos tus almacenes de datos a la vez. Por el contrario, la recuperación con agentes permite la búsqueda de varias pasadas. El agente planifica y ejecuta las búsquedas de forma secuencial, y elige las mejores herramientas para cada paso. También puede combinar resultados de varios almacenes de datos de la Búsqueda con agentes y usar herramientas como la Búsqueda de Google y Google Maps.

Por ejemplo, tienes almacenes de datos separados para las políticas globales de la empresa y los detalles de las oficinas regionales. Un usuario pregunta: "¿Cuáles son las reglas de cumplimiento de nuestra oficina de Tokio?".

  • Sin recuperación con agentes: Consulta el almacén de políticas y el almacén de la oficina regional de forma simultánea con la cadena de consulta completa. Esto podría mostrar resultados fragmentados.

  • Con recuperación con agentes: El agente planifica la ejecución. Primero, recupera los detalles sobre la oficina de Tokio del almacén regional. Luego, con ese contexto específico, realiza una segunda búsqueda segmentada en el almacén de políticas.

    El agente sintetiza estos hallazgos en una respuesta única, coherente y más precisa.

La recuperación con agentes también te permite realizar consultas de búsqueda de varias turnos (preguntas de seguimiento) en apps de búsqueda combinada. Sin la recuperación con agentes, la búsqueda de varias turnos solo funciona con apps de un solo almacén de datos. Para conservar el contexto de la conversación en varios turnos, puedes combinar la recuperación con agentes con una sesión de Agent Platform.

Clasificación de consultas personalizadas

Los métodos answer y streaming answer proporcionan dos tipos de clasificación de consultas: ADVERSARIAL_QUERY y NON_ANSWER_SEEKING_QUERY.

La recuperación con agentes te permite definir tipos de clasificación adicionales para que coincidan con tus flujos de trabajo empresariales. El sistema usa un clasificador para determinar la intención del usuario y enruta la solicitud a la configuración de agente adecuada.

Por ejemplo, a partir de la consulta, determinas que la intención de la consulta es hacer un seguimiento de un pedido y especificaste una clasificación TRACK_ORDER. En lugar de ejecutar una búsqueda genérica en todos tus almacenes de datos, el sistema carga un agente especializado equipado con las herramientas y los datos necesarios para recuperar el estado del envío.

Formas de habilitar y usar la recuperación con agentes

Existen dos formas de habilitar la recuperación con agentes:

  • Agente de respuesta predefinido de Google: Si ya tienes una app de búsqueda en la Búsqueda con agentes, puedes habilitar la recuperación con agentes configurando enable_agent_invocation=true en las solicitudes a la API cuando envías consultas a la app. En este caso, conservas la configuración de entrega de búsqueda existente.

  • App personalizada en modo IA: Cuando creas una app de la Búsqueda con agentes, defines un tipo diferente de configuración de entrega, la configuración de entrega default_agent_answer. También se puede hacer referencia a esto como el motor personalizado en modo IA, ya que "app" y "motor" se usan de forma indistinta en la Búsqueda con agentes.

Antes de comenzar

Antes de poder usar la recuperación con agentes, haz lo siguiente:

Configura un motor de razonamiento para sesiones de varias turnos

Para conservar el contexto de la conversación en varios turnos, debes crear un Agent Runtime en el motor de Gemini Enterprise Agent Platform (también llamado motor de razonamiento).

Cuando realizas una solicitud streamAnswer, pasas el nombre del recurso del Agent Runtime como el campo reasoningEngine en la solicitud streamAnswer.

  1. Habilita el Agent Platform en tu Google Cloud proyecto.

  2. Crea una instancia de Agent Runtime (también llamada motor de razonamiento) con la API de REST de Agent Engine (o el Kit de desarrollo de agentes). La instancia aloja las sesiones que usa el método streamAnswer.

    El nombre del recurso de la instancia tiene el siguiente formato:

    projects/PROJECT_NUMBER/locations/LOCATION_ID/reasoningEngines/REASONING_ENGINE_ID

  3. Otorga al agente de servicio de Discovery Engine acceso al motor de razonamiento otorgando la función roles/aiplatform.reasoningEngineServiceAgent a la cuenta de servicio de Discovery Engine:

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

    donde PROJECT_NUMBER es el número del proyecto que aloja el motor de razonamiento. Este permiso permite que el backend de respuesta de transmisión cree, lea y agregue eventos a las sesiones en tu nombre.

  4. Revisa las cuotas aplicables. Las sesiones respaldadas por Agent Runtime consumen cuotas de la API de Agent Platform. Las cuotas de interés son las siguientes:

    • aiplatform.googleapis.com/session_write_requests : Crea, borra o actualiza sesiones de Agent Runtime por minuto.

    • aiplatform.googleapis.com/session_event_append_requests : Agrega eventos a las sesiones de Agent Runtime por minuto.

    Para obtener más información, consulta Cuotas de Agent Engine de Gemini Enterprise Agent Platform.

  5. Toma nota del nombre del recurso de Agent Runtime, ya que debes pasarlo como el campo reasoningEngine en la solicitud streamAnswer.

Opcional: Configura una app personalizada en modo IA

De forma predeterminada, la recuperación con agentes usa el agente de respuesta predefinido de Google. Esto clasifica las consultas en las intenciones DEFAULT_ANSWER_SEEKING y DO_NOT_ANSWER. Puedes crear una app personalizada en modo IA cuando quieras personalizar herramientas o agregar compatibilidad con nuevas clases de intenciones de consulta. Cada intención personalizada (o marco) declara las condiciones en las que el agente clasifica una consulta en la intención y las instrucciones y herramientas que usa el agente para controlarla.

  1. Crea el motor a través del engines.create método REST con un engine_config.answer_agent bloque.

    La configuración se estructura de la siguiente manera:

    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. Después de crear el motor, enruta las solicitudes a través de su configuración de entrega default_agent_answer:

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

  3. Si necesitas ayuda para diseñar o registrar una app personalizada en modo IA, comunícate con el equipo de asistencia support.

Transmite una respuesta con la recuperación con agentes

En el siguiente comando, se muestra cómo llamar al método de respuesta de transmisión con agentes habilitada. Al igual que la salida sin recuperación con agentes, esta llamada transmite una respuesta generada en forma de una serie de respuestas JSON.

Si configuraste un motor de razonamiento, incluye su nombre de recurso en el campo reasoningEngine para conservar la sesión en los turnos.

REST

Para buscar y obtener resultados con una respuesta generada transmitida, haz lo siguiente:

  1. Ejecuta el siguiente comando de 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"
      }'

    Reemplaza lo siguiente:

    • PROJECT_ID: el ID de tu Google Cloud proyecto.
    • APP_ID: el ID de la app de la Búsqueda con agentes que deseas consultar.
    • SERVING_CONFIG_ID: Para usar una app personalizada en modo IA, configura este parámetro en default_agent_answer. Para usar el agente de respuesta predefinido de Google, configura este parámetro en default_search.
    • PROJECT_NUMBER: el número del proyecto que aloja el motor de razonamiento.
    • QUERY: una cadena de texto libre que contiene la pregunta o la consulta de búsqueda.
    • SESSION: Si continúas una conversación de varias turnos, este es el nombre del recurso de la sesión que se muestra en la respuesta del turno anterior, por ejemplo, projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/sessions/SESSION_ID. Si no continúas una conversación, configura este parámetro en - (un guion).
    • USER_PSEUDO_ID: un identificador único que se usa para hacer un seguimiento del visitante.
    • LOCATION_ID: la ubicación de tu motor de razonamiento, por ejemplo us-central1.
    • REASONING_ENGINE_ID: el ID de la instancia de Agent Engine que creaste.

Python

Para obtener más información, consulta la documentación de referencia de la API de la PythonBúsqueda con agentes.

Para autenticarte en la Búsqueda con agentes, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

En la siguiente muestra, se usa el cliente de Python de Discovery Engine (v1alpha) para llamar a stream_answer_query con la invocación de agentes habilitada. Pasa el campo reasoning_engine para las sesiones de varias turnos.

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

Obtén la versión preliminar del SDK de Discovery Engine

El SDK de Discovery Engine facilita la interacción con Google Cloud los servicios desde tus aplicaciones. El SDK ayuda con el manejo de errores y la autenticación, y proporciona funciones como reintentos automáticos, manejo de paginación y administración de operaciones de larga duración.

Debido a que la función de recuperación con agentes está en una lista de entidades permitidas, el SDK que necesitas para trabajar con esta función es diferente de las bibliotecas cliente de Discovery Engine disponibles de forma general.

Para obtener la versión preliminar del SDK de Discovery Engine, haz lo siguiente:

  1. Comunícate con el equipo de asistencia para obtener acceso a la carpeta de Google Drive del SDK de versión preliminar.

  2. Descarga el paquete para tu idioma.

Cambios en la API

Debido a que esta función está en una lista de entidades permitidas, la documentación de referencia de la API en la página del método de respuesta de transmisión no muestra todos los campos que están disponibles y que se necesitan para usar la recuperación con agentes con el método de respuesta de transmisión. Los campos faltantes se documentan de la siguiente manera.

Campos del cuerpo de la solicitud

  • enableAgentInvocation (booleano): Configura true para cambiar al procesamiento con agentes con la configuración de entrega de búsqueda existente. Este campo es opcional si especificas una configuración de entrega answer_agent con una app personalizada en modo IA.

  • reasoningEngine (cadena): El nombre del recurso de Agent Runtime que aloja las sesiones de agentes, con el formato projects/*/locations/*/reasoningEngines/*.

Campos de respuesta

Cuando se habilita la recuperación con agentes, cada generada Answer.Reference incluye lo siguiente:

  • queries (cadena repetida): La lista de consultas que emitió el agente para producir la referencia.

Servicio de sesiones

La API de REST del servicio de sesiones no admite los métodos create ni update. Sin embargo, admite los otros métodos: list, get y delete.

La API de RPC del servicio de sesiones no admite las operaciones Update ni Create en los recursos de sesión que se usan para conversaciones de varias turnos. Sin embargo, admite el otro servicio: operaciones List, Get y Delete en los recursos de sesión que se usan para conversaciones de varias turnos.