Uso de la API de agentes de Genie

Integre Genie Agents en su propio bot de chat, agente o aplicación con Genie Agents API. La API proporciona APIs en modo Chat para consultas de datos en lenguaje natural con estado (con preguntas de seguimiento e historial) y APIs de Gestión para flujos de trabajo CI/CD que crean, configuran y despliegan Agentes Genie en los espacios de trabajo.

Visión general

La API de Genie ofrece los siguientes tipos de capacidades:

• APIs del modo chat: Habilitar la consulta de datos en lenguaje natural en aplicaciones, chatbots y frameworks de agentes. Estas APIs soportan conversaciones con estado creadas en modo Chat, donde los usuarios pueden hacer preguntas de seguimiento y explorar datos de forma natural a lo largo del tiempo.
• API del modo Agente: Permiten a los desarrolladores enviar indicaciones mediante programación en el modo Agente, transmitir en streaming el razonamiento y los resultados de SQL, y recibir informes finales con referencias.
• API de administración: habilite la creación, la configuración y la implementación de Genie Agents entre áreas de trabajo. Use estas API para canalizaciones de CI/CD, control de versiones y administración automatizada de agentes.

Esta página explica cómo preparar un Agente Genie bien seleccionado y gestionar agentes entre espacios de trabajo para que la API devuelva resultados fiables. El agente proporciona el contexto que usa Genie para interpretar preguntas y generar respuestas. Si el agente está incompleto o no probado, es posible que los usuarios sigan recibiendo resultados incorrectos incluso con una integración de API correcta. Para los endpoints de ejecución, los formatos de solicitud y de respuesta, consulte la referencia de la API de REST enlazada en referencia de la API de Genie.

Los ejemplos de configuración en esta página usan directamente la API REST. También puede llamar a estas API mediante los SDK de Azure Databricks. Consulte SDK de Databricks.

Requisitos previos

Para usar la API de Genie, debe tener:

• Acceso a un espacio de trabajo de Azure Databricks con los permisos de Databricks SQL.
• Necesita al menos privilegios para usar en SQL Pro o en un almacén de SQL sin servidor.

Cómo empezar

Configuración de la autenticación de Azure Databricks

Para casos de uso de producción en los que esté presente un usuario con acceso a un navegador, use OAuth para usuarios (OAuth U2M). En situaciones en las que no es posible la autenticación basada en explorador, use una entidad de servicio para autenticarse con la API. Consulte OAuth para entidades de servicio (OAuth M2M). Las entidades de servicio deben tener permisos para acceder a los datos necesarios y a los almacenes de datos SQL.

Recopilación de detalles

• Nombre de la instancia del área de trabajo: Busque y copie el nombre de la instancia de su área de trabajo desde la URL del área de trabajo de Databricks. Para más información sobre los identificadores del área de trabajo en la dirección URL, consulte Obtención de identificadores para objetos del área de trabajo.

  Ejemplo: https://cust-success.cloud.databricks.com/

• ID del almacén: necesita el identificador de un almacén SQL para el que tenga al menos privilegios de USO. Para encontrar el identificador de tu almacén:

  1. Vaya a SQL Warehouses en el área de trabajo.
  2. Seleccione el almacén que desea usar.
  3. Copie el identificador de almacenamiento desde la dirección URL o la página de detalles del almacenamiento.

  Como alternativa, use el endpoint List warehousesGET /api/2.0/sql/warehouses para recuperar programáticamente una lista de todos los almacenes SQL a los que tiene permisos de acceso. La respuesta incluye el ID de almacén.

Crear o seleccionar un agente de Genie

Un agente de Genie bien estructurado tiene las siguientes características:

• Usa datos anotados correctamente: Genie se basa en los metadatos de la tabla y los comentarios de columna. Compruebe que los orígenes de datos del Catálogo de Unity tengan comentarios claros y descriptivos.
• ¿Se ha probado el usuario? Para probar el agente, haga preguntas que espere de los usuarios finales. Use pruebas para crear y refinar consultas SQL de ejemplo.
• Incluye contexto específico de la empresa: agregue instrucciones, por ejemplo, SQL y funciones. Consulte Adición de ejemplos e instrucciones de SQL. Apunte a al menos cinco consultas SQL de ejemplo probadas.
• Usa pruebas comparativas para probar la precisión: agregue al menos cinco preguntas comparativas basadas en preguntas de usuario previstas. Consulte Pruebas comparativas.

