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

Use a API de Genie Agents

Integre os Genie Agents em seu próprio chatbot, agente ou aplicativo com a API dos 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 workspaces.

nota

Os Genie Agents eram anteriormente conhecidos como Genie Spaces.

Visão geral​

A API Genie oferece dois tipos de funcionalidades:

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

Esta página descreve as APIs de conversação e gerenciamento. Antes de chamar as APIs de conversação, prepare um Genie Agent bem selecionado. 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. Este guia explica a configuração mínima necessária para criar um agente que funcione efetivamente com a API do Genie.

Os exemplos nesta página utilizam a API REST diretamente. Você também pode chamar essas APIs usando os SDKs do Databricks. Consulte os SDKs do Databricks.

Pré-requisitos​

Para usar a API Genie, você precisa ter:

  • Acesso a um Databricks workspace com o direito Databricks SQL.
  • Pelo menos os privilégios CAN USE em um SQL pro ou serverless SQL warehouse.

Começando​

Configurar autenticação do Databricks​

Para casos de uso em produção onde um usuário com acesso a um navegador esteja presente, utilize OAuth para usuários (OAuth U2M). Em situações onde a autenticação baseada em navegador não é possível, utilize uma entidade de serviço para autenticar com a API. Consulte OAuth para entidade de serviço (OAuth M2M). A entidade de serviço deve ter permissões de acesso aos dados necessários e ao banco de dados SQL .

Reúna os detalhes​

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

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

  • ID do Warehouse : Você precisa do ID de um SQL warehouse no qual você tenha pelo menos privilégios de CAN USE. Para encontrar o ID do seu armazém:

    1. Acesse o SQL Warehouse em seu workspace.
    2. Selecione o armazém que deseja utilizar.
    3. Copie o ID do armazém a partir do URL ou da página de detalhes do armazém.

    Alternativamente, use o endpointList warehouses GET /api/2.0/sql/warehouses para recuperar programaticamente uma lista de todos os warehouses SQL aos quais você tem permissão de acesso. A resposta inclui o ID do armazém.

Criar ou selecionar um Genie Agent​

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

  • Utiliza dados bem anotados : Genie depende de metadados de tabelas e comentários de colunas. Verifique se sua fonte de dados Unity Catalog possui comentários claros e descritivos.
  • 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 os exemplos e instruções para adicionar SQL. Procure criar pelo menos cinco exemplos de consultas SQL testadas.
  • Utiliza parâmetros de referência para testar a precisão : Adicione pelo menos cinco perguntas de referência com base em perguntas previstas dos usuários. Consulte os indicadores de desempenho.

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

É possível criar um novo Genie Agent ou usar 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 placeholders 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"
}

Entendendo o campo serialized_space​

O campo serialized_space é uma string JSON que define a configuração e as fontes de dados para 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 fins de compatibilidade com versões anteriores. Use 2 conforme mostrado no exemplo abaixo.

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

    • sample_questions : Exemplos de perguntas para guiar os usuários. Cada pergunta requer um ID (cadeia hexadecimal de 32 caracteres) e uma pergunta (matriz de strings).

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

    • tables : Array de objetos de tabela com identificador (namespace de três níveis), descrição opcional e configurações de coluna opcionais.
    • metric_views : Array de objetos view de métricas (mesma estrutura das tabelas).

  • instruções : Instruções estruturadas para o agente:

    • text_instructions : Orientações gerais para o LLM.
    • example_question_sqls : Exemplos de perguntas com respostas em SQL, opcionalmente com parâmetros e orientações de uso .
    • funções SQL : Referências a funções SQL disponíveis para o agente.
    • join_specs : Relações join predefinidas entre tabelas. O campo sql requer exatamente dois elementos: a condição 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--". Veja o formato das especificações de junção.
    • sql_snippets : Filtros , expressões e medidas reutilizáveis.

  • benchmarks: Perguntas para avaliar a qualidade do agente, cada uma com uma resposta SQL da verdade fundamental.

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

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 o seu agente, crie esta estrutura JSON e, em seguida, faça o escape dela como uma string para a solicitação da API. Para obter detalhes completos do esquema, consulte a referência da API Criar Genie Agent.

Regras de validação para espaço serializado​

O JSON serialized_space deve estar em conformidade com as seguintes regras de validaçã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 stringshexadecimais de 32 caracteres em minúsculas (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 hífens)

Documentos de identificação 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 os benchmarks estiverem 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}')"

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

Requisitos de classificação​

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

Coleção

keyde classificação

data_sources.tables

identifier (alfabeticamente)

data_sources.metric_views

identifier (alfabeticamente)

data_sources.tables[].column_configs

column_name (alfabeticamente)

data_sources.metric_views[].column_configs

column_name (alfabeticamente)

config.sample_questions

id (alfabeticamente)

instructions.text_instructions

id (alfabeticamente)

instructions.example_question_sqls

id (alfabeticamente)

instructions.sql_functions

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

instructions.join_specs

id (alfabeticamente)

instructions.sql_snippets.filters

id (alfabeticamente)

instructions.sql_snippets.expressions

id (alfabeticamente)

instructions.sql_snippets.measures

id (alfabeticamente)

benchmarks.questions

id (alfabeticamente)

