Usar a API de Agentes do Genie

Integre o Genie Agents ao seu próprio chatbot, agente ou aplicativo com a API do Genie Agents. A API oferece APIs do modo Chat para consultas de dados em linguagem natural com estado (com perguntas e histórico subsequentes) e APIs de Gerenciamento para fluxos de trabalho CI/CD que criam, configuram e implantam Agentes Genie em ambientes de trabalho.

Visão geral

A API do Genie oferece os seguintes tipos de capacidades:

• APIs do modo chat: Habilitar consultas de dados em linguagem natural em aplicativos, chatbots e frameworks de agentes. Essas APIs suportam conversas com estado criadas no modo Chat, onde os usuários podem fazer perguntas de acompanhamento e explorar dados naturalmente ao longo do tempo.
• APIs do modo Agente: Permitem que os desenvolvedores enviem prompts programaticamente no modo Agente, transmitam os resultados de raciocínio e SQL, e recebam relatórios finais com citações.
• APIs de gerenciamento: habilite a criação, a configuração e a implantação programáticas dos Agentes do Genie em workspaces. Use essas APIs para pipelines de CI/CD, controle de versão e gerenciamento automatizado de agente.

Esta página explica como preparar um Agente Genie bem selecionado e gerenciar agentes entre os espaços de trabalho para que a API retorne resultados confiáveis. O agente fornece o contexto que o Genie usa para interpretar perguntas e gerar respostas. Se o agente estiver incompleto ou não testado, os usuários ainda poderão receber resultados incorretos mesmo com uma integração de API correta. Para os endpoints de runtime, formatos de requisição e formatos de resposta, veja a referência da API REST vinculada na referência da API do Genie.

Os exemplos de configuração nesta página usam diretamente a API REST. Você também pode chamar essas APIs usando os SDKs de Azure Databricks. Consulte os SDKs do Databricks.

Pré-requisitos

Para usar a API do Genie, você deve ter:

• Acesso a um workspace do Azure Databricks com o direito Databricks SQL.
• Pelo menos privilégios CAN USE em um warehouse SQL Pro ou SQL sem servidor.

Como começar

Configurar a autenticação do 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, use um principal de serviço para autenticar na API. Consulte o 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 depósitos SQL.

Reunir detalhes

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

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

• ID do warehouse: você precisa da ID de um SQL Warehouse no qual você tenha pelo menos privilégios DE USO. Para localizar a ID do seu armazém:

  1. Vá para SQL Warehouses em seu workspace.
  2. Selecione o armazém que você deseja usar.
  3. Copie o ID do warehouse do URL ou da página de detalhes do warehouse.

  Como alternativa, use o ponto de extremidade Listar warehousesGET /api/2.0/sql/warehouses para obter programaticamente uma lista de todos os SQL Warehouses que você tem permissões para acessar. A resposta inclui a identificação do armazém.

Criar ou selecionar um agente do Genie

Um Agente Genie bem estruturado tem as seguintes características:

• Usa dados bem anotados: o Genie depende de metadados de tabela e comentários de coluna. Verifique se as fontes de dados do Catálogo do Unity têm comentários claros e descritivos.
• É testado por usuários: teste seu agente fazendo as perguntas que você espera que os usuários finais façam. Use o teste para criar e refinar consultas SQL de exemplo.
• Inclui contexto específico da empresa: adicionar instruções, exemplo de SQL e funções. Consulte Adicionar exemplos e instruções do SQL. Tenha como objetivo pelo menos cinco consultas SQL testadas como exemplo.
• Usa parâmetros de comparação para testar a precisão: adicione pelo menos cinco perguntas de parâmetro de comparação com base nas perguntas do usuário previstas. Consulte Benchmarks.

Para obter mais informações sobre como criar um agente, consulte Criar e gerenciar um Genie Agent e Selecionar e organizar um Genie Agent eficaz.

Você pode criar um novo Agente do Genie ou usar um existente:

Criar um novo agente

Crie um Agente Genie programaticamente usando a API Create Genie Agent. O exemplo a seguir demonstra um agente bem estruturado que segue as práticas recomendadas. 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"
}

Usar um agente existente

Se já tiver um agente do Genie, você poderá encontrar a ID do espaço usando a API de agentes Listar Genie. Você também pode encontrar e copiar o ID do espaço na guia Configurações do 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>",
    }
  ]
}

Use o space_id da resposta em chamadas subsequentes de API.

Noções básicas sobre o campo serialized_space

O serialized_space campo é uma cadeia de caracteres JSON que define a configuração e as fontes de dados do Genie Agent. Na solicitação de API, esse JSON deve ser tratado como uma cadeia de caracteres. O campo contém:

• versão: número de versão do esquema para compatibilidade com versões anteriores. Use 2 conforme mostrado no exemplo abaixo.
• configuração: Configuração do agente, incluindo:
  • sample_questions: Perguntas de exemplo para orientar os usuários. Cada pergunta requer uma ID (cadeia de caracteres hexáxe de 32 caracteres) e uma pergunta (matriz de cadeias de caracteres).
• data_sources: fontes de dados disponíveis para o agente:
  • tabelas: Matriz de objetos de tabela com identificador (namespace de três níveis), descrição opcional e column_configs opcional.
  • metric_views: matriz de objetos de exibição de métrica (mesma estrutura que tabelas).
• instruções: instruções estruturadas para o agente:
  • text_instructions: diretrizes de alto nível para a 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 predefinidas entre tabelas. O campo sql requer exatamente dois elementos: a condição de junção, usando referências de alias entre crases e uma anotação de tipo de relação, por exemplo "--rt=FROM_RELATIONSHIP_TYPE_MANY_TO_ONE--". Consulte o formato de especificações de junção.
  • sql_snippets: filtros reutilizáveis, expressões e medidas.
