Usar a API do Genie One

info

Beta

Este recurso está em Beta. Um administrador de workspace deve ativar a pré-visualização da API Genie One . Consulte Requisitos.

A API do Genie One permite que seu próprio aplicativo, serviço de backend ou agente faça perguntas em linguagem natural ao Genie One sobre seus dados via HTTP e transmita as respostas de volta. O Genie One funciona em todos os dados que o chamador pode acessar e baseia suas respostas em Ontologia Genie, portanto você não precisa configurar um agente com curadoria primeiro. As novas perguntas entram em execução com as permissões do Unity Catalog do chamador, portanto as respostas incluem apenas os dados que o chamador pode acessar. Ler uma resposta salva ou uma história de conversas retorna o conteúdo armazenado. Ele não executa novamente as queries nem verifica novamente as permissões nos dados subjacentes.

Esta página explica como autenticar, fazer perguntas, fazer transmissão de respostas e gerenciar conversas. Para formatos completos de solicitação e resposta, consulte a referência da API do Genie One.

Requisitos

Um administrador de workspace deve ativar a pré-visualização da API Genie One na página Pré-visualizações do workspace.
O chamador deve ser capaz de usar o Genie One. O entitlement Acesso do consumidor ou qualquer entitlement de workspace superior é suficiente. Consulte O que é o acesso do consumidor?.
O chamador deve ter privilégios SELECT nos dados do Unity Catalog que suas perguntas utilizam.
Para execução queries em um SQL warehouse específico, o autor da chamada deve ter pelo menos a permissão CAN USE nesse warehouse. Se você não especificar um warehouse, o Genie One escolherá um.

Autenticar

A API Genie One aceita access tokens OAuth com o escopo genie.

Para aplicativos onde um usuário está presente, use OAuth para usuários (OAuth U2M). As solicitações são executadas como esse usuário, portanto as respostas refletem as permissões do Unity Catalog do próprio usuário.
Para cargas de trabalho automatizadas, use uma Service Principal com OAuth para Service Principal (OAuth M2M). A Service Principal deve ter acesso aos dados e SQL warehouses que suas perguntas usam.

Você também precisa do URL do seu workspace. Os exemplos nesta página usam <workspace-url> para isso. Consulte Obter identificadores para objetos do workspace.

Faça uma pergunta e faça a transmissão da resposta

Enviar uma pergunta para POST /api/2.0/genie/one/responses. O Endpoint retorna uma resposta text/event-stream que faz a transmissão do progresso e da resposta final do Genie One como Server-Sent Events (SSE).

Começar uma conversa

Omita conversation_id para começar uma nova conversa. Defina input como a pergunta:

curl
Python

Bash
curl -N -X POST "https://<workspace-url>/api/2.0/genie/one/responses" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"input": "How did revenue change last quarter?"}'

A opção -N desativa o buffer de saída para que o curl imprima cada evento conforme ele chega.

O exemplo a seguir usa o Databricks SDK para Python apenas para resolver sua autenticação, portanto, funciona com OAuth U2M, OAuth M2M ou um perfil de configuração. Ele envia a solicitação com a biblioteca requests, entrega os IDs de resposta e conversa a um retorno de chamada on_created assim que a resposta é aceita e recupera com uma solicitação GET se a transmissão terminar mais cedo. Em seguida, imprime a resposta final.

Instale os pacotes que o exemplo usa:

Bash
pip install databricks-sdk requests

Python
import json
import time

import requests
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
base_url = f"{w.config.host}/api/2.0/genie/one"
terminal_events = ("response.completed", "response.failed", "response.incomplete")


def get_response(conversation_id, response_id, timeout_seconds=600):
    # Poll the stored response until it reaches a terminal status.
    deadline = time.time() + timeout_seconds
    while True:
        resp = requests.get(
            f"{base_url}/conversations/{conversation_id}/responses/{response_id}",
            headers=w.config.authenticate(),
        )
        resp.raise_for_status()
        response = resp.json()
        if response["status"] != "in_progress" or time.time() > deadline:
            return response
        time.sleep(3)


