Utilizar a API Genie Agents

Integre os Genie Agents no seu próprio chatbot, agente ou aplicação através da API dos Genie Agents. A API fornece APIs em modo Chat para consulta de dados em linguagem natural com estado (com perguntas de seguimento e histórico) e APIs de Gestão para fluxos de trabalho CI/CD que criam, configuram e implementam Agentes Genie em espaços de trabalho.

Descrição geral

A API do Genie oferece os seguintes tipos de capacidades:

• APIs do modo chat: Permitir a consulta de dados em linguagem natural em aplicações, chatbots e frameworks de agentes. Estas APIs suportam conversas com estado criadas em modo Chat, onde os utilizadores podem fazer perguntas de seguimento e explorar dados de forma natural ao longo do tempo.
• APIs do modo Agente: Permitem aos programadores enviar prompts programaticamente no modo Agente, transmitir os resultados de raciocínio e SQL, e receber relatórios finais com citações.
• APIs de gestão: Permitir a criação, configuração e implementação programática de Agentes Genie em vários espaços de trabalho. Use estas APIs para pipelines CI/CD, controlo de versões e gestão automatizada de agentes.

Esta página explica como preparar um Agente Genie bem selecionado e gerir agentes entre espaços de trabalho, de modo a que a API devolva resultados fiáveis. O agente fornece o contexto que o Génio usa para interpretar perguntas e gerar respostas. Se o agente estiver incompleto ou não testado, os utilizadores podem ainda assim receber resultados incorretos mesmo com uma integração correta da API. Para os endpoints de runtime, os formatos de pedido e de resposta, consulte a referência da API REST indicada em referência da API Genie.

Os exemplos de configuração nesta página usam diretamente a API REST. Também pode chamar estas APIs usando os SDKs do Azure Databricks. Ver SDKs Databricks.

Pré-requisitos

Para usar a API do Genie, deve ter:

• Acesso a um espaço de trabalho do Azure Databricks com a permissão Databricks SQL.
• Pelo menos PODE USAR privilégios em um SQL pro ou SQL warehouse sem servidor.

Como Começar

Configurar autenticação Azure Databricks

Para casos de uso de produção em que um usuário com acesso a um navegador está presente, use OAuth para usuários (OAuth U2M). Em situações em que a autenticação baseada em navegador não é possível, utilize um principal de serviço para autenticar com a API. Consulte OAuth para entidades de serviço (OAuth M2M). As entidades de serviço devem ter permissões para acessar os dados necessários e os SQL warehouses.

Recolha detalhes

• Nome da instância do espaço de trabalho: Encontre e copie o nome da sua instância do espaço de trabalho a partir do URL do seu espaço de trabalho Databricks. Para obter detalhes sobre os identificadores de espaço de trabalho em sua URL, consulte Obter identificadores para objetos de espaço de trabalho.

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

• ID do armazém: Precisa do ID de um armazém SQL onde tem pelo menos privilégios de utilizar. Para encontrar o ID do seu armazém:

  1. Vai a SQL Warehouses no teu espaço de trabalho.
  2. Seleciona o armazém que queres usar.
  3. Copie o ID do armazém a partir do URL ou da página de detalhes do armazém.

  Alternativamente, usa o endpoint GET /api/2.0/sql/warehouses para recuperar programaticamente uma lista de todos os warehouses SQL aos quais tens permissões de acesso. A resposta inclui o ID do armazém.

Crie ou selecione um Agente Génio

Um Agente Génio bem estruturado apresenta as seguintes características:

• Utiliza dados bem anotados: O Genie baseia-se em metadados de tabela e comentários nas colunas. Verifique se as suas fontes de dados do Unity Catalog têm comentários claros e descritivos.
• Foi testado por utilizadores: Teste o seu agente fazendo perguntas que espera que os utilizadores finais façam. Use testes para criar e refinar exemplos de consultas SQL.
• Inclui contexto específico da empresa: Adicionar instruções, SQL de exemplo e funções. Consulte Adicionar exemplos e instruções SQL. Procura pelo menos cinco consultas SQL de exemplo testadas.
• Utiliza benchmarks para testar a precisão: Adiciona pelo menos cinco perguntas de benchmark com base nas perguntas antecipadas dos utilizadores. Consulte Benchmarks.

Para mais informações sobre como criar um agente, consulte Criar e gerir um Agente Génio e Curar um Agente Génio eficaz.

