Utiliser l’API Agents Genie

Intégrez Genie Agents à votre propre chatbot, agent ou application grâce à l’API Genie Agents. L’API fournit des API en mode chat pour la requête de données en langage naturel avec état (avec questions de suivi et historique) ainsi que des API de gestion pour les flux de travail CI/CD qui créent, configurent et déploient des agents Genie dans les espaces de travail.

Aperçu

L’API Genie offre les types de fonctionnalités suivants :

• API en mode chat : Activez la requête de données en langage naturel dans les applications, chatbots et frameworks d’agents. Ces API prennent en charge des conversations avec état créées en mode Chat où les utilisateurs peuvent poser des questions complémentaires et explorer naturellement les données au fil du temps.
• API en mode agent : permettent aux développeurs d’envoyer des invites de façon programmatique en mode agent, de diffuser les résultats de raisonnement et SQL, et de recevoir les rapports finaux avec les citations.
• API de gestion : activez la création, la configuration et le déploiement programmatiques d’agents Genie dans les espaces de travail. Utilisez ces API pour les pipelines CI/CD, le contrôle de version et la gestion automatisée des agents.

Cette page explique comment préparer un agent Genie bien sélectionné et gérer les agents à travers les espaces de travail afin que l’API restitue des résultats fiables. L’agent fournit le contexte que Genie utilise pour interpréter les questions et générer des réponses. Si l’agent est incomplet ou non testé, les utilisateurs peuvent toujours recevoir des résultats incorrects même avec une intégration correcte de l’API. Pour les terminaux d’exécution, les formats de requête et les formats de réponse, voir la référence API REST liée dans la référence de l’API Genie.

Les exemples de configuration sur cette page utilisent directement l’API REST. Vous pouvez également appeler ces API à l’aide des sdk Azure Databricks. Consultez les Kits de développement logiciel (SDK) Databricks.

Prerequisites

Pour utiliser l’API Genie, vous devez avoir :

• Accès à un espace de travail Azure Databricks avec l'autorisation Databricks SQL.
• Au moins les privilèges PEUT UTILISER sur un entrepôt de données SQL Pro ou SQL serverless.

Premiers pas

Configurer l’authentification Azure Databricks

Pour les cas d’usage de production où un utilisateur ayant accès à un navigateur est présent, utilisez OAuth pour les utilisateurs (OAuth U2M). Dans les situations où l’authentification basée sur un navigateur n’est pas possible, utilisez un principal de service pour s’authentifier auprès de l’API. Consultez OAuth pour les entités de service (OAuth M2M). Les principaux de service doivent disposer des autorisations nécessaires pour accéder aux données requises et aux entrepôts SQL.

Collecter les détails

• Nom de l’instance de l’espace de travail : recherchez et copiez le nom de votre instance d’espace de travail à partir de l’URL de votre espace de travail Databricks. Pour plus d’informations sur les identificateurs d’espace de travail dans votre URL, consultez Obtenir des identificateurs pour les objets d’espace de travail.

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

• ID d’entrepôt : vous avez besoin de l’ID d’un entrepôt SQL sur lequel vous disposez au moins des privilèges CAN USE. Pour trouver votre ID d’entrepôt :

  1. Accédez à SQL Warehouses dans votre espace de travail.
  2. Sélectionnez l’entrepôt que vous souhaitez utiliser.
  3. Copiez l’ID de l’entrepôt à partir de l’URL ou de la page de détails de l’entrepôt.

  Vous pouvez également utiliser le point de terminaisonGET /api/2.0/sql/warehouses d’entrepôts de liste pour récupérer par programme une liste de tous les entrepôts SQL auxquels vous disposez des autorisations d’accès. La réponse inclut l’ID de l’entrepôt.

Créer ou sélectionner un agent Genie

Un Agent Génie bien structuré présente les caractéristiques suivantes :

• Utilise des données bien annotées : Genie s’appuie sur les métadonnées de table et les commentaires de colonne. Vérifiez que vos sources de données Unity Catalog ont des commentaires clairs et descriptifs.
• Test de l’utilisateur : testez votre agent en posant des questions que vous attendez des utilisateurs finaux. Utilisez des tests pour créer et affiner des exemples de requêtes SQL.
• Inclut un contexte spécifique à l’entreprise : ajouter des instructions, des exemples de sql et des fonctions. Consultez ajouter des exemples et des instructions SQL. Visez au moins cinq exemples de requêtes SQL testées.
• Utilise des benchmarks pour tester la précision : ajoutez au moins cinq questions de benchmark en fonction des questions attendues de l’utilisateur. Voir Benchmarks.

Pour plus d’informations sur la création d’un agent, consultez Créer et gérer un Agent Génie etOrganiser un agent Génie efficace.