def ask(question, conversation_id=None, on_created=None):
    body = {"input": question}
    if conversation_id:
        body["conversation_id"] = conversation_id

    created = None
    try:
        with requests.post(
            f"{base_url}/responses",
            headers={**w.config.authenticate(), "Content-Type": "application/json"},
            json=body,
            stream=True,
        ) as resp:
            resp.raise_for_status()
            # The stream is UTF-8, but its content type doesn't declare a charset.
            resp.encoding = "utf-8"
            for line in resp.iter_lines(decode_unicode=True):
                if not line or not line.startswith("data:"):
                    continue
                # SSE allows an optional single space after "data:".
                data = line[len("data:"):]
                if data.startswith(" "):
                    data = data[1:]
                if data == "[DONE]":
                    break
                event = json.loads(data)
                if event["type"] == "response.created":
                    created = event["response"]
                    if on_created:
                        on_created(created["conversation_id"], created["id"])
                elif event["type"] in terminal_events:
                    return event["response"]
    except requests.RequestException:
        # Without response.created, you can't tell whether the request was accepted.
        if created is None:
            raise
    if created is None:
        raise RuntimeError("The stream ended before the response was accepted.")
    # The stream ended or disconnected before a terminal event. Recover with GET.
    return get_response(created["conversation_id"], created["id"])


response = ask(
    "How did revenue change last quarter?",
    on_created=lambda conversation_id, response_id: print(
        f"conversation_id={conversation_id} response_id={response_id}"
    ),
)
print(response["status"])
for item in response["output"]:
    if item.get("phase") == "final_answer":
        # Keep parts separate so Markdown tables and source notes stay on their own lines.
        print("\n\n".join(part["text"] for part in item["content"]))

Este exemplo aguarda o evento de terminal. Para mostrar o progresso enquanto o Genie One trabalha, também trate os eventos de item de saída, conforme descrito em Ler a transmissão de eventos.

Ler de uma transmissão de eventos

Cada evento tem um nome de SSE event e um corpo de JSON data com um type correspondente e um sequence_number crescente. Uma transmissão encurtada tem a seguinte aparência:

Text
event: response.created
data: {"type":"response.created","sequence_number":0,"response":{"object":"response","id":"9f7c84c6d3af4ae8ac5cc43590a15366","model":"genie-one","status":"in_progress","output":[],"conversation_id":"6a34b9a50cb4435da7c463130c9d42c1"}}

event: response.output_item.added
data: {"type":"response.output_item.added","sequence_number":1,"output_index":0,"item":{"type":"message","role":"assistant","status":"in_progress","phase":"final_answer","content":[{"type":"output_text","text":"Revenue increased 12% last quarter.","annotations":[]}]}}

event: response.output_item.done
data: {"type":"response.output_item.done","sequence_number":2,"output_index":0,"item":{"type":"message","role":"assistant","status":"completed","phase":"final_answer","content":[{"type":"output_text","text":"Revenue increased 12% last quarter.","annotations":[]}]}}

event: response.completed
data: {"type":"response.completed","sequence_number":3,"response":{"object":"response","id":"9f7c84c6d3af4ae8ac5cc43590a15366","status":"completed","output":[...],"conversation_id":"6a34b9a50cb4435da7c463130c9d42c1"}}

data: [DONE]

Trate os eventos da seguinte forma:

response.created : A resposta foi aceita. Salve response.id e response.conversation_id. Você precisa deles para fazer uma pergunta complementar ou para se recuperar caso a transmissão seja desconectada.
response.output_item.added , response.output_item.updated e response.output_item.done : Uma mensagem do assistente foi adicionada, alterada ou finalizada. Cada evento carrega a mensagem completa, portanto substitua a mensagem em output_index em vez de anexar texto a ela.
response.completed , response.failed ou response.incomplete : A resposta atingiu um estado terminal. O array response.output contém as mensagens finais do assistente. A transmissão termina então com data: [DONE].

Cada mensagem de assistente tem um phase. As mensagens com a fase commentary descrevem o progresso do Genie One enquanto ele trabalha, e você pode exibi-las como atualizações de status. A mensagem com a fase final_answer é a resposta. O texto da resposta é Markdown e pode incluir tabelas de resultados.

Se a resposta falhar depois de ser aceita, o status HTTP ainda é 200 e a transmissão termina com um evento response.failed. O objeto response.error descreve a falha. Consulte Solução de problemas.