Podes criar um novo Agente Génio ou usar um existente:

Criar um novo agente

Crie um Agente Genie programaticamente usando a API Create Genie Agent. O exemplo seguinte demonstra um agente bem estruturado que segue as melhores práticas. Substitua os espaços reservados pelos seus valores.

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 um agente existente

Se já tens um Agente Genie, podes encontrar o ID do espaço usando a API List Genie Agents. Também podes encontrar e copiar o ID do espaço no separador Definições do Agente 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>",
    }
  ]
}

Utilize a space_id da resposta em chamadas subsequentes à API.

Compreender o campo serialized_space

O serialized_space campo é uma string JSON que define a configuração e as fontes de dados do seu Agente Genie. No pedido da API, este JSON deve ser convertido numa string. O campo contém:

• versão: Número de versão do esquema para compatibilidade retroativa. Use 2 conforme mostrado no exemplo abaixo.
• config: Configuração do agente incluindo:
  • sample_questions: Perguntas de exemplo para orientar os utilizadores. Cada pergunta requer um id (cadeia hexadecimal de 32 caracteres) e uma pergunta (array de cadeias).
• data_sources: Fontes de dados disponíveis para o agente:
  • tabelas: Array de objetos de tabela com identificador (espaço de nomes de três níveis), descrição opcional e column_configs opcional.
  • metric_views: Array de objetos de vista métrica (mesma estrutura das tabelas).
• instruções: Instruções estruturadas para o agente:
  • text_instructions: Orientação de alto nível para o LLM.
  • example_question_sqls: Perguntas de exemplo com respostas SQL, opcionalmente com parâmetros e usage_guidance.
  • sql_functions: Referências a funções SQL disponíveis para o agente.
  • join_specs: Relações de junção pré-definidas entre tabelas. O sql campo requer exatamente dois elementos: a condição de junção, usando referências de alias entre aspas de backtick, e uma anotação de tipo de relação, por exemplo "--rt=FROM_RELATIONSHIP_TYPE_MANY_TO_ONE--". Consulte o formato de especificações Join.
  • sql_snippets: Filtros, expressões e medidas reutilizáveis.
• benchmarks: Perguntas para avaliar a qualidade do agente, cada uma com uma resposta SQL fundamentada.

A versão não escapada do serialized_space campo do exemplo de criar agente é a seguinte:

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

Ao construir o seu agente, crie esta estrutura JSON e depois escape-a sob a forma de uma string no pedido à API. Para detalhes completos do esquema, consulte a referência da API Create Genie Agent.

Regras de validação para serialized_space

O serialized_space JSON deve cumprir as seguintes regras de validação. O JSON que não é válido é rejeitado durante a criação ou atualização do agente.

Versão

• Campo de versão: Obrigatório. Utilize 2 para novos agentes. O número de versão existe para compatibilidade retroativa.

Formato de Identificação

Todos os campos ID devem ser cadeias hexadecimais minúsculas de 32 caracteres (formato UUID sem hífenes).

• Válido: a1b2c3d4e5f60000000000000000000a
• Não válido: a1b2c3d4e5f6 (demasiado curto), A1B2C3D4E5F60000000000000000000A (maiúsculo), a1b2c3d4-e5f6-0000-0000-00000000000a (contém hífens)

As identificações são obrigatórias 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 (se os benchmarks forem incluídos)

Pode usar o seguinte comando para gerar um ID 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}')"

Isto gera um UUID ordenado no tempo. Os IDs gerados em sequência ordenam-se alfabeticamente na ordem em que foram criados, o que satisfaz automaticamente os requisitos de ordenação .

Requisitos de ordenação

As coleções que contenham IDs ou identificadores devem ser pré-ordenadas. O sistema valida que os arrays já estão ordenados e rejeita entrada não ordenada.

Restrições de unicidade

• IDs de perguntas: Todos os IDs em config.sample_questions e benchmarks.questions devem ser únicos em ambas as coleções.
• IDs de instrução: Todos os IDs em text_instructions, example_question_sqls, sql_functions, join_specs, e todos sql_snippets os tipos devem ser únicos.
• Configurações de colunas: A combinação de (table_identifier, column_name) deve ser única dentro do agente.

Limites de tamanho e comprimento