Para obtener más información sobre cómo crear un agente, vea Crear y administrar un agente de Genie y Curar un agente de Genie eficaz.

Puede crear un agente de Genie o usar uno existente:

Creación de un agente

Cree un agente de Genie mediante programación mediante la API Crear agente de Genie. En el ejemplo siguiente se muestra un agente bien estructurado que sigue los procedimientos recomendados. Reemplace los marcadores de posición por valores propios:

POST /api/2.0/genie/spaces
Host: <DATABRICKS_INSTANCE>
Authorization: Bearer <your_authentication_token>
{
  "description": "Space for analyzing sales performance and trends",
  "parent_path": "/Workspace/Users/<username>",
  "serialized_space": "{\"version\":1,\"config\":{\"sample_questions\":[{\"id\":\"a1b2c3d4e5f6\",\"question\":[\"What were total sales last month?\"]},{\"id\":\"b2c3d4e5f6g7\",\"question\":[\"Show top 10 customers by revenue\"]},{\"id\":\"c3d4e5f6g7h8\",\"question\":[\"Compare sales by region for Q1 vs Q2\"]}]},\"data_sources\":{\"tables\":[{\"identifier\":\"sales.analytics.orders\",\"description\":[\"Transactional order data including order date, amount, and customer information\"],\"column_configs\":[{\"column_name\":\"order_date\",\"get_example_values\":true},{\"column_name\":\"status\",\"get_example_values\":true,\"build_value_dictionary\":true},{\"column_name\":\"region\",\"get_example_values\":true,\"build_value_dictionary\":true}]},{\"identifier\":\"sales.analytics.customers\"},{\"identifier\":\"sales.analytics.products\"}]},\"instructions\":{\"text_instructions\":[{\"id\":\"01f0b37c378e1c91\",\"content\":[\"When calculating revenue, sum the order_amount column. When asked about 'last month', use the previous calendar month (not the last 30 days). Round all monetary values to 2 decimal places.\"]}],\"example_question_sqls\":[{\"id\":\"01f0821116d912db\",\"question\":[\"Show top 10 customers by revenue\"],\"sql\":[\"SELECT customer_name, SUM(order_amount) as total_revenue\\n\",\"FROM sales.analytics.orders o\\n\",\"JOIN sales.analytics.customers c ON o.customer_id = c.customer_id\\n\",\"GROUP BY customer_name\\n\",\"ORDER BY total_revenue DESC\\n\",\"LIMIT 10\"]},{\"id\":\"01f099751a3a1df3\",\"question\":[\"What were total sales last month\"],\"sql\":[\"SELECT SUM(order_amount) as total_sales\\n\",\"FROM sales.analytics.orders\\n\",\"WHERE order_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL 1 MONTH)\\n\",\"AND order_date < DATE_TRUNC('month', CURRENT_DATE)\"]}],\"join_specs\":[{\"id\":\"01f0c0b4e8151\",\"left\":{\"identifier\":\"sales.analytics.orders\",\"alias\":\"orders\"},\"right\":{\"identifier\":\"sales.analytics.customers\",\"alias\":\"customers\"},\"sql\":[\"orders.customer_id = customers.customer_id\"]}],\"sql_snippets\":{\"filters\":[{\"id\":\"01f09972e66d1\",\"sql\":[\"orders.order_amount > 1000\"],\"display_name\":\"high value orders\",\"synonyms\":[\"large orders\",\"big purchases\"]}],\"expressions\":[{\"id\":\"01f09974563a1\",\"alias\":\"order_year\",\"sql\":[\"YEAR(orders.order_date)\"],\"display_name\":\"year\"}],\"measures\":[{\"id\":\"01f09972611f1\",\"alias\":\"total_revenue\",\"sql\":[\"SUM(orders.order_amount)\"],\"display_name\":\"total revenue\",\"synonyms\":[\"revenue\",\"total sales\"]}]}}}",
  "title": "Sales Analytics Space",
  "warehouse_id": "<warehouse-id>"
}