Faça uma pergunta complementar

Para continuar uma conversa, passe o conversation_id de response.created. Genie One usa as perguntas e respostas anteriores como contexto.

Bash
curl -N -X POST "https://<workspace-url>/api/2.0/genie/one/responses" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Break that down by region.",
    "conversation_id": "<conversation-id>"
  }'

Você também pode definir warehouse_id para executar queries em um SQL warehouse específico e user_timezone para um fuso horário IANA, como America/Los_Angeles, para que o Genie One interprete datas relativas no fuso horário do usuário.

Recuperar de uma conexão perdida

Desconectar-se da transmissão não cancela a resposta. O Genie One continua funcionando e você pode recuperar o resultado com os IDs de response.created:

Bash
curl "https://<workspace-url>/api/2.0/genie/one/conversations/<conversation-id>/responses/<response-id>" \
  -H "Authorization: Bearer <access-token>"

A solicitação retorna o mesmo objeto de Resposta que o evento de transmissão de terminal. Como status é in_progress, faça o polling do endpoint a cada poucos segundos. Pare quando status for completed, failed ou incomplete.

Não envie novamente a solicitação POST para recuperar. Cada solicitação POST começa uma nova resposta.

Ler citações

Cada parte output_text tem um array annotations que lista as fontes que o Genie One usou para esse texto. Cada anotação inclui:

title: O nome de exibição da origem.
asset_type: O tipo de fonte, como TABLE, NOTEBOOK ou WEB.
identifier: O identificador do ativo, um caminho de volume ou uma URL da web.
index: O número de citação baseado em um ao qual o texto da resposta se refere.

Gerenciar conversas

As conversas que você cria com a API do Genie One pertencem ao usuário chamador ou ao service principal. Eles também aparecem na história de chat desse usuário no Genie One.

Listar conversas : GET /api/2.0/genie/one/conversations retorna as conversas do Genie One do autor da chamada, as atualizadas mais recentemente primeiro. Não inclui conversas do Genie Agent. Use page_size (default 20, máximo 100) e passe next_page_token como page_token para obter a próxima página.
Obter uma conversa : GET /api/2.0/genie/one/conversations/{conversation_id} retorna o título e os Timestamp da conversa, sem suas mensagens.
Listar itens de conversa : GET /api/2.0/genie/one/conversations/{conversation_id}/items retorna as mensagens do usuário e do assistente na conversa. Use-o para reconstruir uma história de chat no seu aplicativo.
Excluir uma conversa : DELETE /api/2.0/genie/one/conversations/{conversation_id} exclui a conversa.

Por exemplo, para listar suas três conversas mais recentes:

Bash
curl "https://<workspace-url>/api/2.0/genie/one/conversations?page_size=3" \
  -H "Authorization: Bearer <access-token>"

Limitações

Cada solicitação aceita uma pergunta como texto, até 25.000 bytes UTF-8. Imagens, arquivos e várias mensagens em uma única solicitação não são suportados.
Uma conversa pode ter apenas uma resposta ativa. Uma nova pergunta nessa conversa retorna HTTP 409 até que a resposta ativa termine.
As solicitações têm a taxa limitada por workspace. As solicitações acima do limite retornam HTTP 429.

Práticas recomendadas

Salve os IDs de response.created : Armazene os IDs de resposta e de conversa assim que a transmissão começar, para que você possa recuperar a resposta se a conexão cair.
Tente novamente as solicitações rejeitadas com recuo exponencial : quando a API retorna uma resposta de erro antes de a transmissão começar, como 429, tente novamente com um atraso crescente entre as tentativas. Após receber response.created, recupere a resposta com GET em vez de reenviar a solicitação POST.
Não tente novamente às cegas após um timeout ou erro de gateway : se uma solicitação expirar ou retornar um erro de gateway como 502 ou 504 antes que response.created chegue, a API pode ainda tê-la aceitado. Reenviar a solicitação POST pode então criar uma segunda resposta.
Tentar novamente apenas as respostas com falha quando o erro puder ser tentado novamente : Quando uma resposta falhar, verifique response.error.retryable antes de fazer a pergunta novamente.
Comece uma nova conversa para cada sessão : Reutilizar uma conversa em sessões não relacionadas pode reduzir a precisão porque o Genie One usa turnos anteriores como contexto.
Registrar solicitações e respostas : Registre IDs de resposta, status e erros para ajudar na depuração e no monitoramento do uso.

