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

API do Supervisor (Beta)

info

Beta

Este recurso está em versão Beta. Os administradores da conta podem controlar o acesso a este recurso na página de Pré-visualizações . Veja as prévias do Gerenciador Databricks.

A API Supervisor simplifica a criação de agentes personalizados no Databricks , com suporte para modo em segundo plano para tarefas de longa duração. Você define o modelo, as ferramentas e as instruções em uma solicitação para um endpoint compatível com OpenResponses(POST /mlflow/v1/responses), e Databricks executa o loop do agente para você: chamando repetidamente o modelo, selecionando e executando ferramentas e sintetizando uma resposta final.

Existem três abordagens para criar um agente de chamada de ferramentas personalizado no Databricks:

  • Agente Supervisor de Tijolos (recomendado): Totalmente declarativo com otimização de feedback humano para a mais alta qualidade.
  • API do Supervisor : Crie um agente personalizado programaticamente — escolha modelos em tempo de execução, controle quais ferramentas usar por solicitação ou itere durante o desenvolvimento. Também é a escolha certa quando você precisa de controle sobre a seleção do modelo, ao mesmo tempo que delega o gerenciamento do loop do agente ao Databricks.
  • APIs unificadas ou nativas do AI Gateway : Crie seu próprio loop de agente. O Databricks fornece apenas a camada de inferência LLM. Use APIs unificadas sempre que possível para permitir a troca de modelos ou APIs nativas específicas do provedor (/openai, /anthropic, /gemini) ao migrar código existente para Databricks ou usar recurso específico do provedor.

Requisitos​

o passo 1: Criar uma chamada LLM de turno único​

Comece com uma chamada básica, sem usar nenhuma ferramenta. O cliente DatabricksOpenAI configura automaticamente o URL base e a autenticação para seu workspace:

Python
from databricks_openai import DatabricksOpenAI

client = DatabricksOpenAI(use_ai_gateway=True)

response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "Tell me about Databricks"}],
  stream=False
)

print(response.output_text)

o passo 2: Adicionar ferramentas hospedadas para executar o loop do agente​

Ao incluir ferramentas na solicitação, Databricks gerencia um ciclo de várias etapas em seu nome: o modelo decide quais ferramentas chamar, Databricks as executa, envia os resultados de volta para o modelo e repete o processo até que o modelo produza uma resposta final.

Python
response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "Summarize recent customer reviews and flag any urgent issues."}],
  tools=[
    {
      "type": "genie_space",
      "genie_space": {
        "id": "<genie-space-id>",
        "description": "Answers customer review questions using SQL"
      }
    },
    {
      "type": "uc_function",
      "uc_function": {
        "name": "<catalog>.<schema>.<function_name>",
        "description": "Flags a review as requiring urgent attention"
      }
    },
    {
      "type": "knowledge_assistant",
      "knowledge_assistant": {
        "knowledge_assistant_id": "<knowledge-assistant-id>",
        "description": "Answers questions from internal documentation"
      }
    },
    {
      "type": "app",
      "app": {
        "name": "<app-name>",
        "description": "Custom application endpoint"
      }
    },
    {
      "type": "uc_connection",
      "uc_connection": {
        "name": "<uc-connection-name>",
        "description": "Searches the web for current information"
      }
    },
  ],
  stream=True
)

for event in response:
  print(event)

o passo 3 (Opcional): Conecte-se a serviço de terceiros com sistema de gerenciamento de conexões​

Databricks oferece conexões de gerenciamento de sistema para serviços populares de terceiros, como Google Drive, GitHub, Atlassian e SharePoint. Essas conexões são uma alternativa rápida à configuração de seu próprio servidor MCP externo — você ainda pode usar o tipo de ferramenta uc_connection para se conectar a qualquer servidor MCP externo que você mesmo configurou.

As conexões de gerenciamento do sistema exigem que os Conectores de Terceiros para Agentes (versão beta) estejam habilitados em seu workspace. Veja as prévias do Gerenciador Databricks.

Os seguintes conectores são suportados:

Conector

Descrição

system_ai_agent_google_drive

Pesquise e leia arquivos do Google Drive.

system_ai_agent_github_mcp

Acesse repositórios, problemas e solicitações de pull do GitHub.