restrições de unicidade​

  • IDs das 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 os tipos sql_snippets devem ser únicos.
  • Configurações de coluna : A combinação de (table_identifier, column_name) deve ser única dentro do agente.

Limites de tamanho e comprimento​

  • Comprimento das strings : Os elementos individuais das strings são limitados a 25.000 caracteres.
  • Tamanho da matriz : Os campos repetidos estão limitados a 10.000 itens.
  • Instruções de texto : É permitida no máximo 1 instrução de texto por agente.
  • Visualização de tabelas e métricas : Sujeita a limites específicos workspace .
  • Conteú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 campo sql em cada especificação join deve conter exatamente dois elementos :

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

    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 junções com múltiplas colunas, crie uma especificação 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 referência : Cada questão de referência deve ter exatamente uma resposta com o formato definido como SQL.
  • Trechos de SQL : Os campos SQL de filtro, expressão e medida não devem estar vazios.

Usando a API de conversação​

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

iniciar uma conversa​

O endpoint Começar conversa POST /api/2.0/genie/spaces/{space_id}/start-conversation inicia uma nova conversa no seu Genie Agent.

Substitua os placeholders pela sua instância Databricks, ID do Genie Agent e token de autenticação. Um exemplo de resposta bem-sucedida segue a solicitação. Ele 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 os endereços conversation_id e message_id na resposta à pesquisa para 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>

O exemplo de resposta a seguir 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 é preenchido progressivamente durante o processamento. Quando o status for PENDING_WAREHOUSE ou EXECUTING_QUERY, você já pode começar a ler o campo attachments . A resposta é preenchida incrementalmente, começando com a consulta 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 sondagem pode ser interrompida, mas o conteúdo significativo está disponível mais cedo se o seu cliente inspecionar a resposta durante a sondagem 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 usuário ativo confiável.

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

Recuperar resultados da consulta​

A matriz attachments contém a resposta do Genie. Ela inclui a resposta de texto gerada (text), a instrução de consulta, se existir (query), e um identificador que você pode usar para obter os resultados da consulta associada (attachment_id). Substitua os espaços reservados no exemplo a seguir para recuperar os resultados da consulta gerada:

nota

Ao contrário da UI dos Genie Agents, a API de Conversação do 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 mostrar progresso incremental aos usuários, inspecione o campo attachments durante o polling nos estados PENDING_WAREHOUSE ou EXECUTING_QUERY em vez de esperar 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ção do Genie retorna resultados de consulta 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 baixar a visualização, use o endpoint de visualização de anexo de 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

Os resultados da visualização não são compatíveis com workspaces com Private Link.

Faça perguntas de acompanhamento.​

Depois de receber uma resposta, use o conversation_id para continuar a conversa. O contexto das mensagens anteriores é mantido e usado nas 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 às mensagens e listar os comentários existentes usando o endpoint API de comentários de mensagens.

Para adicionar um comentário a uma mensagem, use o endpoint Criar 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 os comentários existentes em uma mensagem, use o endpoint Listar comentários da mensagem.

Recuperar dados do agente e da conversa​

A API Genie oferece endpoints adicionais para recuperar a 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 das configurações do 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 tópicos de conversa antigos​

Para permitir que os usuários consultem tópicos de conversa antigos, use o endpoint List conversation messages GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages para recuperar todas as mensagens de um tópico de conversa específico.

Recuperar dados de conversas para análise​

Gerentes de agente podem recuperar programaticamente todas as mensagens anteriores feitas 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 threads 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 permissão CAN MANAGE, no mínimo, no agente.

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

Melhores práticas 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 solicitações com falha para você, então adicione sua própria fila e backoff exponencial. Isso ajuda seu aplicativo a lidar com falhas transitórias e a evitar solicitações repetidas desnecessárias à medida que ele cresce.
  • Registrar respostas API : Implemente um registro abrangente de solicitações e respostas API para ajudar na otimização do uso, monitorar padrões de utilização e acompanhar custos.
  • Verificar atualizações de status a cada 1 a 5 segundos : Continue verificando até que um status de mensagem conclusivo, como COMPLETED, FAILED ou CANCELLED, seja recebido. Limite o intervalo de consulta a 10 minutos para a maioria das solicitações. Se não houver uma resposta conclusiva após 10 minutos, interrompa a consulta e retorne um erro de tempo limite ou solicite ao usuário que verifique manualmente o status da consulta posteriormente.
  • Utilize o recuo exponencial para a verificação : Aumente o atraso entre as verificações até um máximo de um minuto. Isso reduz solicitações desnecessárias para consultas de longa duração, ao mesmo tempo que permite 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ção : Para gerenciar conversas antigas e permanecer abaixo 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 antigas ou conversas de teste.
    3. Use o botão DELETE /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id} endpoint para remover conversas de forma programática.

Monitore o agente​

Depois que o aplicativo estiver configurado, o senhor poderá monitorar as perguntas e respostas na interface do usuário do Databricks.

Incentive os usuários a testar o agente para que se aprenda sobre os tipos de perguntas que eles provavelmente farão e as respostas que receberão. Forneça aos usuários orientações para ajudá-los a começar a testar o agente. Use a tab Monitoramento para visualizar perguntas e respostas. Consulte Monitore o agente.

Também é possível usar os logs de auditoria para monitorar a atividade em um Genie Agent. Consulte eventos do Genie Agent.

Nesta página