APIs do Modo Agente no Genie Agents
As APIs do modo Agente permitem executar o modo Agente programaticamente em vez de por meio da UI do Databricks. Use-os para integrar o modo Agente em seus próprios aplicativos, como chatbots, relatórios agendados e ferramentas internas.
Beta
As APIs do modo Agente do Genie Agents estão em versão Beta.
O Modo Agente era anteriormente conhecido como Research Agent. Genie Agents eram anteriormente conhecidos como Genie Spaces.
Como as APIs do modo Agente funcionam
Com as APIs do modo Agent, você envia uma pergunta em linguagem natural para um Genie Agent. Ele cria e refina um plano de pesquisa, executa queries SQL, itera com base em cada resultado e retorna um relatório com citações e tabelas de apoio. Os resultados são transmitidos por transmissão para o seu cliente como Server-Sent Events (SSE).
As APIs abrangem os endpoints, formatos de solicitação e resposta, e tipos de evento de transmissão necessários para se comunicar diretamente com o Modo Agente. Para a visão geral do conceito e a experiência da interface do usuário, consulte Modo Agente no Genie Agents.
Requisitos
Para usar as APIs do modo Agente, seu workspace deve atender aos seguintes requisitos:
- O Unity Catalog está ativado. Consulte O que é o Unity Catalog?.
- Os recursos de IA desenvolvidos por parceiros estão ativados. Consulte Recursos de AI com tecnologia de parceiros.
- Você tem um Genie Agent com instruções claras e metadados da tabela. O modo Agente depende deste contexto para raciocinar sobre seus dados. Consulte Crie um Genie Agent eficaz.
Para habilitar as APIs para seu workspace, entre em contato com a equipe de conta da Databricks com os IDs dos workspaces onde você deseja o recurso. Após a aprovação da solicitação, um administrador do workspace ativa a **API do Mode de Agente Genie Agents** no menu **Visualizações**.
Começar
Os exemplos a seguir mostram como enviar um prompt e ler a resposta transmitida.
Envie seu primeiro prompt com curl
A solicitação a seguir envia uma pergunta em linguagem natural a um Genie Agent e transmite a resposta como um SSE:
curl -N --no-buffer \
-X POST "https://${DATABRICKS_HOST}/api/2.0/genie/agents/${AGENT_ID}/responses" \
-H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"input": [
{
"type": "message",
"role": "user",
"content": [{"type": "input_text", "text": "What were our top 10 customers by revenue last quarter?"}]
}
]
}'
Os eventos chegam como pares de event: e data::
event: response.created
data: {"type":"response.created","sequence_number":0,"response":{"object":"response","id":"01f14fe4e34b...","model":"genie-agent","status":"in_progress","output":[],"conversation_id":"01f14fe4e338..."}}
event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"sequence_number":1,"item":{"type":"reasoning","id":"01f14fe4f248...","status":"in_progress","content":[{"type":"reasoning_text","text":"I need to find revenue data..."}],"summary":[]}}
event: response.completed
data: {"type":"response.completed","sequence_number":42,"response":{"object":"response","id":"01f14fe4e34b...","model":"genie-agent","status":"completed","output":[...],"conversation_id":"01f14fe4e338...","created_at":1748383200}}
Leia a transmissão com o cliente Databricks OpenAI (Python)
Instale o cliente:
pip install databricks-openai
Crie uma resposta e trate cada evento à medida que ele chega:
from databricks.sdk import WorkspaceClient
from databricks_openai import DatabricksOpenAI
AGENT_ID = "<your-agent-id>" # Same as your Genie Agent ID
w = WorkspaceClient()
host = f"https://{w.config.host}" if not w.config.host.startswith("http") else w.config.host
client = DatabricksOpenAI(workspace_client=w)
client.base_url = f"{host}/api/2.0/genie/agents/{AGENT_ID}"
stream = client.responses.create(
model="genie-agent",
input=[
{
"type": "message",
"role": "user",
"content": [{"type": "input_text", "text": "What were our top 10 customers by revenue last quarter?"}],
}
],
stream=True,
)
conversation_id = None
for event in stream:
if event.type == "response.created":
conversation_id = event.response.conversation_id
elif event.type == "response.output_item.done":
print(f"Output item: {event.item.type}")
elif event.type == "response.completed":
print(f"Done: {event.response.status}")
elif event.type == "response.failed":
print(f"Failed: {event.response.error}")
Enviar um prompt de acompanhamento
Para continuar uma conversação, passe o conversation_id da primeira resposta:
stream = client.responses.create(
model="genie-agent",
input=[
{
"type": "message",
"role": "user",
"content": [{"type": "input_text", "text": "Break that down by region"}],
}
],
stream=True,
extra_body={"conversation_id": conversation_id},
)
O agente mantém o contexto de interações anteriores e pode fazer referência a queries e resultados anteriores.
Referência de API
As APIs do modo Agente abrangem os Endpoint disponíveis, os formatos de solicitação e resposta, o ciclo de vida de eventos SSE, os modelos de dados e os códigos de erro.
URL base
Todos os Endpoint são relativos à seguinte URL base:
https://<workspace-url>/api/2.0/genie/agents
O agent_id em cada caminho é o ID do Genie Agent, o mesmo identificador hexadecimal de 32 caracteres que aparece na URL do Genie Agent.
Endpoint
As APIs fornecem os seguintes endpoints:
Método | Caminho | Descrição |
|---|---|---|
|
| Crie uma resposta como uma transmissão SSE. |
|
| Listar todos os itens em uma conversa. |
Criar uma resposta
Cria uma nova resposta do modo Agente. Retorna uma transmissão SSE que entrega itens de saída em tempo real conforme o modo Agente é executado.
POST /{agent_id}/responses
Parâmetros de caminho
O endpoint aceita o seguinte parâmetro de caminho:
Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
|
| Sim | O ID do Genie Agent. Uma string hexadecimal minúscula de 32 caracteres. |
Corpo da solicitação
O corpo da solicitação aceita os seguintes campos:
campo | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
|
| Sim | Nenhuma | Os itens de entrada. A matriz deve conter exatamente um item |
|
| Não |
| O ID de uma conversa existente para continuar. Quando omitido, uma nova conversa é criada. |
Ciclo de vida do evento SSE
A transmissão começa com um evento response.created, transmite itens de saída e então termina com um evento terminal:
response.created (once, stream opened)
-> response.output_item.added (0..N, new item appears)
-> response.output_item.updated (0..N, item content changed)
-> response.output_item.done (0..N, item finalized)
-> response.completed (once, terminal success)
OR response.failed (once, terminal failure)
Cada evento carrega um sequence_number que aumenta monotonicamente e que você pode usar para ordenação.
Tipos de evento SSE
A transmissão emite os seguintes tipos de evento.
response.created
Emitido uma vez no início. Contém um objeto Response com status: "in_progress" e um array output vazio.
event: response.created
data: {
"type": "response.created",
"sequence_number": 0,
"response": {
"object": "response",
"id": "01f15a22a7a816299374da7bc4264025",
"model": "genie-agent",
"status": "in_progress",
"output": [],
"conversation_id": "01f15a22a79a1699ab5e7f59563c5655",
"created_at": 1748383200
}
}
response.output_item.added
Emitido quando um novo item de saída aparece pela primeira vez. O item ainda pode estar in_progress.
event: response.output_item.added
data: {
"type": "response.output_item.added",
"output_index": 0,
"sequence_number": 1,
"item": {
"type": "reasoning",
"id": "01f14fe4f24818d79f3e5963c31ec151",
"status": "in_progress",
"content": [
{"type": "reasoning_text", "text": "I need to find the revenue data..."}
],
"summary": []
}
}
response.output_item.updated
Emitido quando o conteúdo de um item existente é alterado, como quando os resultados de uma query chegam para um function_call_output. Usa a mesma estrutura de payload que response.output_item.added.
response.output_item.done
Emitido quando um item de saída alcança seu estado final. Usa a mesma estrutura de payload que response.output_item.added. Se um item chegar já concluído, os eventos added e done são emitidos em sequência.
response.completed
Evento de sucesso de terminal. Engloba o Response final com todos os itens de saída.
event: response.completed
data: {
"type": "response.completed",
"sequence_number": 42,
"response": {
"object": "response",
"id": "01f14fe4e34b1b2293908bcece575499",
"model": "genie-agent",
"status": "completed",
"output": [ ... ],
"conversation_id": "01f14fe4e33816c6aa264b4661f998ea",
"created_at": 1748383200
}
}
response.failed
Evento de falha de terminal. O Response tem status: "failed" e um objeto error. Um item de mensagem de erro do sistema é emitido como response.output_item.added imediatamente antes deste evento. Para a lista completa de códigos, consulte Códigos de erro de transmissão.
event: response.failed
data: {
"type": "response.failed",
"sequence_number": 5,
"response": {
"object": "response",
"id": "01f14fe4e34b1b2293908bcece575499",
"model": "genie-agent",
"status": "failed",
"output": [ ... ],
"error": {
"type": "server_error",
"code": "sql_execution_error",
"message": "Table 'sales' does not exist"
},
"conversation_id": "01f14fe4e33816c6aa264b4661f998ea",
"created_at": 1748383200
}
}
Concorrência
Apenas uma resposta pode ser gerada por conversa por vez. Uma segunda solicitação para uma conversa que já tem uma resposta em andamento retorna um HTTP 409:
HTTP 409
{"error": {"type": "RESOURCE_CONFLICT", "message": "A response is already being generated for conversation <id>"}}
Tempos esgotados
A transmissão SSE tem um tempo limite do lado do servidor de 90 minutos. Como o modo Agente executa raciocínio em várias etapas e execução SQL, mantenha sua conexão HTTP aberta por toda a duração.
Listar itens de conversa
Recupera os itens de saída em uma conversa como uma lista plana. Os itens de todas as rodadas são combinados em ordem cronológica, incluindo mensagens de usuário, raciocínio, queries, resultados e relatórios. Este Endpoint suporta paginação baseada em cursor pelos parâmetros de query after e limit.
GET /{agent_id}/conversations/{conversation_id}/items
Use este endpoint para:
- Exiba o histórico completo da conversa em seu aplicativo.
- Recuperar resultados após uma transmissão SSE ser desconectada. Chame este Endpoint após a resposta ser concluída.
- Busque conversas grandes incrementalmente em vez de carregar todos os itens de uma vez.
Parâmetros de caminho
O endpoint aceita os seguintes parâmetros de caminho:
Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
|
| Sim | O ID do Genie Agent. Uma string hexadecimal minúscula de 32 caracteres. |
|
| Sim | O ID da conversa. |
Parâmetros da query
O Endpoint aceita os seguintes parâmetros de query:
Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
|
| Não | 100 | O número máximo de itens a serem retornados. Intervalo: 1 a 100. |
|
| Não | Nenhuma | O cursor de paginação. Passe |
|
| Não |
| A ordem de classificação. Use |
Exemplos de solicitações
Recuperar todos os itens em uma conversa:
GET /api/2.0/genie/agents/01f14fe4e338.../conversations/01f14fe4e338.../items
Limitar o tamanho da página:
GET /api/2.0/genie/agents/01f14fe4e338.../conversations/01f14fe4e338.../items?limit=5
Retorne os itens mais recentes primeiro:
GET /api/2.0/genie/agents/01f14fe4e338.../conversations/01f14fe4e338.../items?order=desc&limit=5
Buscar a próxima página:
GET /api/2.0/genie/agents/01f14fe4e338.../conversations/01f14fe4e338.../items?limit=5&after=01f14fe4f24e10beacaa1720d4b79b59_output
Resposta
A resposta tem Content-Type: application/json e é um envelope de lista paginada com "object": "list":
{
"data": [
{
"type": "message",
"role": "user",
"content": [{ "type": "input_text", "text": "What were our top 10 customers by revenue last quarter?" }],
"id": "01f14fe4e34b1b2293908bcece575499_input",
"status": "completed"
},
{
"type": "reasoning",
"id": "01f14fe4f24818d79f3e5963c31ec151",
"status": "completed",
"content": [{ "type": "reasoning_text", "text": "I'll query the revenue table grouped by customer..." }],
"summary": []
},
{
"type": "function_call",
"id": "01f14fe4f24e10beacaa1720d4b79b59",
"call_id": "01f14fe4f24e10beacaa1720d4b79b59",
"status": "completed",
"name": "execute_sql",
"arguments": "{\"title\": \"Top 10 Customers\", \"sql\": \"SELECT customer, SUM(revenue) AS total FROM sales GROUP BY customer ORDER BY total DESC LIMIT 10\"}"
},
{
"type": "function_call_output",
"id": "01f14fe4f24e10beacaa1720d4b79b59_output",
"call_id": "01f14fe4f24e10beacaa1720d4b79b59",
"status": "completed",
"output": "Top 10 Customers\n\n| customer | total |\n| --- | --- |\n| Acme Corp | 1500000 |\n| Globex | 1200000 |"
},
{
"type": "message",
"id": "01f14fe5383f184a97ca1178af0d9356",
"role": "assistant",
"status": "completed",
"content": [
{
"type": "output_text",
"text": "Here are your top 10 customers by revenue last quarter [1](https://host/genie/rooms/01f14fe4e338.../chats/01f14fe4e338...?o=12345&gra_focus=01f14fe4f24e...)."
},
{
"type": "output_text",
"text": "| customer | total |\n| --- | --- |\n| Acme Corp | 1500000 |\n| Globex | 1200000 |",
"metadata": {
"columns": [
{ "name": "customer", "type": "STRING" },
{ "name": "total", "type": "DOUBLE" }
],
"preview_rows": [
["Acme Corp", "1500000"],
["Globex", "1200000"]
],
"total_row_count": 10,
"status": "available",
"sql": "SELECT customer, SUM(revenue) AS total FROM sales GROUP BY customer ORDER BY total DESC LIMIT 10"
}
},
{
"type": "output_text",
"text": "Acme Corp leads with $1.5M [1](https://host/genie/rooms/01f14fe4e338.../chats/01f14fe4e338...?o=12345&gra_focus=01f14fe4f24e...), followed by Globex at $1.2M [1](https://host/genie/rooms/01f14fe4e338.../chats/01f14fe4e338...?o=12345&gra_focus=01f14fe4f24e...)..."
}
]
}
],
"first_id": "01f14fe4e34b1b2293908bcece575499_input",
"last_id": "01f14fe5383f184a97ca1178af0d9356",
"has_more": false,
"status": "completed",
"object": "list"
}
O campo status de nível superior reflete o estado da resposta mais recente na conversa. É "in_progress" enquanto uma resposta está em transmissão, e "completed" ou "failed" depois que ela termina. Monitore este campo para detectar quando uma resposta terminou.
Paginação
A resposta inclui três campos de paginação:
campo | Tipo | Descrição |
|---|---|---|
|
| A ID do primeiro item na página atual. Ausente quando |
|
| A ID do último item na página atual. Passe-o como |
|
|
|
Para paginar todos os itens, solicite páginas até que has_more seja false:
items = []
after = None
while True:
params = {"limit": 10}
if after:
params["after"] = after
page = client.get(f"/conversations/{conv_id}/items", params=params)
items.extend(page["data"])
if not page["has_more"]:
break
after = page["last_id"]
O array data contém itens de saída em ordem cronológica. As mensagens de entrada do usuário aparecem como message itens com um sufixo _input no ID.
Entenda a resposta
Esta seção explica como os itens de saída se encaixam para formar uma resposta completa do modo Agente.
Fluxo de itens de saída
Uma resposta típica do modo Agent produz itens de saída na seguinte ordem:
reasoning The agent's plan and analysis
|
function_call A SQL query the agent runs
|
function_call_output The query results, paired with the function_call above
|
... (reasoning, function_call, and function_call_output repeat for each query) ...
|
message The final report, with structured text and inline tables
O agente pode executar várias queries em sequência, refinando sua análise com base em cada resultado. Uma única resposta pode conter muitos ciclos de raciocínio, query e resultado antes do relatório final.
Como chamada de função e saída de chamada de função se pareiam
Cada query SQL produz um par de itens de saída vinculados por call_id:
function_callé a query que o agente executa. O campoargumentsé uma string codificada em JSON que descreve a invocação da ferramenta.function_call_outputé o resultado. Depois que o item for concluído, o campooutputcontém o título da query seguido por uma tabela markdown dos dados.
O call_id é idêntico em ambos os itens. O function_call_output.id é sempre {call_id}_output.
Analisar o relatório
O item de saída final é um message com role: "assistant". Seu array content contém vários fragmentos output_text de dois tipos:
- Blocos de texto contêm análise narrativa com links de citação embutidos.
- Os blocos de tabela contêm resultados de query embutidos renderizados como tabelas markdown. Cada bloco de tabela carrega
metadatacom os dados de resultado de query estruturados, para que seu cliente possa renderizar tabelas ou gráficos avançados programaticamente.
O fragmento de tabela a seguir inclui tanto o markdown renderizado quanto o metadata estruturado:
{
"type": "output_text",
"text": "| customer | total |\n| --- | --- |\n| Acme Corp | 1500000 |\n| Globex | 1200000 |",
"metadata": {
"columns": [
{ "name": "customer", "type": "STRING" },
{ "name": "total", "type": "DOUBLE" }
],
"preview_rows": [
["Acme Corp", "1500000"],
["Globex", "1200000"]
],
"total_row_count": 10,
"status": "available",
"sql": "SELECT customer, SUM(revenue) AS total FROM sales GROUP BY customer ORDER BY total DESC LIMIT 10"
}
}
Um objeto de chunk de tabela metadata contém os seguintes campos:
campo | Tipo | Descrição |
|---|---|---|
|
| As definições da coluna. |
|
| As linhas de resultado truncadas. |
|
| A contagem total de linhas, quando conhecida. |
|
| Ou |
|
| A query SQL que produziu os resultados. |
Citações
Os fragmentos de texto no relatório contêm citações em linha que link cada afirmação à query SQL que a suporta. Cada citação é um link markdown da forma [N](url), onde N é um número de rodapé sequencial e url aponta para a interface do usuário do Genie Agent com a query relevante focada.
O URL de citação tem o seguinte formato:
https://<workspace-url>/genie/rooms/<space_id>/chats/<conversation_id>?o=<workspace_id>&gra_focus=<attachment_id>
A URL contém os seguintes componentes:
Componente | Descrição |
|---|---|
| O ID do Genie Agent, o mesmo valor que |
| A conversa que contém a query citada. |
| O ID numérico do Workspace. |
| O ID de anexo da query, que identifica o resultado da query SQL específico. |
Para renderizar citações, siga estas orientações com base no seu cliente:
- Os renderizadores Markdown exibem citações como links de rodapé clicáveis automaticamente.
- Para texto simples, reduza
[N](url)para[N]ou remova a citação. - Para uma interface do usuário personalizada, analise o parâmetro de query
gra_focusna URL para identificar a query citada, depois faça a correspondência com os itensfunction_call_outputna conversa.
As citações são desduplicadas. Se a mesma query for citada várias vezes, cada referência usa o mesmo número de índice e URL.
Modelos de dados
Esta seção descreve os objetos que as APIs retornam.
Resposta
O objeto Response é retornado nos eventos SSE response.created, response.completed e response.failed.
campo | Tipo | Descrição |
|---|---|---|
|
| Sempre |
|
| O ID de resposta exclusivo. |
|
| Sempre |
|
| Ou |
|
| Os itens de saída produzidos pela resposta. |
|
| A conversa à qual a resposta pertence. |
|
| A hora Unix epoch em segundos quando a resposta foi criada. |
|
| Presente quando |
Informações de Erro
O objeto ErrorInfo descreve uma falha:
campo | Tipo | Descrição |
|---|---|---|
|
| Um de: |
|
| Uma descrição legível por humanos. Para erros internos, isto é sempre |
|
| Um código de erro opcional com mais detalhes, como |
Itens de saída
Os itens de saída são polimórficos no campo type. Os seguintes tipos estão disponíveis.
reasoning
O raciocínio interno do agente à medida que o modo Agente é executado.
campo | Tipo | Descrição |
|---|---|---|
|
|
|
|
| A ID exclusiva do item. |
|
| Ou |
|
| Contém |
|
| Sempre |
function_call
Uma invocação de ferramenta, que é uma execução de query SQL.
campo | Tipo | Descrição |
|---|---|---|
|
|
|
|
| A ID exclusiva do item. |
|
| O ID de correlação que se vincula ao |
|
|
|
|
|
|
|
| Uma string JSON, por exemplo |
function_call_output
O resultado de uma invocação de ferramenta, emparelhado com um function_call a call_id.
campo | Tipo | Descrição |
|---|---|---|
|
|
|
|
| Sempre |
|
| Corresponde ao |
|
| Ou |
|
| O resultado da consulta. Consulte a seguinte tabela de ciclo de vida. |
O campo output evolui à medida que o item avança:
Status |
|
|---|---|
| Somente o título da query. |
| O título da query, uma linha em branco e, em seguida, a tabela de resultados markdown. |
Dados de resultados de query estruturada, como colunas, linhas e SQL, estão disponíveis nos blocos de tabela do relatório, não no item function_call_output. Consulte Analisar o relatório.
message
Uma mensagem de texto. Uma mensagem aparece em uma das três funções:
Função | Quando | Descrição |
|---|---|---|
| Entrada | A pergunta do usuário. Aparece em |
| Relatório | O relatório estruturado final com texto e blocos de tabela embutidos. |
| Erro ou cancelar | Emitido quando uma resposta falha ou é cancelada. |
O objeto message contém os seguintes campos:
campo | Tipo | Descrição |
|---|---|---|
|
|
|
|
| Ou |
|
| O conteúdo da mensagem. Consulte Analisar o relatório para mensagens do assistente. |
|
| A ID exclusiva do item. As mensagens do sistema usam |
|
| Ou |
Quando uma resposta falha, o erro estruturado é entregue no campo error do objeto Response (consulte ErrorInfo) e no evento response.failed, não no item message do sistema.
Itens de conteúdo
As APIs usam os seguintes tipos de item de conteúdo:
Tipo | Campos | Usado em |
|---|---|---|
|
| Mensagens do usuário (entrada). |
|
| Mensagens do assistente (blocos de relatório). Blocos de texto contêm |
|
| Itens de raciocínio. |
ColumnInfo
O objeto ColumnInfo descreve uma coluna:
campo | Tipo | Descrição |
|---|---|---|
|
| O nome da coluna. |
|
| O tipo de dados da coluna, como |
Tratamento de erros
As APIs retornam dois tipos de erros: erros HTTP antes do início da transmissão e erros de transmissão que encerram uma transmissão aberta.
Erros HTTP
Erros HTTP são retornados como respostas JSON padrão antes do início da transmissão SSE:
{ "error": { "type": "ERROR_CODE", "message": "Human-readable description" } }
Os seguintes erros HTTP podem ocorrer:
Status HTTP | Código de erro | Condição |
|---|---|---|
|
| Um parâmetro de caminho está ausente, os itens de entrada estão ausentes ou são inválidos, ou a última entrada não é uma mensagem do usuário. |
|
| O Workspace não está inscrito na pré-visualização, ou um administrador do Workspace não ativou a pré-visualização. |
|
| O chamador não tem permissão CAN VIEW no Genie Agent. |
|
| O Genie Agent ou a conversa não existe. |
|
| Uma resposta já está sendo gerada para a conversa. |
|
| Ocorreu um erro inesperado do servidor. |
Códigos de erro de transmissão
Quando uma falha ocorre na transmissão, uma mensagem de erro do sistema (role: "system", status: "failed") é emitida como response.output_item.added, seguida pelo evento response.failed. O objeto error em Response possui type e code.
O campo type é um dos seguintes tipos de especificação:
| Descrição |
|---|---|
| Uma falha interna do servidor que o cliente não causou. |
| Uma solicitação malformada ou semanticamente inválida, ou um problema de permissão em que o usuário pode agir. |
| Um recurso referenciado não existe. |
| O modelo falhou ao processar uma solicitação que era válida. |
| A solicitação foi limitada por taxa. |
O campo code fornece mais detalhes:
|
| Descrição |
|---|---|---|
|
| Um erro inesperado do servidor. A mensagem é sempre |
|
| Uma query SQL falhou ao ser executada. |
|
| Uma dependência está temporariamente indisponível. |
|
| A solicitação ou uma chamada upstream atingiu o tempo limite. |
|
| O modelo está temporariamente indisponível. |
|
| O histórico da conversa excedeu a janela de contexto do modelo. |
|
| Um filtro de conteúdo bloqueou a resposta. |
|
| Muitas solicitações concorrentes ou um limite de taxa upstream foi atingido. |
|
| O workspace excedeu seu orçamento de uso para o modo de Agente. |
|
| O chamador não tem permissão para usar o SQL warehouse configurado. |
|
| Nenhuma tabela consultável está disponível no Genie Agent. |
|
| A solicitação estava malformada ou faltavam campos obrigatórios. |
|
| O chamador perdeu a permissão ou a delegação falhou durante a execução. |
|
| Uma operação concorrente entrou em conflito com a solicitação. |
|
| O SQL warehouse configurado não existe ou foi excluído. |
|
| Um recurso referenciado não foi encontrado durante a execução. |
Perguntas Frequentes
As perguntas a seguir abrangem tópicos comuns para as APIs do modo Agente.
Quanto tempo levam as respostas?
O tempo de resposta depende da complexidade da pergunta. Perguntas de single-query podem ser concluídas em menos de um minuto. A pesquisa multi-query pode levar vários minutos. A transmissão tem um tempo limite do lado do servidor de 90 minutos.
Posso consultar em vez de transmissão?
Sim. Envie a solicitação para criar uma resposta, depois use o ID da conversa do evento response.created para recuperar os itens da conversa. O endpoint de itens retorna o histórico completo da conversa, incluindo respostas em andamento. Consulte o campo de nível superior status na resposta da lista de itens até que seja completed ou failed.
Como funciona uma conversa em vários turnos?
Passe o ID da conversa de uma resposta anterior na sua próxima solicitação. O agente tem acesso a todas as queries anteriores e resultados na conversa, e pode referenciá-los no relatório.
O formato de saída de markdown é estável?
O conteúdo de texto, incluindo partes de relatório, texto de raciocínio e saída de resultado de query, é retornado em markdown. A estrutura markdown exata, como níveis de cabeçalho e formatação de tabela, é gerada pelo modelo e não é garantida como estável entre solicitações ou versões de API. Trate a saída markdown como texto formatado de melhor esforço e use os campos estruturados, como colunas e linhas de visualização, como a representação estável e legível por máquina dos dados.
Posso recuperar visualizações?
Sim. Recupere visualizações com o endpoint de visualização de anexo de mensagem para download. Consulte GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/attachments/{attachment_id}/query-result/visualization na referência da API REST.
Os resultados da query expiram?
Sim. Os resultados da query SQL seguem a mesma política de expiração que a API de Execução de Instrução. Depois que os resultados expiram, o ID do comando não os retorna mais. As linhas de visualização nos metadados da resposta permanecem disponíveis no Endpoint de itens de conversação.
Como saber quais tabelas o agente pode query?
O agente pode query somente tabelas que você adiciona ao Genie Agent. Não é possível acessar seu catálogo completo. Para obter os melhores resultados, adicione descrições de coluna, queries de exemplo e instruções de join. Consulte Organizar um Genie Agent eficaz.