Utilisez l’API Genie Agents

Intégrez les agents Genie dans votre propre chatbot, agent ou application avec l'API des agents Genie. L'API fournit des API de conversation pour l'interrogation de données en langage naturel avec état (avec questions de suivi et historique) et des APIs de gestion pour les workflows CI/CD qui créent, configurent et déploient des agents Genie sur plusieurs Workspace.

remarque

Les agents Genie étaient auparavant appelés Genie space.

Présentation

L'API Genie fournit deux types de capacités :

• Conversation APIs : Activez l'interrogation des données en langage naturel dans les applications, les chatbots et les frameworks d'agents d'IA. Ces APIs prennent en charge les conversations avec état où les utilisateurs peuvent poser des questions de suivi et explorer les données naturellement au fil du temps.
• APIs de gestion : Permettent la création, la configuration et le déploiement programmatiques des agents Genie à travers les Workspace. Utilisez ces APIs pour les pipelines CI/CD, le contrôle de version et la gestion automatisée des agents.

Cette page décrit les APIs de conversation et de gestion. Avant d'appeler les APIs de conversation, préparez un Genie Agent bien organisé. 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 pourraient toujours recevoir des résultats incorrects même avec une intégration d'API correcte. Ce guide explique la configuration minimale nécessaire pour créer un agent qui fonctionne efficacement avec l'API Genie.

Les exemples sur cette page utilisent directement l'API REST. Vous pouvez également appeler ces APIs à l'aide des SDKs Databricks. Consultez les SDK Databricks.

Prérequis

Pour utiliser l’API Genie, vous devez disposer de :

• Accès à un Workspace Databricks avec le droit Databricks SQL.
• Au moins les privilèges CAN USE sur un SQL Warehouse Pro ou Serverless.

Démarrer

Configurer l'authentification Databricks

Pour les cas d'utilisation en 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 Service Principal pour vous authentifier auprès de l'API. Consultez OAuth pour les Service Principals (OAuth M2M). Les Service Principal doivent disposer des autorisations nécessaires pour accéder aux données et aux SQL Warehouse requis.

Recueillir les détails

• Nom de l'instance du Workspace : Trouvez et copiez le nom de l'instance de votre Workspace à partir de l'URL de votre Workspace Databricks. Pour plus de détails sur les identifiants du Workspace dans votre URL, consultez Obtenir les identifiants pour les objets du Workspace.

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

• ID du Warehouse : vous avez besoin de l'ID d'un SQL Warehouse sur lequel vous disposez au minimum des privilèges CAN USE. Pour trouver l'ID de votre Warehouse :

  1. Allez à SQL Warehouses dans votre workspace.
  2. Sélectionnez le warehouse que vous souhaitez utiliser.
  3. Copiez l'ID du warehouse à partir de l'URL ou de la page des détails du warehouse.

  Vous pouvez également utiliser l'GET /api/2.0/sql/warehouses endpoint de listage des warehouses SQL pour récupérer par programmation une liste de tous les warehouses SQL auxquels vous avez les autorisations d'accès. La réponse inclut l'ID du warehouse.

Créer ou sélectionner un Genie Agent

Un Genie Agent 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.
• **Utilisateur testé** : Testez votre agent en lui posant des questions que vous attendez des utilisateurs finaux. Utilisez les tests pour créer et affiner des exemples de queries SQL.
• Inclut le contexte spécifique à l'entreprise : ajoutez des instructions, des exemples 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 basées sur les questions des utilisateurs anticipées. Voir Benchmarks.

Pour plus d'informations sur la création d'un agent, consultez Créer et gérer un Genie Agent et Préparer un Genie Agent efficace.

Vous pouvez soit créer un Genie Agent, soit utiliser un Genie Agent existant :

Create a new agent

Créez un Genie Agent par programmation à l'aide de l'API de création de Genie Agent. L'exemple suivant montre un agent bien structuré qui suit les bonnes 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"
}

Use an existing agent

Si vous avez déjà un Genie Agent, vous pouvez trouver l'ID d'espace à l'aide de l'API de liste des Genie Agents. Vous pouvez également trouver et copier l'ID d'espace depuis le tab Paramètres du Genie Agent.

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 le space_id de la réponse dans les appels d'API ultérieurs.

Compréhension du champ serialized_space

