Pular para o conteúdo principal
Última atualização em

Use a API do Genie Agents

Integre os Genie Agents em seu próprio chatbot, agente ou aplicativo com a API do Genie Agents. A API fornece APIs de Conversação para consulta de dados em linguagem natural com estado (com perguntas de acompanhamento e histórico) e APIs de Gerenciamento para fluxos de trabalho de CI/CD que criam, configuram e implantam Genie Agents em Workspace.

nota

Genie Agents eram anteriormente conhecidos como Genie Spaces.

Visão geral​

A API do Genie fornece dois tipos de recursos:

  • APIs de Conversa : Habilitam consultas de dados em linguagem natural em aplicativos, chatbots e estruturas de agente de AI. Essas APIs suportam conversas com estado onde os usuários podem fazer perguntas de acompanhamento e explorar dados naturalmente ao longo do tempo.
  • APIs de gerenciamento : Permitem a criação, configuração e implantação programáticas de Genie Agents em workspaces. Use estas APIs para pipelines de CI/CD, controle de versão e gerenciamento automatizado de agentes.

Esta página descreve tanto as APIs de conversação quanto as de gerenciamento. Antes de chamar as APIs de conversação, prepare um Genie Agent bem-curado. 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 poderão ainda receber resultados incorretos mesmo com uma integração de API correta. Este guia explica a configuração mínima necessária para criar um agente que funcione efetivamente com a API do Genie.

Os exemplos desta página usam a REST API diretamente. O senhor também pode chamar essas APIs usando os SDKs da Databricks. Consulte SDKs da Databricks.

Pré-requisitos​

Para usar a API Genie, é necessário ter:

  • Acesso a um workspace Databricks com direito ao Databricks SQL.
  • No mínimo privilégios CAN USE em um SQL warehouse profissional ou serverless.

Começar​

Configure a autenticação do Databricks​

Para casos de uso de produção onde 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 Service Principal para autenticar com a API. Consulte OAuth para Service Principal (OAuth M2M). Service Principal devem ter permissões para acessar os dados necessários e SQL warehouses.

Coletar detalhes​

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

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

  • ID do Warehouse : você precisa do ID de um SQL warehouse no qual você tenha, no mínimo, privilégios CAN USE. Para encontrar o ID do seu warehouse:

    1. Acesse **SQL Warehouses** no seu workspace.
    2. Selecione o warehouse que deseja usar.
    3. Copie o ID do warehouse da URL ou da página de detalhes do warehouse.

    Alternativamente, utilize o Endpoint List warehouse GET /api/2.0/sql/warehouses para recuperar programaticamente uma lista de todos os SQL warehouse aos quais o usuário tem permissão para acessar. A resposta inclui o ID do warehouse.

Criar ou selecionar um Genie Agent​

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

  • Usa dados bem anotados : O Genie se baseia em metadados da tabela e comentários de coluna. Verifique se suas fontes de dados do Unity Catalog têm comentários claros e descritivos.
  • O usuário é testado : Teste seu agente fazendo perguntas que você espera dos usuários finais. Use testes para criar e refinar exemplos de queries SQL.
  • Inclui contexto específico da empresa : Adicione instruções, exemplos de SQL e funções. Consulte Adicionar exemplos e instruções SQL. Busque pelo menos cinco queries SQL de exemplo testadas.
  • Usa benchmarks para testar a precisão : Adicione pelo menos cinco perguntas de benchmark com base nas perguntas antecipadas do usuário. Consulte Benchmarks.

Para obter mais informações sobre como criar um agente, consulte Criar e Gerenciar um Genie Agent e Organizar um Genie Agent Eficaz.

Crie um novo Genie Agent ou utilize um existente:

Crie um Genie Agent programaticamente usando a API Criar Genie Agent. O exemplo a seguir demonstra um agente bem-estruturado que segue as melhores práticas. Substitua os valores temporários pelos seus:

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

Entender o campo serialized_space​

