Inspecciona y llama a un agente de datos

En este documento, se describe cómo inspeccionar un agente y actualizar su archivo de contexto. Puedes inspeccionar un agente para probar su capacidad de generar consultas en SQL a partir de preguntas en lenguaje natural. Si una búsqueda generada no es precisa, puedes actualizar el contexto del agente.

Para obtener más información sobre los agentes de datos, consulta Descripción general de los agentes de datos.

Antes de comenzar

Asegúrate de que ya se haya creado un agente de datos y de que se haya subido el contexto del agente al agente de datos. Para obtener más información, consulta Administra agentes de datos en Spanner Studio.

Inspecciona un agente de datos

Para inspeccionar un agente de datos, sigue estos pasos:

  1. En la consola de Google Cloud , ve a la página de Spanner.

    Ir a Spanner

  2. Selecciona una instancia de la lista y, luego, selecciona una base de datos.

  3. En el menú de navegación, haz clic en Spanner Studio.

  4. En el panel Explorador, junto a Agentes de datos, haz clic en Ver acciones.

  5. Haz clic en Inspect agent.

  6. En el editor de consultas, haz clic en Generar SQL para abrir el panel Ayúdame a escribir código.

  7. Ingresa una pregunta en lenguaje natural para generar una consulta en SQL y haz clic en Generar.

  8. Revisa la precisión de la consulta en SQL.

Descarga y actualiza el contexto de un agente de datos

Si no te satisface la consulta en SQL generada para una pregunta en lenguaje natural, descarga el archivo de contexto del agente existente. Luego, puedes revisar y actualizar la plantilla de consulta, y volver a subir el archivo de contexto actualizado al agente.

Para descargar y actualizar el contexto de un agente de datos, sigue estos pasos:

  1. En el panel Explorador, junto a Agentes de datos, haz clic en Ver acciones.
  2. Haz clic en Descargar archivo de contexto del agente.
  3. Sigue los pasos que se indican en Cómo compilar contextos con Gemini CLI para actualizar el contexto con pares de preguntas adicionales.
  4. En el panel Explorador, junto a tu agente de datos, haz clic en Ver acciones.
  5. Haz clic en Editar agente.
  6. Haz clic en Examinar en la sección Subir archivo de contexto del agente y selecciona el archivo de contexto del agente actualizado.
  7. Haz clic en Guardar para actualizar el contexto del agente.

Cuando estés conforme con la precisión de tus respuestas, puedes usar el extremo QueryData para conectar tu aplicación al agente de datos.

Cómo encontrar el ID de contexto del agente

Para conectar una aplicación de datos al agente de datos, necesitas el ID de contexto del agente.

  1. En la consola de Google Cloud , ve a la página de Spanner.

    Ir a Spanner

  2. Selecciona una instancia de la lista y, luego, selecciona una base de datos.

  3. En el menú de navegación, haz clic en Spanner Studio.

  4. En el panel Explorador, junto a Agentes de datos, haz clic en Ver acciones.

  5. Haz clic en Editar agente.

  6. Anota el ID de contexto en Agent context ID. El formato del ID de contexto del agente es similar a projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_pg_all_templates.

Conecta el agente de datos a la aplicación

Establece el ID de contexto del agente en la llamada de método QueryData para proporcionar contexto creado para las fuentes de datos de bases de datos, como AlloyDB, Spanner, Cloud SQL y Cloud SQL para PostgreSQL. Para obtener más información, consulta Cómo definir el contexto del agente de datos para las fuentes de datos de bases de datos.

Después de inspeccionar el agente de datos, puedes hacer referencia a la fuente de datos de la base de datos en tu llamada a QueryData.

Ejemplo de solicitud de QueryData con contexto creado

En el siguiente ejemplo, se muestra una solicitud QueryData que usa la fuente de datos de la base de datos spanner_reference. El campo agent_context_reference.context_set_id se usa para vincularse al contexto previamente creado y almacenado en la base de datos.

{
  "parent": "projects/cloud-db-nl2sql/locations/us-central1",
  "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.",
  "context": {
    "datasource_references": [
      {
        "spanner_reference" {
          "database_reference" {
            "engine": "GOOGLE_SQL"
            "project_id": "cloud-db-nl2sql"
            "region": "us-central1"
            "instance_id": "evalbench"
            "database_id": "financial"
          },
          "agent_context_reference": {
            "context_set_id": "projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_pg_all_templates"
          }
        }
      }
    ]
  },
  "generation_options": {
    "generate_query_result": true,
    "generate_natural_language_answer": true,
    "generate_disambiguation_question": true,
    "generate_explanation": true
  }
}

El cuerpo de la solicitud contiene los siguientes campos:

  • prompt: Es la pregunta en lenguaje natural del usuario final.
  • context: Contiene información sobre las fuentes de datos.
    • datasource_references: Especifica el tipo de fuente de datos.
      • spanner_reference: Se requiere cuando se consulta la base de datos. Este campo cambia según la base de datos que consultes.
        • database_reference: Especifica información relacionada con tu instancia de base de datos.
          • engine: Es el dialecto de SQL de la base de datos. Se establece en GOOGLE_SQL para las bases de datos de Spanner.
          • project_id: Es el ID del proyecto de la instancia de la base de datos.
          • region: Es la región de la instancia de Spanner.
          • instance_id: Es el ID de la instancia de Spanner.
          • database_id: Es el ID de la base de datos.
        • agent_context_reference: Vínculos al contexto creado en la base de datos.
          • context_set_id: Es el ID completo del contexto del agente almacenado en la base de datos. Por ejemplo, projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_gsql_gemini_all_templates
  • generationOptions: Configura el tipo de salida que se generará.
    • generate_query_result: Se establece en verdadero para generar y devolver los resultados de la búsqueda.
    • generate_natural_language_answer: Opcional Si se establece como verdadero, se genera una respuesta en lenguaje natural.
    • generate_explanation: Opcional Si se establece en verdadero, genera una explicación de la consulta en SQL.
    • generate_disambiguation_question: Opcional Si se establece como verdadero, genera preguntas de desambiguación si la búsqueda es ambigua.

Ejemplo de respuesta de QueryData

Este es un ejemplo de una respuesta correcta de una llamada QueryData:

{
  "generated_query": "-- Count the number of accounts in Prague that are eligible for loans\nSELECT\n  COUNT(DISTINCT \"loans\".\"account_id\")\nFROM \"loans\"\nJOIN \"district\" -- Join based on district ID\n  ON \"loans\".\"district_id\" = \"district\".\"district_id\"\nWHERE\n  \"district\".\"A3\" = 'Prague'; -- Filter for the Prague region",
  "intent_explanation": "The question asks for the number of accounts eligible for loans in the Prague region. I need to join the `district` table with the `loans` table to filter by region and count the distinct accounts. The `A3` column in the `district` table contains the region information, and I'll filter for 'Prague'. The `loans` table contains information about loans, including the `account_id` and `district_id`. I will join these two tables on their respective district IDs.",
  "query_result": {
    "columns": [
      {
        "name": "count"
      }
    ],
    "rows": [
      {
        "values": [
          {
            "value": "2"
          }
        ]
      }
    ],
    "total_row_count": 1
  },
  "natural_language_answer": "There are 2 accounts in Prague that are eligible for loans."
}

¿Qué sigue?