Le champ serialized_space est une chaîne JSON qui définit la configuration et les sources de données pour votre Genie Agent. Dans la requête API, ce JSON doit être échappé en tant que chaîne de caractères. Le champ contient :

• version : Numéro de version du schéma pour la rétrocompatibilité. Utilisez 2 comme illustré dans l'exemple ci-dessous.

• config : Configuration de l'agent, y compris :

  • sample_questions : Exemples de questions pour guider les utilisateurs. Chaque question nécessite un ID (chaîne hexadécimale 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 identifiant (espace de noms à trois niveaux), description facultative et configurations de colonne facultatives.
  • **metric_views** : Tableau d’objets de vue métrique (même structure que les tables).

• instructions : Instructions structurées pour l'agent :

  • text_instructions : Directives de haut niveau pour le LLM.
  • example_question_sqls : Exemples de questions avec des réponses SQL, éventuellement avec des parameters et 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 requiert exactement deux éléments : la condition de jointure, utilisant des références d’alias entre guillemets inversés, et une annotation de type de relation, par exemple "--rt=FROM_RELATIONSHIP_TYPE_MANY_TO_ONE--". Voir Format des spécifications de jointure.
  • sql_snippets : Filtres , expressions et mesures réutilisables.

• benchmarks : Questions pour évaluer la qualité des agents, chacune avec une réponse SQL de vérité terrain.

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

JSON

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

Lorsque vous construisez votre agent, créez cette structure JSON, puis échappez-la comme une chaîne de caractères pour la requête API. Pour plus de détails sur le schéma, consultez la documentation de référence de l'API Create Genie Agent.

Règles de validation pour l'espace sérialisé

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

Version

• Champ de version : obligatoire. Utilisez 2 pour les nouveaux agents. Le numéro de version existe pour des raisons de rétrocompatibilité.

Format d'ID

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

• Valide : a1b2c3d4e5f60000000000000000000a
• Non valide : a1b2c3d4e5f6 (trop court), A1B2C3D4E5F60000000000000000000A (majuscules), a1b2c3d4-e5f6-0000-0000-00000000000a (contient des tirets).

Des 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 :

Bash

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

Ceci génère un UUID ordonné chronologiquement. Les identifiants générés en séquence sont triés par ordre alphabétique selon leur ordre de création, ce qui satisfait automatiquement les exigences de tri.

Exigences de tri

Les collections contenant des ID ou des identifiants doivent être prétriées. Le système valide que les tableaux sont déjà triés et rejette les entrées non triées.

Collecte	Clé de tri
data_sources.tables	identifier (par ordre alphabétique)
data_sources.metric_views	identifier (par ordre alphabétique)
data_sources.tables[].column_configs	column_name (par ordre alphabétique)
data_sources.metric_views[].column_configs	column_name (par ordre alphabétique)
config.sample_questions	id (par ordre alphabétique)
instructions.text_instructions	id (par ordre alphabétique)
instructions.example_question_sqls	id (par ordre alphabétique)
instructions.sql_functions	(id, identifier) tuple (alphabétiquement)
instructions.join_specs	id (par ordre alphabétique)
instructions.sql_snippets.filters	id (par ordre alphabétique)
instructions.sql_snippets.expressions	id (par ordre alphabétique)
instructions.sql_snippets.measures	id (par ordre alphabétique)
benchmarks.questions	id (par ordre alphabétique)

Collecte	Clé de tri
data_sources.tables	identifier (par ordre alphabétique)
data_sources.metric_views	identifier (par ordre alphabétique)
data_sources.tables[].column_configs	column_name (par ordre alphabétique)
data_sources.metric_views[].column_configs	column_name (par ordre alphabétique)
config.sample_questions	id (par ordre alphabétique)
instructions.text_instructions	id (par ordre alphabétique)
instructions.example_question_sqls	id (par ordre alphabétique)
instructions.sql_functions	(id, identifier) tuple (alphabétiquement)
instructions.join_specs	id (par ordre alphabétique)
instructions.sql_snippets.filters	id (par ordre alphabétique)
instructions.sql_snippets.expressions	id (par ordre alphabétique)
instructions.sql_snippets.measures	id (par ordre alphabétique)
benchmarks.questions	id (par ordre alphabétique)

Contraintes d'unicité

• ID de question : tous les ID dans config.sample_questions et benchmarks.questions doivent être uniques parmi les deux collections.
• ID d'instruction : tous les ID pour text_instructions, example_question_sqls, sql_functions, join_specs et tous les types sql_snippets doivent être uniques.
• Configurations de colonne : La combinaison de (table_identifier, column_name) doit être unique au sein de l'agent.

Limites de taille et de longueur

• Longueur des chaînes : 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 textuelles : Au maximum 1 instruction textuelle est autorisée par agent.
• Tables et vues métriques : Soumis à des limites spécifiques au workspace.
• Contenu SQL : Le texte de la query dans les champs sql et join_specs.sql est soumis à des limites de longueur.

Format des spécifications de jointure

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

1. La condition de jointure, utilisant des références d’alias entre guillemets inversés :

   Text

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

2. Une annotation de type de relation au format suivant :

   Text

   "--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 du type de relation entraîne le rejet de la requête par l'API avec une erreur d'analyse. Pour les jointures multi-colonnes, créez une spécification de jointure distincte pour chaque relation.

Autres exigences

• Identifiants de table : Doivent utiliser le format d'espace de noms à trois niveaux (catalog.schema.table).
• Réponses de référence : Chaque question de référence doit avoir une seule réponse avec le format défini sur SQL.
• Extraits SQL : les champs SQL de filtre, d'expression et de mesure ne doivent pas être vides.

Utilisation de l'API de conversation

Après avoir configuré un Genie Agent, utilisez les Endpoint d'API de conversation pour poser des questions, récupérer des résultats et maintenir des conversations à plusieurs tours avec le contexte.

start une conversation

L’ Endpoint de start conversation POST /api/2.0/genie/spaces/{space_id}/start-conversation start une nouvelle conversation dans votre Genie Agent.

Remplacez les espaces réservés par votre instance Databricks, l'ID de votre Genie Agent et votre jeton d'authentification. Un exemple de réponse réussie suit la requête. Il comprend des détails que vous pouvez utiliser pour accéder à nouveau à cette conversation pour des questions de suivi.

POST /api/2.0/genie/spaces/{space_id}/start-conversation

HOST= <DATABRICKS_INSTANCE>
Authorization: <your_authentication_token>
{
    "content": "<your question>",
}


Response:

{
  "conversation": {
    "created_timestamp": 1719769718,
    "id": "6a64adad2e664ee58de08488f986af3e",
    "last_updated_timestamp": 1719769718,
    "space_id": "3c409c00b54a44c79f79da06b82460e2",
    "title": "Give me top sales for last month",
    "user_id": 12345
  },
  "message": {
    "attachments": null,
    "content": "Give me top sales for last month",
    "conversation_id": "6a64adad2e664ee58de08488f986af3e",
    "created_timestamp": 1719769718,
    "error": null,
    "id": "e1ef34712a29169db030324fd0e1df5f",
    "last_updated_timestamp": 1719769718,
    "query_result": null,
    "space_id": "3c409c00b54a44c79f79da06b82460e2",
    "status": "IN_PROGRESS",
    "user_id": 12345
  }
}

Récupérer le SQL généré

Utilisez les conversation_id et message_id dans la réponse pour interroger afin de vérifier l'état de génération du message et récupérer le SQL généré par Genie. Consultez GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id} pour les détails complets de la requête et de la réponse.

Substituez vos valeurs dans la requête suivante :

GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}
HOST= <DATABRICKS_INSTANCE>
Authorization: Bearer <your_authentication_token>