• Comprimento da string: Os elementos individuais da string estão limitados a 25.000 caracteres.
• Tamanho do array: Campos repetidos estão limitados a 10.000 itens.
• Instruções de texto: No máximo 1 instrução de texto é permitida por agente.
• Tabelas e vistas métricas: Sujeitas a limites específicos do espaço de trabalho.
• Conteúdo SQL: Consultar texto em sql campos e join_specs.sql está sujeito a limites de comprimento.

Formato de especificações de junção

O sql campo em cada especificação de junção deve conter exatamente dois elementos:

1. A condição de junção, usando referências de alias com aspas `backtick`:

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

2. Uma anotação de tipo de relação no seguinte formato:

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

   Valores válidos de cardinalidade:

   • FROM_RELATIONSHIP_TYPE_MANY_TO_ONE
   • FROM_RELATIONSHIP_TYPE_ONE_TO_MANY
   • FROM_RELATIONSHIP_TYPE_ONE_TO_ONE
   • FROM_RELATIONSHIP_TYPE_MANY_TO_MANY

Omitir a anotação do tipo de relação faz com que a API rejeite o pedido com um erro de análise sintática. Para junções multi-colunas, crie uma especificação de junção separada para cada relação.

Outros requisitos

• Identificadores de tabela: Deve usar o formato de namespace de três níveis (catalog.schema.table).
• Respostas de benchmark: Cada pergunta de benchmark deve ter exatamente uma resposta com o formato definido para SQL.
• Excertos de SQL: Os campos SQL de filtro, expressão e medida não devem estar vazios.

Referência da API Genie

As secções anteriores mostram como preparar um Agente Genie e gerir agentes em vários espaços de trabalho. Para iniciar conversas, enviar mensagens e recuperar resultados dos Agentes Genie, consulte a referência da API REST:

• APIs do modo Agente: Envie prompts no modo Agente, transmita o seu raciocínio e resultados SQL, e receba os relatórios finais com citações. Consulte a referência da API do modo Agente.
• APIs do modo Chat: Inicie uma conversa no modo Chat, faça perguntas de seguimento e recupere SQL gerado, resultados de consultas e visualizações. Consulte a referência da API de conversação.

Boas práticas e limites

Boas práticas para usar a API do Genie

Para manter o desempenho e a confiabilidade ao usar a API do Genie:

• Implementa lógica de retentativa com backoff exponencial: A API não reenvia automaticamente pedidos falhados, por isso adiciona o teu próprio sistema de fila e backoff exponencial. Isto ajuda a sua aplicação a lidar com falhas transitórias e a evitar pedidos repetidos desnecessários à medida que cresce.
• Registar respostas da API: Implementar registos abrangentes dos pedidos e respostas da API para ajudar na depuração, monitorização de padrões de utilização e acompanhamento de custos.
• Solicite atualizações de estado a cada 1 a 5 segundos: Continue a sondagem até que seja recebido um estado conclusivo da mensagem, como COMPLETED, FAILED, ou CANCELLED, Limite a sondagem a 10 minutos para a maioria das consultas. Se não houver uma resposta conclusiva após 10 minutos, pare a sondagem e retorne um erro de tempo limite ou solicite que o usuário verifique manualmente o status da consulta mais tarde.
• Use o recuo exponencial para sondagens: aumente o atraso entre sondagens até um máximo de um minuto. Isto reduz pedidos desnecessários para consultas de longa duração, permitindo ainda assim baixa latência para consultas rápidas.
• Inicie uma nova conversa para cada sessão: Evite reutilizar tópicos de conversa entre sessões, pois isso pode reduzir a precisão devido à reutilização não intencional do contexto.
• Mantenha os limites de conversa: Para gerir conversas antigas e manter-se abaixo do limite de 10.000 conversas:
  1. Utilize o ponto final GET /api/2.0/genie/spaces/{space_id}/conversations para ver todas as conversas existentes num agente.
  2. Identifique conversas que não são mais necessárias, como conversas mais antigas ou conversas de teste.
  3. Use o DELETE /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id} endpoint para remover conversas programaticamente.

Monitorizar o agente

Depois que seu aplicativo for configurado, você poderá monitorar perguntas e respostas na interface do usuário do Databricks.

Incentive os utilizadores a testar o agente para que saiba sobre os tipos de perguntas que provavelmente farão e as respostas que recebem. Forneça aos utilizadores orientações para os ajudar a começar a testar o agente. Use a guia Monitoramento para exibir perguntas e respostas. Veja Monitorizar o agente.

Também pode usar registos de auditoria para monitorizar a atividade num Agente Genie. Veja os eventos do Genie Agent.