O campo serialized_space é uma string JSON que define a configuração e as fontes de dados para o seu Genie Agent. Na solicitação da API, este JSON deve ser escapado como uma string. O campo contém:

  • Versão : Número da versão do esquema para compatibilidade com versões anteriores. Use 2 conforme mostrado no exemplo abaixo.

  • config : Configuração do agente, incluindo:

    • sample_questions : Perguntas de exemplo para guia os usuários. Cada pergunta requer um id (string hexadecimal de 32 caracteres) e question (array de strings).

  • data_sources : Fontes de dados disponíveis para o agente:

    • tables: Matriz de objetos de tabela com **identificador** (namespace de três níveis), **descrição** opcional e **column_configs** opcionais.
    • metric_views : Array de objetos de view de métricas (mesma estrutura que 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 : Relacionamentos de join pré-definidos entre tabelas. O campo sql requer exatamente dois elementos: a condição de join, usando referências de alias entre crases, e uma anotação de tipo de relacionamento, por exemplo "--rt=FROM_RELATIONSHIP_TYPE_MANY_TO_ONE--". Consulte Formato das especificações de join.
    • sql_snippets : Filtros , expressões e medidas reutilizáveis.

  • benchmarks : perguntas para avaliar a qualidade do agente, cada uma com uma resposta SQL de base verdadeira.

A versão sem escape do campo serialized_space do exemplo de criação de agente é semelhante a:

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

Ao construir seu agente, crie esta estrutura JSON e, em seguida, escape-a como uma string para a solicitação da API. Para obter detalhes completos do esquema, consulte a referência da API de criação do Genie Agent.

Regras de validação para serialized_space​

O JSON serialized_space deve estar em conformidade com 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 Versão : Obrigatório. Use 2 para novos agentes. O número da versão existe para compatibilidade com versões anteriores.

formato de ID​

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

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

IDs são necessários 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 benchmarks forem incluídos)

Você pode usar o seguinte comando para gerar um ID válido:

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

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

Requisitos de ordenação​

Coleções que contêm IDs ou identificadores devem ser pré-classificadas. O sistema valida que os arrays já estão classificados e rejeita entradas não classificadas.

Coleção

Chave de classificação

data_sources.tables

identifier (em ordem alfabética)

data_sources.metric_views

identifier (em ordem alfabética)

data_sources.tables[].column_configs

column_name (em ordem alfabética)

data_sources.metric_views[].column_configs

column_name (em ordem alfabética)

config.sample_questions

id (em ordem alfabética)

instructions.text_instructions

id (em ordem alfabética)

instructions.example_question_sqls

id (em ordem alfabética)

instructions.sql_functions

(id, identifier) tupla (em ordem alfabética)

instructions.join_specs

id (em ordem alfabética)

instructions.sql_snippets.filters

id (em ordem alfabética)

instructions.sql_snippets.expressions

id (em ordem alfabética)

instructions.sql_snippets.measures

id (em ordem alfabética)

benchmarks.questions

id (em ordem alfabética)

Coleção

Chave de classificação

data_sources.tables

identifier (em ordem alfabética)

data_sources.metric_views

identifier (em ordem alfabética)

data_sources.tables[].column_configs

column_name (em ordem alfabética)

data_sources.metric_views[].column_configs

column_name (em ordem alfabética)

config.sample_questions

id (em ordem alfabética)

instructions.text_instructions

id (em ordem alfabética)

instructions.example_question_sqls

id (em ordem alfabética)

instructions.sql_functions

(id, identifier) tupla (em ordem alfabética)

instructions.join_specs

id (em ordem alfabética)

instructions.sql_snippets.filters

id (em ordem alfabética)

instructions.sql_snippets.expressions

id (em ordem alfabética)

instructions.sql_snippets.measures

id (em ordem alfabética)

benchmarks.questions

id (em ordem alfabética)

Restrições de unicidade​

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

Limites de tamanho e comprimento​

  • Comprimento da string : Os elementos individuais da string são limitados a 25.000 caracteres.
  • Tamanho do array: 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 views de métricas : Sujeito a limites específicos do Workspace.
  • Conteúdo SQL : o texto da query nos campos sql e join_specs.sql está sujeito a limites de comprimento.