Response:
{
  "space_id": "3c409c00b54a44c79f79da06b82460e2",
  "title": "Sales Analytics Space",
  "description": "Space for analyzing sales performance and trends",
  "warehouse_id": "<warehouse-id>",
  "serialized_space": "{\n  \"version\": 1,\n  \"config\": {\n    \"sample_questions\": [\n      {\n        \"id\": \"a1b2c3d4e5f600000000000000000000\",\n        \"question\": [\n          \"What were total sales last month?\"\n        ]\n      },\n      {\n        \"id\": \"b2c3d4e5f6g700000000000000000000\",\n        \"question\": [\n          \"Show top 10 customers by revenue\"\n        ]\n      },\n      {\n        \"id\": \"c3d4e5f6g7h800000000000000000000\",\n        \"question\": [\n          \"Compare sales by region for Q1 vs Q2\"\n        ]\n      }\n    ]\n  },\n  \"data_sources\": {\n    \"tables\": [\n      {\n        \"identifier\": \"sales.analytics.orders\",\n        \"description\": [\n          \"Transactional order data including order date, amount, and customer information\"\n        ],\n        \"column_configs\": [\n          {\n            \"column_name\": \"order_date\",\n            \"get_example_values\": true\n          },\n          {\n            \"column_name\": \"status\",\n            \"get_example_values\": true,\n            \"build_value_dictionary\": true\n          },\n          {\n            \"column_name\": \"region\",\n            \"get_example_values\": true,\n            \"build_value_dictionary\": true\n          }\n        ]\n      },\n      {\n        \"identifier\": \"sales.analytics.customers\"\n      },\n      {\n        \"identifier\": \"sales.analytics.products\"\n      }\n    ]\n  },\n  \"instructions\": {\n    \"text_instructions\": [\n      {\n        \"id\": \"01f0b37c378e1c91\",\n        \"content\": [\n          \"When calculating revenue, sum the order_amount column. When asked about 'last month', use the previous calendar month (not the last 30 days). Round all monetary values to 2 decimal places.\"\n        ]\n      }\n    ],\n    \"example_question_sqls\": [\n      {\n        \"id\": \"01f0821116d912db\",\n        \"question\": [\n          \"Show top 10 customers by revenue\"\n        ],\n        \"sql\": [\n          \"SELECT customer_name, SUM(order_amount) as total_revenue\\n\",\n          \"FROM sales.analytics.orders o\\n\",\n          \"JOIN sales.analytics.customers c ON o.customer_id = c.customer_id\\n\",\n          \"GROUP BY customer_name\\n\",\n          \"ORDER BY total_revenue DESC\\n\",\n          \"LIMIT 10\"\n        ]\n      },\n      {\n        \"id\": \"01f099751a3a1df3\",\n        \"question\": [\n          \"What were total sales last month\"\n        ],\n        \"sql\": [\n          \"SELECT SUM(order_amount) as total_sales\\n\",\n          \"FROM sales.analytics.orders\\n\",\n          \"WHERE order_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL 1 MONTH)\\n\",\n          \"AND order_date < DATE_TRUNC('month', CURRENT_DATE)\"\n        ]\n      }\n    ],\n    \"join_specs\": [\n      {\n        \"id\": \"01f0c0b4e8151\",\n        \"left\": {\n          \"identifier\": \"sales.analytics.orders\",\n          \"alias\": \"orders\"\n        },\n        \"right\": {\n          \"identifier\": \"sales.analytics.customers\",\n          \"alias\": \"customers\"\n        },\n        \"sql\": [\n          \"orders.customer_id = customers.customer_id\"\n        ]\n      }\n    ],\n    \"sql_snippets\": {\n      \"filters\": [\n        {\n          \"id\": \"01f09972e66d1\",\n          \"sql\": [\"orders.order_amount > 1000\"],\n          \"display_name\": \"high value orders\",\n          \"synonyms\": [\"large orders\", \"big purchases\"]\n        }\n      ],\n      \"expressions\": [\n        {\n          \"id\": \"01f09974563a1\",\n          \"alias\": \"order_year\",\n          \"sql\": [\"YEAR(orders.order_date)\"],\n          \"display_name\": \"year\"\n        }\n      ],\n      \"measures\": [\n        {\n          \"id\": \"01f09972611f1\",\n          \"alias\": \"total_revenue\",\n          \"sql\": [\"SUM(orders.order_amount)\"],\n          \"display_name\": \"total revenue\",\n          \"synonyms\": [\"revenue\", \"total sales\"]\n        }\n      ]\n    }\n  }\n}\n"
}