• parâmetros de comparação: perguntas para avaliar a qualidade do agente, cada uma com uma resposta SQL de verdade básica.

A versão sem escape do campo serialized_space do exemplo de criar agente parece:

{
  "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 seu agente, crie essa estrutura JSON e escape-a como uma cadeia de caracteres para a solicitação de API. Para obter 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 estar em conformidade com as regras de validação a seguir. JSON que não é válido é rejeitado durante a criação ou atualização do agente.

Versão

• Campo de versão: Obrigatório. Use 2 para novos agentes. O número de versão existe para compatibilidade com versões anteriores.

Formato de ID

Todos os campos de ID devem ser cadeias de caracteres hexadecimal minúsculas de 32 caracteres (formato UUID sem hifens).

• Válido: a1b2c3d4e5f60000000000000000000a
• Não válido: a1b2c3d4e5f6 (muito curto), A1B2C3D4E5F60000000000000000000A (maiúsculas) a1b2c3d4-e5f6-0000-0000-00000000000a (contém hifens)

As IDs são necessá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 parâmetros de comparação forem incluídos)

Você pode usar o seguinte comando para gerar uma ID válida:

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

Isso gera uma UUID ordenada por tempo. As IDs geradas em sequência classificam em ordem alfabética na ordem em que foram criadas, o que atende automaticamente aos requisitos de classificação .

Requisitos de classificação

Coleções que contêm IDs ou identificadores devem ser pré-classificadas. O sistema valida que as matrizes já estão classificadas e rejeita a entrada não classificada.

Restrições de exclusividade

• IDs de pergunta: todas as IDs em config.sample_questions e benchmarks.questions devem ser únicas nas duas coleções.
• IDs de instrução: todos as IDs entre text_instructions, example_question_sqls, sql_functionse join_specstodos os sql_snippets tipos devem ser exclusivos.
• Configurações de coluna: a combinação de (table_identifier, column_name) deve ser única no agente.

Limites de tamanho e comprimento

• Comprimento da cadeia de caracteres: os elementos de cadeia de caracteres individuais são limitados a 25.000 caracteres.
• Tamanho da matriz: os campos repetidos são limitados a 10.000 itens.
• Instruções de texto: no máximo 1 instrução de texto é permitida por agente.
• Tabelas e exibições de métrica: sujeito a limites específicos da área de trabalho.
• Conteúdo do SQL: o texto da consulta nos campos sql 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 invertidas:

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

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

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

   Valores de cardinalidade válidos:

   • FROM_RELATIONSHIP_TYPE_MANY_TO_ONE
   • FROM_RELATIONSHIP_TYPE_ONE_TO_MANY
   • FROM_RELATIONSHIP_TYPE_ONE_TO_ONE
   • FROM_RELATIONSHIP_TYPE_MANY_TO_MANY

Omitir a anotação de tipo de relação faz com que a API rejeite a solicitação com um erro de análise. Para junções de várias 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 parâmetro de comparação: cada pergunta de parâmetro de comparação deve ter exatamente uma resposta com o formato definido como SQL.
• Snippets de SQL: os campos SQL de filtragem, expressão e medida não devem estar vazios.

Referência da API do Genie

As seções anteriores mostram como preparar um Agente Genie e gerenciar agentes em diferentes espaços de trabalho. Para iniciar conversas, enviar mensagens e recuperar resultados dos Agentes Genie, veja a referência da API REST:

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

Melhores práticas e limites

Práticas recomendadas para usar a API do Genie

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

• Implemente a lógica de repetição com recuo exponencial: a API não tenta novamente solicitações com falha para você, portanto, adicione sua própria lógica de fila e recuo exponencial. Isso ajuda seu aplicativo a lidar com falhas transitórias e evitar solicitações de repetição desnecessárias à medida que cresce.
• Registre as respostas da API: Implemente o registro detalhado das solicitações e respostas da API para ajudar na depuração, monitoramento de padrões de uso e rastreamento de custos.
• Sondagem para atualizações de status a cada 1 a 5 segundos: Continue a sondagem até que um status de mensagem conclusiva, como COMPLETED, FAILEDou CANCELLED, seja recebido. Limite a sondagem para 10 minutos para a maioria das consultas. Se não houver resposta conclusiva após 10 minutos, interrompa a sondagem e retorne um erro de tempo limite ou solicite que o usuário verifique manualmente o status da consulta mais tarde.
• Use a estratégia de espera exponencial para consultas: aumente o atraso entre as consultas até um máximo de um minuto. Isso reduz solicitações desnecessárias para consultas de longa execução, permitindo ainda baixa latência para consultas rápidas.
• Inicie uma nova conversa para cada sessão: evite reutilizar threads de conversa entre sessões, pois isso pode reduzir a precisão devido à reutilização de contexto não intencional.
• Manter limites de conversa: para gerenciar conversas antigas e ficar abaixo do limite de 10.000 conversas:
  1. Use o endpoint GET /api/2.0/genie/spaces/{space_id}/conversations para ver todos os tópicos de conversa existentes de um agente.
  2. Identifique conversas que não são mais necessárias, como conversas mais antigas ou conversas de teste.
  3. Utilize o DELETE /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id} endpoint para remover conversas programaticamente.

Monitorar o agente

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

Incentive os usuários a testar o agente para que você aprenda sobre os tipos de perguntas que eles provavelmente farão e as respostas que recebem. Forneça aos usuários orientações para ajudá-los a começar a testar o agente. Use a guia Monitoramento para exibir perguntas e respostas. Consulte Monitorar o agente.

Você também pode usar logs de auditoria para monitorar as atividades de um Agente do Genie. Veja os eventos do agente Genie.