Formato de especificações de join​

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

  1. A condição de join, usando referências de alias entre acentos graves:

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

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

    Text
    "--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 do tipo de relacionamento faz com que a API rejeite a solicitação com um erro de análise. Para joins de várias colunas, crie uma especificação de join separada para cada relacionamento.

Outros requisitos​

  • Identificadores de tabela : devem 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 como SQL.
  • **Snippets de SQL**: Os campos de SQL de filtro, expressão e medida não devem estar vazios.

Como usar a API de conversação​

Após configurar um Genie Agent, utilize os endpoints da API de conversa para fazer perguntas, recuperar resultados e manter conversas em vários turnos com contexto.

Iniciar uma conversa​

O Endpoint 'Iniciar conversa' POST /api/2.0/genie/spaces/{space_id}/start-conversation inicia uma nova conversa em seu Genie Agent.

Substitua os espaços reservados pela sua instância do Databricks, ID do Genie Agent e token de autenticação. Um exemplo de resposta bem-sucedida segue a solicitação. Inclui detalhes que podem ser usados para acessar esta conversa novamente para perguntas de acompanhamento.

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

Recuperar SQL gerado​

Use conversation_id e message_id na resposta para consultar e verificar o status de geração da mensagem e recuperar o SQL gerado do Genie. Consulte GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id} para obter detalhes completos da solicitação e da resposta.

Substitua seus valores na seguinte solicitação:

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

A seguinte resposta de exemplo relata os detalhes da mensagem:

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
}

O campo attachments é progressivamente preenchido durante o processamento. Quando o status for PENDING_WAREHOUSE ou EXECUTING_QUERY, o usuário já pode começar a ler o campo attachments. A resposta é preenchida de forma incremental, começando com a query SQL gerada, seguida pela descrição, perguntas de acompanhamento e contexto adicional. O status COMPLETED indica que o processo de resposta foi totalmente concluído e a consulta pode parar, mas o conteúdo significativo está disponível mais cedo se o seu cliente inspecionar a resposta durante a consulta, em vez de esperar pela conclusão.

Para determinar se uma resposta foi gerada usando um ativo confiável, verifique o campo attachments na resposta para um objeto query.parameters. Sua presença indica que a resposta veio de um ativo confiável.

Para acessar os rastreamentos de raciocínio do Genie, verifique o campo attachments para um objeto query_attachments do tipo GenieQueryAttachments. Quando presente, ele contém o raciocínio passo a passo que o Genie usou para gerar a resposta. Para obter detalhes completos do campo, consulte a referência da API Obter Mensagem.

Recuperar resultados de query​

O array attachments contém a resposta do Genie. Inclui a resposta de texto gerada (text), a instrução de query, se existir (query), e um identificador que pode ser usado para obter os resultados da query associada (attachment_id). Substitua os espaços reservados no exemplo a seguir para recuperar os resultados da query gerada:

nota

Ao contrário da UI dos Genie Agents, a API de Conversa Genie não suporta o padrão de resposta de duas fases, onde o Genie mostra uma resposta preliminar e depois a atualiza após a inspeção. Para exibir o progresso incremental aos usuários, inspecione o campo attachments enquanto faz polling durante os estados PENDING_WAREHOUSE ou EXECUTING_QUERY, em vez de aguardar por COMPLETED.

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

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

Recuperar resultados da visualização (Beta)​

Por default, a API de conversa do Genie retorna resultados de query tabulares. Para também recuperar resultados de visualização, defina enable_visualization: true ao começar uma conversa ou criar uma mensagem. Quando ativado, o campo attachments na resposta inclui um objeto viz do tipo GenieVizAttachment contendo a visualização title e o query_attachment_id do qual foi gerado.

Para fazer download da visualização, use o endpoint de visualização de anexo da mensagem 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>

Consulte a referência da API Genie.

nota

Resultados de visualização não são suportados para Workspace com Private Link.

Fazer perguntas de acompanhamento​

Depois que receber uma resposta, use conversation_id para continuar a conversa. O contexto das mensagens anteriores é retido e usado em respostas de acompanhamento. Para obter detalhes completos da solicitação e da resposta, consulte 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?",
}

Adicionar comentários às mensagens​