Uso de un agente existente

Si ya dispone de un agente de Genie, puede encontrar el ID del espacio mediante la API de listado de agentes de Genie. También puede encontrar y copiar el identificador de espacio en la pestaña Configuración del agente de Genie.

GET /api/2.0/genie/spaces
Host: <DATABRICKS_INSTANCE>
Authorization: Bearer <your_authentication_token>

Response:
{
  "spaces": [
    {
      "description": "Space for analyzing sales performance and trends",
      "serialized_space": "{\"version\":1,\"config\":{\"sample_questions\":[{\"id\":\"a1b2c3d4e5f6\",\"question\":[\"What were total sales last month?\"]},{\"id\":\"b2c3d4e5f6g7\",\"question\":[\"Show top 10 customers by revenue\"]},{\"id\":\"c3d4e5f6g7h8\",\"question\":[\"Compare sales by region for Q1 vs Q2\"]}]},\"data_sources\":{\"tables\":[{\"identifier\":\"sales.analytics.orders\",\"description\":[\"Transactional order data including order date, amount, and customer information\"],\"column_configs\":[{\"column_name\":\"order_date\",\"get_example_values\":true},{\"column_name\":\"status\",\"get_example_values\":true,\"build_value_dictionary\":true},{\"column_name\":\"region\",\"get_example_values\":true,\"build_value_dictionary\":true}]},{\"identifier\":\"sales.analytics.customers\"},{\"identifier\":\"sales.analytics.products\"}]},\"instructions\":{\"text_instructions\":[{\"id\":\"01f0b37c378e1c91\",\"content\":[\"When calculating revenue, sum the order_amount column. When asked about 'last month', use the previous calendar month (not the last 30 days). Round all monetary values to 2 decimal places.\"]}],\"example_question_sqls\":[{\"id\":\"01f0821116d912db\",\"question\":[\"Show top 10 customers by revenue\"],\"sql\":[\"SELECT customer_name, SUM(order_amount) as total_revenue\\n\",\"FROM sales.analytics.orders o\\n\",\"JOIN sales.analytics.customers c ON o.customer_id = c.customer_id\\n\",\"GROUP BY customer_name\\n\",\"ORDER BY total_revenue DESC\\n\",\"LIMIT 10\"]},{\"id\":\"01f099751a3a1df3\",\"question\":[\"What were total sales last month\"],\"sql\":[\"SELECT SUM(order_amount) as total_sales\\n\",\"FROM sales.analytics.orders\\n\",\"WHERE order_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL 1 MONTH)\\n\",\"AND order_date < DATE_TRUNC('month', CURRENT_DATE)\"]}],\"join_specs\":[{\"id\":\"01f0c0b4e8151\",\"left\":{\"identifier\":\"sales.analytics.orders\",\"alias\":\"orders\"},\"right\":{\"identifier\":\"sales.analytics.customers\",\"alias\":\"customers\"},\"sql\":[\"orders.customer_id = customers.customer_id\"]}],\"sql_snippets\":{\"filters\":[{\"id\":\"01f09972e66d1\",\"sql\":[\"orders.order_amount > 1000\"],\"display_name\":\"high value orders\",\"synonyms\":[\"large orders\",\"big purchases\"]}],\"expressions\":[{\"id\":\"01f09974563a1\",\"alias\":\"order_year\",\"sql\":[\"YEAR(orders.order_date)\"],\"display_name\":\"year\"}],\"measures\":[{\"id\":\"01f09972611f1\",\"alias\":\"total_revenue\",\"sql\":[\"SUM(orders.order_amount)\"],\"display_name\":\"total revenue\",\"synonyms\":[\"revenue\",\"total sales\"]}]}}}",
      "space_id": "3c409c00b54a44c79f79da06b82460e2",
      "title": "Sales Analytics Space",
      "warehouse_id": "<warehouse-id>",
    },
    {
      "description": "Space for marketing campaign analysis",
      "serialized_space": "{\"version\":1,\"config\":{\"sample_questions\":[{\"id\":\"a1b2c3d4e5f6\",\"question\":[\"Show total revenue by state\"]}]},\"data_sources\":{\"tables\":[{\"identifier\":\"sales.gold.orders\"}]}}",
      "space_id": "7f8e9d0c1b2a3456789abcdef0123456",
      "title": "Marketing Analytics Space",
      "warehouse_id": "<warehouse-id>",
    }
  ]
}