La réponse d'exemple suivante indique les détails du message :

Response:

{
  "attachments": null,
  "content": "Give me top sales for last month",
  "conversation_id": "6a64adad2e664ee58de08488f986af3e",
  "created_timestamp": 1719769718,
  "error": null,
  "id": "e1ef34712a29169db030324fd0e1df5f",
  "last_updated_timestamp": 1719769718,
  "query_result": null,
  "space_id": "3c409c00b54a44c79f79da06b82460e2",
  "status": "IN_PROGRESS",
  "user_id": 12345
}

Le champ attachments est progressivement rempli pendant le traitement. Lorsque l'état est PENDING_WAREHOUSE ou EXECUTING_QUERY, vous pouvez déjà commencer à lire le champ attachments. La réponse se remplit de manière incrémentielle, en commençant par la query SQL générée, suivie de la description, des questions de suivi et du contexte supplémentaire. L'état COMPLETED indique que le processus de réponse est entièrement terminé et que le sondage peut s'arrêter, mais un contenu significatif est disponible plus tôt si votre client inspecte la réponse pendant le sondage plutôt que d'attendre la fin.

Pour déterminer si une réponse a été générée à l’aide d’un asset approuvé, vérifiez le champ attachments dans la réponse pour un objet query.parameters. Sa présence indique que la réponse provient d'un actif de confiance.