Você pode adicionar comentários de texto a mensagens e listar comentários existentes usando os Endpoint da API de comentários de mensagem.

Para adicionar um comentário a uma mensagem, use o Endpoint de criação de comentário de mensagem 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>"
}

Para listar comentários existentes em uma mensagem, use o Endpoint de listagem de comentários de mensagens.

Recuperar dados de agente e conversa​

A API Genie fornece endpoints adicionais para recuperar configuração e data histórica de agentes e conversas existentes.

Recuperar configuração do agente​

Ao recuperar informações do agente usando a API Get Genie Agent, você pode incluir o campo serialized_space na resposta definindo o parâmetro include_serialized_space como true. O campo serialized_space contém a representação de string serializada do Genie Agent, incluindo instruções, benchmarks, joins e outros detalhes de configuração.

Use esta representação serializada com a API Criar Genie Agent e a API Atualizar Genie Agent para promover Genie Agents entre workspaces ou criar backups de configurações de agente.

Exemplo de solicitação 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\"]}]"
}

Consulte históricos de conversas antigas​

Para permitir que os usuários se refiram a conversas antigas, utilize o Endpoint de mensagens de conversas de lista GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages para recuperar todas as mensagens de uma conversa específica.

Recuperar dados de conversa para análise​

Os gerentes de agente podem recuperar programaticamente todas as mensagens anteriores solicitadas por todos os usuários de um agente para análise. Para recuperar estes dados:

  1. Use o endpoint GET /api/2.0/genie/spaces/{space_id}/conversations para obter todos os tópicos de conversa existentes em um agente.

    • Por default, este endpoint retorna apenas as conversas do usuário solicitante. Para retornar conversas de todos os usuários no agente, defina o parâmetro include_all como true. O uso de include_all requer pelo menos permissão CAN MANAGE no agente.

  2. Para cada ID de conversa retornada, use o Endpoint GET /api/2.0/genie/spaces/{space_id}/conversations para recuperar a lista de mensagens para essa conversa.

Práticas recomendadas e limites​

Melhores Práticas para Usar a API Genie​

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

  • Implementar lógica de repetição com backoff exponencial : A API não tenta novamente as solicitações com falha para você, então adicione seu próprio enfileiramento e backoff exponencial. Isso ajuda seu aplicativo a lidar com falhas transitórias e a evitar solicitações repetidas desnecessárias à medida que cresce.
  • **Registrar respostas da API**: Implemente o registro abrangente de solicitações e respostas da API para auxiliar na depuração, no monitoramento de padrões de uso e no acompanhamento de custos.
  • Consulte atualizações de status a cada 1 a 5 segundos : Continue consultando até que um status de mensagem conclusivo, como COMPLETED, FAILED ou CANCELLED, seja recebido. Limite a consulta a 10 minutos para a maioria das queries. Se não houver uma resposta conclusiva após 10 minutos, pare de consultar e retorne um erro de tempo limite ou solicite ao usuário que verifique o status da query manualmente mais tarde.
  • Use backoff exponencial para consulta: Aumente o atraso entre as consultas até um máximo de um minuto. Isso reduz solicitações desnecessárias para queries de longa duração, ao mesmo tempo em que permite baixa latência para as 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.
  • Manter limites de conversa : para gerenciar conversas antigas e permanecer dentro do limite de 10.000 conversas:
    1. Use o GET /api/2.0/genie/spaces/{space_id}/conversations endpoint para ver todos os tópicos de conversa existentes em um agente.
    2. Identifique conversas que não são mais necessárias, como conversas mais antigas ou conversas de teste.
    3. Use o Endpoint DELETE /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id} para remover conversas programaticamente.

Monitore o agente​

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

Incentive os usuários a testar o agente para que você possa aprender sobre os tipos de perguntas que provavelmente farão e as respostas que receberão. Forneça aos usuários orientação para ajudá-los a começar a testar o agente. Use a Monitoramento tab para ver perguntas e respostas. Consulte Monitorar o agente.

Você também pode usar logs de auditoria para monitorar a atividade em um Genie Agent. Consulte eventos do Genie Agent.

Nesta página