Utilice el space_id de la respuesta en las llamadas API posteriores.

Descripción del campo serialized_space

El serialized_space campo es una cadena JSON que define la configuración y los orígenes de datos del agente de Genie. En la solicitud de API, este JSON debe ser escapado como una cadena. El campo contiene:

• version: número de versión de esquema para la compatibilidad con versiones anteriores. Use 2 como se muestra en el ejemplo siguiente.
• config: configuración del agente, entre las que se incluyen:
  • sample_questions: preguntas de ejemplo para guiar a los usuarios. Cada pregunta requiere un identificador (cadena hexadecimal de 32 caracteres) y una pregunta (matriz de cadenas).
• data_sources: orígenes de datos disponibles para el agente:
  • tablas: matriz de objetos de tabla con identificador (espacio de nombres de tres niveles), descripción opcional y column_configs opcional.
  • metric_views: matriz de objetos de vista de métricas (misma estructura que tablas).
• instrucciones: Instrucciones estructuradas para el agente:
  • text_instructions: guía de alto nivel para el LLM.
  • example_question_sqls: preguntas de ejemplo con respuestas SQL, opcionalmente con parámetros y usage_guidance.
  • sql_functions: referencias a funciones SQL disponibles para el agente.
  • join_specs: relaciones de combinación predefinidas entre tablas. El sql campo requiere exactamente dos elementos: la condición de combinación, el uso de referencias de alias entre comillas inversas y una anotación de tipo de relación, por ejemplo "--rt=FROM_RELATIONSHIP_TYPE_MANY_TO_ONE--". Consulte El formato de las especificaciones de combinación.
  • sql_snippets: filtros, expresiones y medidasreutilizables.
• Puntos de referencia: preguntas para evaluar la calidad del agente, cada una con una respuesta SQL de referencia.

La versión sin escape del serialized_space campo del ejemplo del agente de creación tiene el siguiente aspecto:

{
  "version": 2,
  "config": {
    "sample_questions": [
      {
        "id": "a1b2c3d4e5f60000000000000000000a",
        "question": ["What were total sales last month?"]
      },
      {
        "id": "b2c3d4e5f6a70000000000000000000b",
        "question": ["Show top 10 customers by revenue"]
      }
    ]
  },
  "data_sources": {
    "tables": [
      {
        "identifier": "sales.analytics.customers",
        "description": ["Customer master data including contact information and account details"],
        "column_configs": [
          {
            "column_name": "customer_id",
            "description": ["Unique identifier for each customer"],
            "synonyms": ["cust_id", "account_id"]
          },
          {
            "column_name": "customer_name",
            "enable_entity_matching": true
          },
          {
            "column_name": "internal_notes",
            "exclude": true
          }
        ]
      },
      {
        "identifier": "sales.analytics.orders",
        "description": ["Transactional order data including order date, amount, and customer information"],
        "column_configs": [
          {
            "column_name": "order_date",
            "enable_format_assistance": true
          },
          {
            "column_name": "region",
            "enable_format_assistance": true,
            "enable_entity_matching": true
          },
          {
            "column_name": "status",
            "enable_format_assistance": true,
            "enable_entity_matching": true
          }
        ]
      },
      {
        "identifier": "sales.analytics.products"
      }
    ],
    "metric_views": [
      {
        "identifier": "sales.analytics.revenue_metrics",
        "description": ["Pre-aggregated revenue metrics by region and time period"],
        "column_configs": [
          {
            "column_name": "period",
            "description": ["Time period for the metric (monthly, quarterly, yearly)"],
            "enable_format_assistance": true
          }
        ]
      }
    ]
  },
  "instructions": {
    "text_instructions": [
      {
        "id": "01f0b37c378e1c9100000000000000a1",
        "content": [
          "When calculating revenue, sum the order_amount column. ",
          "When asked about 'last month', use the previous calendar month. ",
          "Round all monetary values to 2 decimal places."
        ]
      }
    ],
    "example_question_sqls": [
      {
        "id": "01f0821116d912db00000000000000b1",
        "question": ["Show top 10 customers by revenue"],
        "sql": [
          "SELECT customer_name, SUM(order_amount) as total_revenue\n",
          "FROM sales.analytics.orders o\n",
          "JOIN sales.analytics.customers c ON o.customer_id = c.customer_id\n",
          "GROUP BY customer_name\n",
          "ORDER BY total_revenue DESC\n",
          "LIMIT 10"
        ]
      },
      {
        "id": "01f099751a3a1df300000000000000b2",
        "question": ["What were total sales last month"],
        "sql": [
          "SELECT SUM(order_amount) as total_sales\n",
          "FROM sales.analytics.orders\n",
          "WHERE order_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL 1 MONTH)\n",
          "AND order_date < DATE_TRUNC('month', CURRENT_DATE)"
        ]
      },
      {
        "id": "01f099751a3a1df300000000000000b3",
        "question": ["Show sales for a specific region"],
        "sql": [
          "SELECT SUM(order_amount) as total_sales\n",
          "FROM sales.analytics.orders\n",
          "WHERE region = :region_name"
        ],
        "parameters": [
          {
            "name": "region_name",
            "type_hint": "STRING",
            "description": ["The region to filter by (e.g., 'North America', 'Europe')"],
            "default_value": {
              "values": ["North America"]
            }
          }
        ],
        "usage_guidance": ["Use this example when the user asks about sales filtered by a specific geographic region"]
      }
    ],
    "sql_functions": [
      {
        "id": "01f0c0b4e815100000000000000000f1",
        "identifier": "sales.analytics.fiscal_quarter"
      }
    ],
    "join_specs": [
      {
        "id": "01f0c0b4e815100000000000000000c1",
        "left": {
          "identifier": "sales.analytics.orders",
          "alias": "orders"
        },
        "right": {
          "identifier": "sales.analytics.customers",
          "alias": "customers"
        },
        "sql": ["`orders`.`customer_id` = `customers`.`customer_id`", "--rt=FROM_RELATIONSHIP_TYPE_MANY_TO_ONE--"],
        "comment": ["Join orders to customers on customer_id"],
        "instruction": ["Use this join when you need customer details for order analysis"]
      }
    ],
    "sql_snippets": {
      "filters": [
        {
          "id": "01f09972e66d100000000000000000d1",
          "sql": ["orders.order_amount > 1000"],
          "display_name": "high value orders",
          "synonyms": ["large orders", "big purchases"],
          "comment": ["Filters to orders over $1000"],
          "instruction": ["Use when the user asks about high-value or large orders"]
        }
      ],
      "expressions": [
        {
          "id": "01f09974563a100000000000000000e1",
          "alias": "order_year",
          "sql": ["YEAR(orders.order_date)"],
          "display_name": "year",
          "synonyms": ["fiscal year", "calendar year"],
          "comment": ["Extracts the year from order date"],
          "instruction": ["Use for year-over-year analysis"]
        }
      ],
      "measures": [
        {
          "id": "01f09972611f100000000000000000f1",
          "alias": "total_revenue",
          "sql": ["SUM(orders.order_amount)"],
          "display_name": "total revenue",
          "synonyms": ["revenue", "total sales"],
          "comment": ["Sum of all order amounts"],
          "instruction": ["Use this measure for revenue calculations"]
        }
      ]
    }
  },
  "benchmarks": {
    "questions": [
      {
        "id": "01f0d0b4e815100000000000000000g1",
        "question": ["What is the average order value?"],
        "answer": [
          {
            "format": "SQL",
            "content": ["SELECT AVG(order_amount) as avg_order_value\n", "FROM sales.analytics.orders"]
          }
        ]
      }
    ]
  }
}