Vous pouvez créer un agent Genie ou en utiliser un existant :

Créer un agent

Créez un agent Genie par programmation à l’aide de l’API Create Genie Agent. L’exemple suivant illustre un agent bien structuré qui suit les meilleures pratiques. Remplacez les espaces réservés par vos valeurs :

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"
}

Utiliser un agent existant

Si vous disposez déjà d’un Agent Génie, vous pouvez trouver l’ID d’espace à l’aide de l’API List Genie Agents. Vous pouvez également rechercher et copier l’ID d’espace sous l’onglet Paramètres de l’agent Génie.

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>",
    }
  ]
}

Utilisez la réponse space_id dans les appels d’API suivants.

Comprendre le champ serialized_space

Le serialized_space champ est une chaîne JSON qui définit la configuration et les sources de données de votre agent Genie. Dans la requête d’API, ce JSON doit être échappé sous forme de chaîne. Le champ contient :

• version : numéro de version du schéma pour la compatibilité descendante. Utilisez 2 comme indiqué dans l’exemple ci-dessous.
• config : Configuration de l’agent, notamment :
  • sample_questions : Exemples de questions pour guider les utilisateurs. Chaque question nécessite un ID (chaîne hexadécimal de 32 caractères) et une question (tableau de chaînes).
• data_sources : sources de données disponibles pour l’agent :
  • tables : tableau d’objets de table avec identificateur (espace de noms à trois niveaux), description facultative et column_configs facultatif.
  • metric_views : tableau d’objets de vue de métrique (même structure que les tables).
• instructions : instructions structurées pour l’agent :
  • text_instructions : lignes directrices générales pour le LLM.
  • example_question_sqls : Exemples de questions avec des réponses SQL, éventuellement avec des paramètres et des usage_guidance.
  • sql_functions : références aux fonctions SQL disponibles pour l’agent.
  • join_specs : relations de jointure prédéfinies entre les tables. Le champ sql nécessite exactement deux éléments : la condition de jointure, à l’aide de références d’alias entre guillemets inversés, et une annotation de type relationnel, par exemple "--rt=FROM_RELATIONSHIP_TYPE_MANY_TO_ONE--". Consultez le format des spécifications de jointure.
  • sql_snippets : filtres, expressions et mesuresréutilisables.
• benchmarks : Questions permettant d’évaluer la qualité de l’agent, chacune avec une réponse SQL de référence.

La version non échappée du champ serialized_space de l’exemple de création d’agent ressemble à ceci :

{
  "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"]
          }
        ]
      }
    ]
  }
}

Lors de la création de votre agent, créez cette structure JSON, puis placez-la en échappement pour la requête API. Pour plus d’informations sur le schéma, consultez la référence de l’API Create Genie Agent.

Règles de validation pour serialized_space

Le serialized_space json doit être conforme aux règles de validation suivantes. JSON non valide est rejeté lors de la création ou de la mise à jour de l’agent.

Version

• Champ Version : obligatoire. Utiliser 2 pour les nouveaux agents. Le numéro de version existe pour la compatibilité descendante.

Format de l'ID

Tous les champs d’ID doivent être des chaînes hexadécimales minuscules de 32 caractères (format UUID sans traits d’union).

• Valide : a1b2c3d4e5f60000000000000000000a
• Non valide : a1b2c3d4e5f6 (trop court), A1B2C3D4E5F60000000000000000000A (majuscules), a1b2c3d4-e5f6-0000-0000-00000000000a (contient des traits d’union)

Les ID sont requis pour :

• 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 des benchmarks sont inclus)

Vous pouvez utiliser la commande suivante pour générer un ID valide :

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}')"

Cela génère un UUID chronologique. Les ID générés séquentiellement s'ordonnent automatiquement dans l’ordre de leur création, satisfaisant ainsi les exigences de tri automatiquement.

Exigences de tri

Les collections contenant des ID ou des identificateurs doivent être pré-triées. Le système valide que les tableaux sont déjà triés et rejettent l’entrée non triée.

Contraintes d’unicité

• ID de question : tous les ID dans config.sample_questions et benchmarks.questions doivent être uniques dans les deux collections.
• ID d’instruction : tous les ID entre text_instructions, example_question_sqls, sql_functions, join_specset tous les sql_snippets types doivent être uniques.
• Configurations de colonne : la combinaison de (table_identifier, column_name) doit être unique dans l’agent.

Limites de taille et de longueur

• Longueur de chaîne : les éléments de chaîne individuels sont limités à 25 000 caractères.
• Taille du tableau : les champs répétés sont limités à 10 000 éléments.
• Instructions de texte : Au maximum 1 instruction de texte est autorisée par agent.
• Tables et vues de métriques : soumis à des limites spécifiques à l’espace de travail.
• Contenu SQL : le texte de requête dans sql et join_specs.sql les champs est soumis à des limites de longueur.