system_ai_agent_atlassian_mcp

Pesquisa e gerenciamento de recurso Atlassian (Jira, Confluence).

system_ai_agent_sharepoint

Pesquise e leia arquivos do SharePoint.

Passe um conector na matriz tools usando o tipo de ferramenta uc_connection com o campo name definido com o nome do conector:

Python
response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "List my open GitHub pull requests."}],
  tools=[
    {
      "type": "uc_connection",
      "uc_connection": {
        "name": "system_ai_agent_github_mcp"
      }
    }
  ],
)

Autenticação de usuário para máquina (U2M)​

Cada usuário se autentica individualmente. Os tokens OAuth não são compartilhados entre usuários. Na primeira requisição que utiliza um conector para o qual o usuário não foi autenticado, a resposta é concluída com status: "failed" e um erro oauth contendo uma URL de login:

JSON
{
  "status": "failed",
  "error": {
    "code": "oauth",
    "message": "Failed request to <connector>. Please login first at <login-url>."
  }
}

Abra o URL em um navegador, complete o fluxo OAuth e, em seguida, execute novamente a mesma solicitação.

o passo 4: Ativar rastreamento​

Passe um trace_destination no corpo da solicitação para enviar rastreamentos do loop do agente para as tabelas Unity Catalog . Cada solicitação gera um rastreamento que captura a sequência completa de chamadas de modelo e execuções de ferramentas. Se você não definir trace_destination, nenhum rastreamento será gravado. Para obter detalhes sobre a configuração, consulte Armazenar rastreamentos do OpenTelemetry no Unity Catalog.

Usando o cliente Python databricks-openai , passe-o por meio de extra_body:

Python
response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "Tell me about Databricks"}],
  tools=[...],
  extra_body={
    "trace_destination": {
      "catalog_name": "<catalog>",
      "schema_name": "<schema>",
      "table_prefix": "<table-prefix>"
    }
  }
)

Para também retornar o rastreamento diretamente na resposta da API, passe "databricks_options": {"return_trace": True} em extra_body.

Você também pode usar o rastreamento distribuído do MLflow para combinar rastreamentos do código do seu aplicativo e do loop do agente da API do Supervisor em um único rastreamento de ponta a ponta. Propagar cabeçalhos de contexto de rastreamento usando o campo extra_headers :

Python
import mlflow
from mlflow.tracing import get_tracing_context_headers_for_http_request

with mlflow.start_span("client-root") as root_span:
  root_span.set_inputs({"input": "Tell me about Databricks"})

  trace_headers = get_tracing_context_headers_for_http_request()

  response = client.responses.create(
    model="databricks-claude-sonnet-4-5",
    input=[{"type": "message", "role": "user", "content": "Tell me about Databricks"}],
    tools=[...],
    extra_body={
      "trace_destination": {
        "catalog_name": "<catalog>",
        "schema_name": "<schema>",
        "table_prefix": "<table-prefix>"
      }
    },
    extra_headers=trace_headers,
  )

Modo de fundo​

O modo em segundo plano permite a execução de fluxos de trabalho de agentes de longa duração que envolvem múltiplas chamadas de ferramentas e raciocínio complexo sem esperar que elas terminem de forma síncrona. Envie sua solicitação com background=True, receba um ID de resposta imediatamente e aguarde o resultado quando estiver pronto. Isso é especialmente útil para agentes que consultam múltiplas fontes de dados ou encadeiam diversas ferramentas em uma única solicitação.

Criar uma solicitação em segundo plano​

Python
response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "Tell me about Databricks"}],
  tools=[...],
  background=True,
)

print(response.id)     # Use this ID to poll for the result
print(response.status) # "queued" or "in_progress"

Enquete para o resultado​

Use responses.retrieve() para verificar o estado até que ele atinja um estado terminal:

Python
from time import sleep

while response.status in {"queued", "in_progress"}:
  sleep(2)
  response = client.responses.retrieve(response.id)

print(response.output_text)

Modo de fundo com MCP​

Por motivos de segurança, a API do Supervisor exige aprovação explícita do usuário antes de executar qualquer chamada de ferramenta MCP em modo de segundo plano. Quando o loop do agente seleciona uma ferramenta MCP, a resposta é concluída com um mcp_approval_request. Você pode revisar o nome da ferramenta, o rótulo do servidor e os argumentos que o modelo pretende passar:

