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 de respuestas de transmisión puede obtener mejores resultados para ciertos casos de uso, por ejemplo, para habilitar la recuperación de varios pasos para apps con varios almacenes de datos o para personalizar la generación de respuestas para diferentes clases de preguntas.

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

Agent Search 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 agentiva.

Búsqueda combinada con y sin recuperación agentiva

La recuperación agentiva es especialmente útil para las apps de búsqueda combinada. Sin la recuperación basada en agentes, la búsqueda usa un fan-out de un solo paso que consulta todos tus almacenes de datos a la vez. En cambio, la recuperación con agentes permite la búsqueda de varios pasos. El agente planifica y ejecuta búsquedas de forma secuencial, y elige las mejores herramientas para cada paso. Puede combinar resultados de varios almacenes de datos de Agent Search y usar herramientas como la Búsqueda de Google y Google Maps.

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

• Sin recuperación basada en 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 devolver resultados fragmentados.

• Con la recuperación basada en agentes: El agente planifica la ejecución. Primero, recupera detalles sobre la oficina de Tokio de la tienda 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 agentic también te permite realizar búsquedas de varios turnos (preguntas de seguimiento) en apps de búsqueda combinada. Sin la recuperación basada en agentes, la búsqueda de varios turnos solo funciona con apps de un solo almacén de datos. Para conservar el contexto de la conversación en varios turnos, puedes vincular opcionalmente la recuperación basada en agentes con una sesión de la Plataforma de agentes.

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 los flujos de trabajo de tu empresa. El sistema usa un clasificador para determinar la intención del usuario y enruta la solicitud a la configuración del agente adecuada.

Por ejemplo, a partir de la búsqueda, determinas que la intención de la búsqueda 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 basada en agentes

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

• Agente de respuestas predefinidas de Google: Si ya tienes una app de búsqueda en Agent Search, puedes habilitar la recuperación basada en agentes configurando enable_agent_invocation=true en las solicitudes de la API cuando envíes consultas a la app. En este caso, conservarás la configuración existente de la publicación de la búsqueda.

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

Antes de comenzar

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

• Configura un motor de razonamiento para sesiones de varios turnos

• Opcional: Configura una app personalizada en modo IA

Configura un motor de razonamiento para sesiones de varios turnos

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

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

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

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 acceso al agente de servicio de Discovery Engine al motor de inferencia otorgando el rol 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 inferencia. Este permiso permite que el backend de respuestas 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: Crear, borrar o actualizar 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 las cuotas del motor de agentes de Gemini Enterprise Agent Platform.

5. Anota el nombre del recurso del entorno de ejecución del agente, ya que debes pasarlo como el campo reasoningEngine en la solicitud streamAnswer.

Opcional: Configura una app personalizada en modo de IA

De forma predeterminada, la recuperación agéntica usa el agente de respuestas de Google predefinido. Esta función clasifica las búsquedas en intenciones DEFAULT_ANSWER_SEEKING y DO_NOT_ANSWER. Puedes crear una app personalizada en modo de IA cuando quieras personalizar herramientas o agregar compatibilidad con nuevas clases de intents de búsqueda. Cada intent personalizado (o marco) declara las condiciones en las que el agente clasifica una búsqueda en el intent y las instrucciones y herramientas que el agente usa para controlarla.

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

   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 publicación 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 con el modo de IA, comunícate con el equipo de asistencia.

Transmite una respuesta con la recuperación basada en agentes

En el siguiente comando, se muestra cómo llamar al método streaming answer con la recuperación basada en agentes habilitada. Al igual que el resultado sin recuperación agente, 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 diferentes 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 los servicios de Google Clouddesde 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.

Dado que la función de recuperación con agentes está en una lista de entidades permitidas, el SDK con el que debes trabajar para usar 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 acceder a la carpeta de Google Drive de la versión preliminar del SDK.

2. Descarga el paquete para tu idioma.

Cambios en la API

Debido a que esta función se encuentra 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 son necesarios para usar la recuperación basada en 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): Establece 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 publicación answer_agent con una app en modo de IA personalizada.

• reasoningEngine (cadena): Es el nombre del recurso del entorno de ejecución del agente que aloja las sesiones del agente, con el formato projects/*/locations/*/reasoningEngines/*.

Campos de respuesta

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

• queries (cadena repetida): Es la lista de preguntas que hizo el agente para producir la referencia.

Servicio de sesiones

La API de REST del servicio de sesión 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 varios turnos. Sin embargo, sí admite el otro servicio: operaciones List, Get y Delete en recursos de sesión que se usan para conversaciones de varios turnos.