Pour accéder aux traces de raisonnement de Genie, vérifiez le champ attachments pour un objet query_attachments de type GenieQueryAttachments. Le cas échéant, il contient le raisonnement étape par étape utilisé par Genie pour générer la réponse. Pour les détails complets des champs, consultez la Référence de l'API de message Get.

Récupérer les résultats des query

Le tableau attachments contient la réponse de Genie. Elle inclut la réponse textuelle générée (text), l'instruction de la query si elle existe (query) et un identifiant que vous pouvez utiliser pour obtenir les résultats de la query associée (attachment_id). Remplacez les espaces réservés dans l'exemple suivant pour récupérer les résultats de la query générée :

remarque

Contrairement à l’interface utilisateur de Genie Agents, l’API de conversation Genie ne prend pas en charge le modèle de réponse en deux phases où Genie affiche une réponse préliminaire, puis la met à jour après inspection. Pour présenter la progression incrémentielle aux utilisateurs, inspectez le champ attachments pendant l’interrogation des états PENDING_WAREHOUSE ou EXECUTING_QUERY plutôt que d’attendre COMPLETED.

GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/query-result/{attachment_id}
Authorization: Bearer <your_authentication_token>

Voir GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/attachments/{attachment_id}/query-result.

Récupérer les résultats de visualisation (Bêta)

Par default, l’API de conversation Genie renvoie des résultats de query tabulaires. Pour récupérer également les résultats de visualisation, définissez enable_visualization: true lorsque vous start une conversation ou créez un message. Lorsqu'il est activé, le champ attachments dans la réponse inclut un objet viz de type GenieVizAttachment contenant la visualisation title et le query_attachment_id à partir duquel elle a été générée.

Pour télécharger la visualisation, utilisez l'Endpoint de visualisation de pièce jointe de message de download :

GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/attachments/{attachment_id}/download-visualization
Authorization: Bearer <your_authentication_token>

Consultez la référence de l'API Genie.

remarque

Les résultats de visualisation ne sont pas pris en charge pour les Private Link Workspaces.

Poser des questions de suivi

Après avoir reçu une réponse, utilisez le conversation_id pour continuer la conversation. Le contexte des messages précédents est conservé et utilisé dans les réponses de suivi. Pour les détails complets de la requête et de la réponse, consultez POST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages.

POST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages
HOST= <DATABRICKS_INSTANCE>
Authorization: <your_authentication_token>
{
  "content": "Which of these customers opened and forwarded the email?",
}

Ajouter des commentaires aux messages

Vous pouvez ajouter des commentaires textuels aux messages et lister les commentaires existants à l'aide des Endpoint de l'API de commentaires de messages.

Pour ajouter un commentaire à un message, utilisez l'endpoint de création de commentaires de message POST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/comments:

POST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/comments
HOST= <DATABRICKS_INSTANCE>
Authorization: Bearer <your_authentication_token>
{
  "content": "<your comment text>"
}

Pour lister les commentaires existants sur un message, utilisez l'endpoint de liste des commentaires de messages.

Récupérer les données de l'agent et de la conversation

L'API Genie fournit des endpoints supplémentaires pour récupérer la configuration et les données historiques des agents et conversations existants.

Récupérer la configuration de l’agent

Lors de la récupération des informations de l'agent à l'aide de l'API Get Genie Agent, vous pouvez inclure le champ serialized_space dans la réponse en définissant le parameter include_serialized_space sur true. Le champ serialized_space contient la représentation sous forme de chaîne sérialisée du Genie Agent, y compris les instructions, les benchmarks, les jointures et d'autres détails de configuration.

Utilisez cette représentation sérialisée avec l'API de création de Genie Agent et l'API de mise à jour de Genie Agent pour promouvoir les Genie Agents entre les Workspaces ou créer des sauvegardes des configurations d'agent.