Solução de problemas

Sintoma	Causa e correção
`404` com a mensagem "O recurso solicitado não foi encontrado."	A prévia da Genie One API está desativada para o workspace, uma conversa ou ID de resposta está incorreto ou pertence a outro usuário, ou o warehouse não está disponível para o chamador. Peça a um administrador do workspace para verificar a página de Prévias do workspace e, em seguida, verifique os IDs e as permissões do chamador.
`401` ou `403`	A solicitação não tem nenhum tokens válido, ou o chamador não pode adicionar uma resposta à conversa. Verifique seu token OAuth e seu escopo `genie`. Consulte Autenticar.
`400` com `INVALID_PARAMETER_VALUE`	O corpo da solicitação contém um campo desconhecido ou uma opção sem suporte, mais de uma mensagem ou uma pergunta com mais de 25.000 bytes. Envie somente os campos indicados na referência da API.
`409` com `ALREADY_EXISTS`	Outra resposta está ativa na conversa. Aguarde a conclusão e tente novamente.
`429` com `RESOURCE_EXHAUSTED`	O workspace excedeu o limite de taxa. Repetir com backoff exponencial. Consulte Limitações.
A transmissão termina com `response.failed`	A resposta falhou após ser aceita. Leia `response.error.message` e tente novamente apenas se `response.error.retryable` for `true`.
A transmissão é desconectada antes de um evento terminal	Recupere a resposta com os IDs de `response.created`. Consulte Recuperar de uma conexão interrompida.

Sintoma	Causa e correção
`404` com a mensagem "O recurso solicitado não foi encontrado."	A prévia da Genie One API está desativada para o workspace, uma conversa ou ID de resposta está incorreto ou pertence a outro usuário, ou o warehouse não está disponível para o chamador. Peça a um administrador do workspace para verificar a página de Prévias do workspace e, em seguida, verifique os IDs e as permissões do chamador.
`401` ou `403`	A solicitação não tem nenhum tokens válido, ou o chamador não pode adicionar uma resposta à conversa. Verifique seu token OAuth e seu escopo `genie`. Consulte Autenticar.
`400` com `INVALID_PARAMETER_VALUE`	O corpo da solicitação contém um campo desconhecido ou uma opção sem suporte, mais de uma mensagem ou uma pergunta com mais de 25.000 bytes. Envie somente os campos indicados na referência da API.
`409` com `ALREADY_EXISTS`	Outra resposta está ativa na conversa. Aguarde a conclusão e tente novamente.
`429` com `RESOURCE_EXHAUSTED`	O workspace excedeu o limite de taxa. Repetir com backoff exponencial. Consulte Limitações.
A transmissão termina com `response.failed`	A resposta falhou após ser aceita. Leia `response.error.message` e tente novamente apenas se `response.error.retryable` for `true`.
A transmissão é desconectada antes de um evento terminal	Recupere a resposta com os IDs de `response.created`. Consulte Recuperar de uma conexão interrompida.

Preços

A API do Genie One faz a execução do Chat no Genie One, portanto as solicitações são cobradas da mesma forma que o chat do Genie One. Consulte os preços do Genie.

Outros recursos

Referência da API do Genie One: Resposta para os Endpoint de resposta de criação e obtenção e a transmissão de eventos.
Referência da API do Genie One: Conversa para os Endpoint de conversa.
Converse no Genie One para saber como o Genie One responde às perguntas.
Use a Genie Agents API para fazer query a um Genie Agent curado.
Servidor MCP do Genie One para conectar um cliente ou agente MCP ao Genie One.

Requisitos​

Autenticar​

Faça uma pergunta e faça a transmissão da resposta​

Começar uma conversa​

Ler de uma transmissão de eventos​

Faça uma pergunta complementar​

Recuperar de uma conexão perdida​

Ler citações​

Gerenciar conversas​

Limitações​

Práticas recomendadas​

Solução de problemas​

Preços​

Outros recursos​