JSON
{
  "type": "mcp_approval_request",
  "id": "<tool-call-id>",
  "arguments": "{\"query\": \"what is Databricks\", \"count\": 5}",
  "name": "you-search",
  "server_label": "<server-label>",
  "status": "completed"
}

Para aprovar a chamada da ferramenta e continuar o loop do agente, envie um mcp_approval_response de volta no campo input com o histórico completo da conversa:

JSON
{
  "type": "mcp_approval_response",
  "id": "<tool-call-id>",
  "approval_request_id": "<tool-call-id>",
  "approve": true
}
nota

As respostas em modo de segundo plano são mantidas no banco de dados por um período máximo de 30 dias.

Ferramentas suportadas​

Você define as ferramentas na matriz tools da sua solicitação. Cada entrada especifica um type e um objeto de configuração com a mesma key. Por exemplo, uma ferramenta Genie Space tem um objeto "type": "genie_space" e um objeto "genie_space": {...} . A API suporta os seguintes tipos de ferramentas:

Tipo de ferramenta

Descrição

Escopo

genie_space

Consulta um Genie Space para obter respostas a perguntas sobre seus dados. Parâmetros: id, description.

genie

uc_function

Chama uma funçãoUnity Catalog como uma ferramenta de agente. Parâmetros: name, description.

unity-catalog

uc_connection

Conecta-se a um servidor MCP externo através de uma conexão Unity Catalog . Parâmetros: name, description. Para Databricks-gerenciar conexões de sistema, defina name para um conector system_ai_agent_* (consulte o passo 3 (Opcional): Conectar a serviço de terceiros com conexões de gerenciamento de sistema). Observação: servidores MCP personalizados em aplicativos ainda não são suportados.

unity-catalog

app

Chama um endpoint de um aplicativo Databricks. Parâmetros: name, description.

apps

knowledge_assistant

Chama um endpoint do Assistente de Conhecimento . Parâmetros: knowledge_assistant_id, description.

model-serving

Parâmetros suportados​

Cada solicitação à API do Supervisor aceita os seguintes parâmetros.

  • model: um dos seguintes modelos suportados. Altere este campo para trocar de provedor sem modificar o restante do seu código.

  • GPT-5 (databricks-gpt-5)

  • GPT-5.1 (databricks-gpt-5-1)

  • GPT-5.2 (databricks-gpt-5-2)

  • GPT-5.4 (databricks-gpt-5-4)

  • input: as mensagens de conversa a serem enviadas.

  • tools: definições de ferramentas hospedadas (genie_space, uc_function, knowledge_assistant, app, uc_connection).

  • instructions: um comando do sistema para orientar o comportamento do supervisor.

  • stream: definido como true para respostas de transmissão.

  • backgroundDefina como true para executar a solicitação de forma assíncrona. Retorna um ID de resposta que você consulta com responses.retrieve(). Consulte o modo em segundo plano.

  • trace_destination: objeto opcional com campos catalog_name, schema_name e table_prefix . Quando configurada, a API do Supervisor grava um registro de todo o ciclo do agente nas tabelas especificadas Unity Catalog . Passe via extra_body no cliente Python.

A API não suporta parâmetros de inferência como temperature. O servidor gerencia isso internamente.

Limitações​

A API do Supervisor possui as seguintes limitações:

  • Tempo de execução em segundo plano : As solicitações em segundo plano têm um tempo máximo de execução de 30 minutos.
  • Chamada de funções no lado do cliente : Somente ferramentas hospedadas são suportadas. Você não pode passar definições de ferramentas function para o cliente executar e não pode misturar ferramentas hospedadas com ferramentas function do lado do cliente na mesma solicitação.
  • transmissão em modo de fundo : stream e background não podem ser ambos true na mesma solicitação.
  • Execução durável : A recuperação automática de falhas ou interrupções com garantias de execução exatamente uma vez para o loop do agente não é suportada.
  • Databricks Apps OBO não são suportados : a autorização em nome do usuário não é suportada para a API do Supervisor. Para usar a API do Supervisor em Databricks Apps, utilize a autorização do sistema e conceda permissões para suas ferramentas.

Próximos passos​

Nesta página