Exemple de requête GET :

GET /api/2.0/genie/spaces/{space_id}?include_serialized_space=true
Host: <DATABRICKS_INSTANCE>
Authorization: Bearer <your_authentication_token>

Response:
{
  "space_id": "3c409c00b54a44c79f79da06b82460e2",
  "title": "Sales Analytics Space",
  "description": "Space for analyzing sales performance and trends",
  "warehouse_id": "<warehouse-id>",
  "serialized_space": "{\"version\":1,\"config\":{\"sample_questions\":[{\"id\":\"a1b2c3d4e5f600000000000000000000\",\"question\":[\"What were total sales last month?\"]},{\"id\":\"b2c3d4e5f6g700000000000000000000\",\"question\":[\"Show top 10 customers by revenue\"]}]},\"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\"]}]"
}

Référencer d'anciens fils de discussion

Pour permettre aux utilisateurs de faire référence aux anciens fils de conversation, utilisez l’ endpoint de liste des messages de conversation GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages pour récupérer tous les messages d’un fil de conversation spécifique.

Récupérer les données de conversation pour analyse

Les gestionnaires d'agents peuvent récupérer par programme tous les messages précédents posés par tous les utilisateurs d'un agent pour analyse. Pour récupérer ces données :

1. Utiliser l'GET /api/2.0/genie/spaces/{space_id}/conversations endpoint pour obtenir tous les threads de conversation existants d'un agent.

   • Par default, cet Endpoint renvoie uniquement les conversations de l'utilisateur demandeur. Pour renvoyer les conversations de tous les utilisateurs de l'agent, définissez le paramètre include_all sur true. L'utilisation de include_all nécessite au moins la permission CAN MANAGE sur l'agent.

2. Pour chaque ID de conversation renvoyé, utilisez l'endpoint GET /api/2.0/genie/spaces/{space_id}/conversations pour récupérer la liste des messages de cette conversation.

Bonnes pratiques et limites

Bonnes 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 relance pas les requêtes échouées pour vous, alors ajoutez votre propre mise en file d'attente et interruption exponentielle. Cela aide votre application à gérer les défaillances transitoires et à éviter les requêtes répétées inutiles à mesure qu'elle se développe.
• Logs des réponses de l'API : Mettez en œuvre des Logs complets des requêtes et des réponses de l'API pour faciliter le debugging, le monitoring des modèles d'utilisation et le suivi des coûts.
• Interroger les mises à jour de statut toutes les 1 à 5 secondes : continuez l'interrogation jusqu'à ce qu'un statut de message concluant, tel que COMPLETED, FAILED, ou CANCELLED, soit reçu. Limitez l'interrogation à 10 minutes pour la plupart des requêtes. S'il n'y a aucune réponse concluante après 10 minutes, arrêtez d'interroger et renvoyez une erreur de délai d'expiration ou invitez l'utilisateur à vérifier manuellement le statut de la query plus tard.
• Utilisez un retrait exponentiel pour le sondage : augmentez le délai entre les sondages jusqu'à un maximum d'une minute. Cela réduit les query inutiles pour les query de longue durée tout en permettant une faible latence pour les plus rapides.
• Start une nouvelle conversation pour chaque session : évitez de réutiliser les fils de conversation entre les sessions, car cela peut réduire la précision en raison d'une réutilisation involontaire du contexte.
• Maintenir les limites de conversation : Pour gérer les anciennes conversations et rester en dessous de la limite de 10 000 conversations :
  1. Utilisez l'endpoint GET /api/2.0/genie/spaces/{space_id}/conversations pour voir tous les fils de conversation existants dans un agent.
  2. Identifiez les conversations qui ne sont plus nécessaires, comme les conversations plus anciennes ou les conversations de test.
  3. Utilisez l'DELETE /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id} endpoint pour supprimer les conversations par programmation.

Surveiller l'agent

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

Encouragez les utilisateurs à tester l'agent afin que vous découvriez les types de questions qu'ils sont susceptibles de poser et les réponses qu'ils reçoivent. Fournissez aux utilisateurs des directives pour les aider à start à tester l'agent. Utilisez l'onglet monitoring pour afficher les questions et les réponses. Voir Surveiller l'agent.

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