Al crear su agente, genere esta estructura JSON y, a continuación, conviértala en una cadena de caracteres para la solicitud de la API. Para obtener detalles completos del esquema, consulte la referencia de la API create Genie Agent.

Reglas de validación para serialized_space

El serialized_space JSON debe cumplir las siguientes reglas de validación. Json que no es válido se rechaza durante la creación o actualización del agente.

Versión

• Campo versión: obligatorio. Use 2 para agentes nuevos. El número de versión existe para la compatibilidad con versiones anteriores.

Formato de identificación

Todos los campos de identificador deben tener cadenas hexadecimales en minúsculas de 32 caracteres (formato UUID sin guiones).

• Válido: a1b2c3d4e5f60000000000000000000a
• No válido: a1b2c3d4e5f6 (demasiado corto), A1B2C3D4E5F60000000000000000000A (mayúsculas), a1b2c3d4-e5f6-0000-0000-00000000000a (contiene guiones)

Los identificadores son necesarios para:

• config.sample_questions[].id
• instructions.text_instructions[].id
• instructions.example_question_sqls[].id
• instructions.join_specs[].id
• instructions.sql_snippets.filters[].id
• instructions.sql_snippets.expressions[].id
• instructions.sql_snippets.measures[].id
• benchmarks.questions[].id (si se incluyen pruebas comparativas)

Puede usar el siguiente comando para generar un identificador válido:

python3 -c "import random,datetime;t=int((datetime.datetime.now()-datetime.datetime(1582,10,15)).total_seconds()*1e7);print(f'{(t&0xFFFFFFFFFFFF0000)|(1<<12)|((t&0xFFFF)>>4):016x}{random.getrandbits(62)|0x8000000000000000:016x}')"

Esto genera un UUID ordenado por tiempo. Los identificadores generados en secuencia se ordenan alfabéticamente en el orden en que fueron creados, lo que satisface automáticamente los requisitos de ordenación.

Requisitos de ordenación

Las colecciones que contienen IDs o identificadores deben ordenarse previamente. El sistema valida que las matrices ya están ordenadas y rechazan entradas no ordenadas.

Restricciones de unicidad

• Identificadores de pregunta: todos los identificadores de config.sample_questions y benchmarks.questions deben ser únicos en ambas colecciones.
• Identificadores de instrucción: todos los identificadores en text_instructions, example_question_sqls, sql_functions, join_specs y todos los tipos de sql_snippets deben ser únicos.
• Configuraciones de columna: la combinación de (table_identifier, column_name) debe ser única dentro del agente.

Límites de tamaño y longitud

• Longitud de cadena: los elementos de cadena individuales están limitados a 25 000 caracteres.
• Tamaño de matriz: los campos repetidos están limitados a 10 000 elementos.
• Instrucciones de texto: se permite al máximo 1 instrucción de texto por agente.
• Tablas y vistas de métricas: sujetos a límites específicos del área de trabajo.
• Contenido de SQL: el texto de la consulta en sql los campos y join_specs.sql está sujeto a límites de longitud.

Formato de especificación de unión

El sql campo de cada especificación de combinación debe contener exactamente dos elementos:

1. La condición de combinación, mediante referencias de alias entre comillas inversas:

   "`orders`.`customer_id` = `customers`.`customer_id`"
   