Format des spécifications de jointure

Le sql champ de chaque spécification de jointure doit contenir exactement deux éléments :

1. Condition de jointure, à l’aide de références d’alias entre guillemets inversés :

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

2. Annotation de type relation au format suivant :

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

   Valeurs de cardinalité valides :

   • FROM_RELATIONSHIP_TYPE_MANY_TO_ONE
   • FROM_RELATIONSHIP_TYPE_ONE_TO_MANY
   • FROM_RELATIONSHIP_TYPE_ONE_TO_ONE
   • FROM_RELATIONSHIP_TYPE_MANY_TO_MANY

L’omission de l’annotation de type de relation entraîne le rejet de la requête par une erreur d’analyse. Pour les jointures à plusieurs colonnes, créez une spécification de jointure distincte pour chaque relation.

Autres exigences

• Identificateurs de table : doit utiliser le format d’espace de noms de trois niveaux (catalog.schema.table).
• Réponses de benchmark : chaque question de benchmark doit avoir exactement une réponse avec un format défini sur SQL.
• Extraits de code SQL : Les champs SQL de filtre, d’expression et de mesure ne doivent pas être vides.

Référence API Genie

Les sections précédentes montrent comment préparer un agent Génie et gérer les agents à travers les espaces de travail. Pour lancer des conversations, envoyer des messages et récupérer les résultats des agents Genie, voir la référence de l’API REST :

• API en mode agent : envoyez des invites en mode agent, diffusez ses résultats de raisonnement et SQL, et recevez les rapports finaux avec les citations. Voir la référence de l’API en mode agent.
• API du mode chat : Démarrez une conversation en mode Chat, posez des questions de suivi, et récupérez le SQL généré, les résultats des requêtes et les visualisations. Voir la référence de l’API Conversation.

Meilleures pratiques et limites

Meilleures pratiques pour l’utilisation de l’API Genie

Pour maintenir les performances et la fiabilité lors de l’utilisation de l’API Genie :

• Implémentez une logique de nouvelle tentative avec interruption exponentielle : l’API ne tente pas les demandes ayant échoué pour vous. Ajoutez donc votre propre file d’attente et votre interruption exponentielle. Cela permet à votre application de gérer les défaillances temporaires et d’éviter les demandes répétées inutiles au fur et à mesure qu’elle augmente.
• Journalisation des réponses API : implémenter la journalisation complète des demandes et réponses API pour faciliter le débogage, le suivi des modèles d’utilisation et le suivi des coûts.
• Interroger les mises à jour d’état toutes les 1 à 5 secondes : continuez l’interrogation jusqu’à ce qu’un message d’état concluant, tel que COMPLETED, FAILED ou CANCELLED, soit reçu. Limitez l’interrogation à 10 minutes pour la plupart des requêtes. S’il n’existe aucune réponse concluante après 10 minutes, arrêtez l’interrogation et retournez une erreur de délai d’expiration ou invitez l’utilisateur à vérifier manuellement l’état de la requête ultérieurement.
• Utilisez un ralentissement exponentiel pour l’interrogation : augmentez le délai entre les interrogations jusqu’à un maximum d’une minute. Cela réduit les requêtes inutiles pour les requêtes longues tout en autorisant une faible latence pour les requêtes rapides.
• Démarrez une nouvelle conversation pour chaque session : évitez de réutiliser les threads de conversation entre les sessions, car cela peut réduire la précision en raison d’une réutilisation inattendue du contexte.
• Maintenir les limites de conversation : pour gérer les anciennes conversations et rester sous la limite de 10 000 conversations :
  1. Utilisez le GET /api/2.0/genie/spaces/{space_id}/conversations point de terminaison pour afficher tous les threads de conversation existants dans un agent.
  2. Identifiez les conversations qui ne sont plus nécessaires, telles que les conversations plus anciennes ou les conversations de test.
  3. Utilisez le DELETE /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id} point de terminaison pour supprimer les conversations par programmation.

Surveiller l’agent

Une fois votre application configurée, vous pouvez surveiller les questions et réponses dans l’interface utilisateur Databricks.

Encouragez les utilisateurs à tester l’agent afin d’en savoir plus sur les types de questions qu’ils sont susceptibles de poser et les réponses qu’ils reçoivent. Fournissez aux utilisateurs des conseils pour les aider à commencer à tester l’agent. Utilisez l’onglet Surveillance pour afficher les questions et les réponses. Consultez Surveillance de l’agent.

Vous pouvez également utiliser les journaux d’audit pour surveiller l’activité dans un Agent Genie. Consultez les événements de l’Agent Genie.