Inspeccionar y llamar 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 SQL a partir de preguntas en lenguaje natural. Si una consulta generada no es precisa, puedes actualizar el contexto del agente.

Para obtener información sobre los agentes de datos, consulta el artículo Descripción general de los agentes de datos.

Antes de empezar

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 Gestionar agentes de datos en Spanner Studio.

Inspeccionar un agente de datos

Para inspeccionar un agente de datos, sigue estos pasos:

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

    Ir a Spanner

  2. Selecciona una instancia de la lista y, a continuación, 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, haga clic en Ver acciones.

  5. Haz clic en Inspeccionar agente.

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

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

  8. Revisa la consulta de SQL para comprobar que es correcta.

Descargar y actualizar el contexto de un agente de datos

Si no estás satisfecho con la consulta SQL generada para una pregunta en lenguaje natural, descarga el archivo de contexto del agente. A continuación, 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, haga clic en Ver acciones.
  2. Haz clic en Descargar archivo de contexto del agente.
  3. Sigue los pasos que se indican en Crear contextos con la CLI de Gemini para actualizar el contexto con pares de consultas adicionales.
  4. En el panel Explorador, junto a su agente de datos, haga clic en Ver acciones.
  5. Haz clic en Editar agente.
  6. En la sección Subir archivo de contexto del agente, haz clic en Examinar y selecciona el archivo de contexto del agente actualizado.
  7. Haz clic en Guardar para actualizar el contexto del agente.

Cuando esté satisfecho con la precisión de sus respuestas, puede usar el endpoint QueryData para conectar su aplicación al agente de datos.

Buscar el ID de contexto del agente

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

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

    Ir a Spanner

  2. Selecciona una instancia de la lista y, a continuación, 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, haga clic en Ver acciones.

  5. Haz clic en Editar agente.

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

Conectar el agente de datos a la aplicación

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

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

Ejemplo de solicitud QueryData con contexto creado

En el siguiente ejemplo se muestra una solicitud QueryData que utiliza una fuente de datos de la base de datos spanner_reference. El campo agent_context_reference.context_set_id se usa para vincular a un contexto predefinido 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: 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: es obligatorio al consultar la base de datos. Este campo cambia en función de la base de datos que estés consultando.
        • database_reference: especifica información relacionada con tu instancia de base de datos.
          • engine: el dialecto SQL de la base de datos. Defina el valor GOOGLE_SQL para las bases de datos de Spanner.
          • project_id: el ID de proyecto de la instancia de la base de datos.
          • region: la región de la instancia de Spanner.
          • instance_id: el ID de instancia de la instancia de Spanner.
          • database_id: ID de la base de datos.
        • agent_context_reference: enlaces al contexto creado en la base de datos.
          • context_set_id: ID de contexto completo del contexto 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 va a generar.
    • generate_query_result: se define como true para generar y devolver los resultados de la consulta.
    • generate_natural_language_answer: opcional. Si se le asigna el valor "true", genera una respuesta en lenguaje natural.
    • generate_explanation: opcional. Si se le asigna el valor true, genera una explicación de la consulta de SQL.
    • generate_disambiguation_question: opcional. Si se le asigna el valor "true", genera preguntas para aclarar la información si la consulta es ambigua.

Ejemplo de respuesta QueryData

A continuación, se muestra un ejemplo de respuesta correcta de una llamada a 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."
}

Siguientes pasos