2. Anotación de tipo de relación con el formato siguiente:

   "--rt=FROM_RELATIONSHIP_TYPE_<CARDINALITY>--"
   

   Valores de cardinalidad válidos:

   • FROM_RELATIONSHIP_TYPE_MANY_TO_ONE
   • FROM_RELATIONSHIP_TYPE_ONE_TO_MANY
   • FROM_RELATIONSHIP_TYPE_ONE_TO_ONE
   • FROM_RELATIONSHIP_TYPE_MANY_TO_MANY

Si se omite la anotación de tipo de relación, la API rechaza la solicitud con un error de análisis. Para las combinaciones de varias columnas, cree una especificación de combinación independiente para cada relación.

Otros requisitos

• Identificadores de tabla: debe usar el formato de espacio de nombres de tres niveles (catalog.schema.table).
• Respuestas comparativas: cada pregunta comparativa debe tener exactamente una respuesta con el formato establecido en SQL.
• Fragmentos de código SQL: los campos SQL de filtro, expresión y medida no deben estar vacíos.

Referencia de la API Genie

Las secciones anteriores muestran cómo preparar a un Agente Genie y gestionar agentes en diferentes espacios de trabajo. Para iniciar conversaciones, enviar mensajes y recuperar resultados de los Agentes Genie, consulte la referencia de la API REST:

• APIs en modo agente: envía prompts en modo agente, transmite sus resultados de razonamiento y SQL, y recibe informes finales con citas. Consulta la referencia de la API del modo agente.
• APIs del modo Chat: Inicia una conversación en modo Chat, haz preguntas de seguimiento y recupera SQL generado, resultados de consultas y visualizaciones. Consulta la referencia de la API de conversación.

Procedimientos recomendados y límites

Procedimientos recomendados para usar la API de Genie

Para mantener el rendimiento y la confiabilidad al usar Genie API:

• Implementación de la lógica de reintento con espera exponencial: la API no reintenta solicitudes fallidas, así que incorpora tu propio sistema de cola y espera exponencial. Esto ayuda a la aplicación a controlar errores transitorios y a evitar solicitudes de repetición innecesarias a medida que crece.
• Registrar respuestas de la API: Implemente un registro completo de solicitudes y respuestas de la API para ayudar con la depuración, la monitorización de patrones de uso y el seguimiento de los costos.
• Sondear las actualizaciones de estado cada 1 a 5 segundos: continúe sondeando hasta que se reciba un estado de mensaje concluyente, como COMPLETED, FAILEDo CANCELLED. Limite el sondeo a 10 minutos para la mayoría de las consultas. Si no hay ninguna respuesta concluyente después de 10 minutos, detenga el sondeo y devuelva un error de tiempo de espera o pida al usuario que compruebe manualmente el estado de la consulta más adelante.
• Usar retroceso exponencial para el sondeo: Aumente el intervalo de tiempo entre sondeos hasta un máximo de un minuto. Esto reduce las solicitudes innecesarias para las consultas de larga duración, a la vez que permite una latencia baja para las rápidas.
• Iniciar una nueva conversación para cada sesión: evite reutilizar los subprocesos de conversación entre sesiones, ya que esto puede reducir la precisión debido a la reutilización de contextos no deseados.
• Mantener límites de conversación: para administrar conversaciones antiguas y mantenerse por debajo del límite de 10 000 conversaciones:
  1. Usa el extremo GET /api/2.0/genie/spaces/{space_id}/conversations para ver todos los hilos de conversación existentes de un agente.
  2. Identifique las conversaciones que ya no son necesarias, como conversaciones anteriores o conversaciones de prueba.
  3. Utilice el DELETE /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id} endpoint para quitar conversaciones de manera programática.

Supervisión del agente

Una vez configurada la aplicación, puede supervisar las preguntas y respuestas en la interfaz de usuario de Databricks.

Anime a los usuarios a probar el agente para que obtenga información sobre los tipos de preguntas que es probable que hagan y las respuestas que reciben. Proporcione a los usuarios instrucciones para ayudarles a empezar a probar el agente. Use la pestaña Supervisión para ver preguntas y respuestas. Consulte Supervisión del agente.

También puede usar registros de auditoría para monitorizar la actividad de un agente de Genie. Consulte los eventos del agente Genie.