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

API do Supervisor (Beta)

info

Beta

Este recurso está em Beta. Os administradores de workspace podem habilitar este recurso na página Visualizações . Consulte Gerenciar prévias do 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. Define-se o modelo, as ferramentas e as instruções em uma solicitação para um endpoint (POST ai-gateway/mlflow/v1/responses) compatível com OpenResponses, e o Databricks executa o loop do agente: chamando repetidamente o modelo, selecionando e executando ferramentas e sintetizando uma resposta final.

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

  • Agente Supervisor Agent Bricks (recomendado): Totalmente declarativo com otimização de feedback humano para a mais alta qualidade.
  • API do supervisor : crie um agente personalizado programaticamente—escolha modelos no Runtime, controle quais ferramentas usar por solicitação ou itere durante o desenvolvimento. Também a escolha certa quando você precisa de controle sobre a escolha do modelo enquanto transfere o gerenciamento do loop do agente para o Databricks.
  • APIs unificadas ou nativas do AI Gateway : escreva seu próprio loop de agente. A Databricks fornece apenas a camada de inferência de 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 portar código existente para a Databricks ou ao usar recursos específicos do provedor.

Requisitos​

Etapa 1: Crie uma chamada LLM de turno único​

Comece com uma chamada básica sem ferramentas. O cliente DatabricksOpenAI configura automaticamente a URL base e a autenticação para o 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: Adicione ferramentas hospedadas para realizar a execução do loop do agente​

Quando você inclui ferramentas na solicitação, o Databricks gerencia um loop de múltiplas interações em seu nome: o modelo decide quais ferramentas chamar, o Databricks as executa, alimenta os resultados de volta ao modelo e repete 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",
      "name": "Customer reviews",
      "description": "Answers customer review questions using SQL",
      "genie_space": {"space_id": "<genie-space-id>"}
    },
    {
      "type": "dashboard",
      "name": "Customer reviews dashboard",
      "description": "Answers questions about the customer reviews dashboard",
      "dashboard": {"dashboard_id": "<dashboard-id>"}
    },
    {
      "type": "uc_function",
      "name": "Flag urgent review",
      "description": "Flags a review as requiring urgent attention",
      "uc_function": {"name": "<catalog>.<schema>.<function_name>"}
    },
    {
      "type": "table",
      "table": {
        "name": "<catalog>.<schema>.<table_name>",
        "description": "Reads from the customer reviews table"
      }
    },
    {
      "type": "vector_search_index",
      "vector_search_index": {
        "name": "<catalog>.<schema>.<index_name>",
        "description": "Searches the product documentation index for relevant passages"
      }
    },
    {
      "type": "knowledge_assistant",
      "name": "Internal docs",
      "description": "Answers questions from internal documentation",
      "knowledge_assistant": {"knowledge_assistant_id": "<knowledge-assistant-id>"}
    },
    {
      "type": "serving_endpoint",
      "name": "Custom agent",
      "description": "Calls a custom agent served from a Databricks model serving endpoint",
      "serving_endpoint": {"name": "<serving-endpoint-name>"}
    },
    {
      "type": "vector_search_index",
      "name": "Product docs",
      "description": "Looks up product documentation by semantic search",
      "vector_search_index": {
        "name": "<catalog>.<schema>.<index>",
        "columns": ["title", "content"]
      }
    },
    {
      "type": "app",
      "name": "Support agent",
      "description": "Custom application endpoint",
      "app": {"name": "<app-name>"}
    },
    {
      "type": "uc_connection",
      "name": "GitHub",
      "description": "Searches GitHub for issues and pull requests",
      "uc_connection": {"name": "<uc-connection-name>"}
    },
    {
      "type": "web_search",
      "name": "Web search",
      "description": "Searches the public web for current information and returns a synthesized answer with citations",
      "web_search": {}
    },
    {
      "type": "volume",
      "volume": {
        "name": "<catalog>.<schema>.<volume>",
        "description": "Searches files in a Unity Catalog volume"
      }
    },
  ],
  stream=True
)

for event in response:
  print(event)

O passo 3 (Opcional): Conecte-se a serviços de terceiros com conexões gerenciadas pelo sistema​

O Databricks fornece conexões gerenciadas pelo sistema para serviços de terceiros populares, como Google Drive, GitHub, Atlassian, SharePoint e Glean. Essas conexões são uma alternativa rápida para configurar o seu próprio Servidor MCP externo — você ainda pode usar o tipo de ferramenta uc_connection para conectar-se a qualquer Servidor MCP externo que tenha configurado.

As conexões gerenciadas pelo sistema exigem que a versão Beta de Conectores de Terceiros para Agentes seja habilitada no seu workspace. Consulte Gerenciar prévias do 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 pull do GitHub.

system_ai_agent_atlassian_mcp

Pesquise e gerencie recursos da Atlassian (Jira, Confluence).

system_ai_agent_sharepoint

Pesquise e leia arquivos do SharePoint.

system_ai_agent_glean_mcp

Pesquise em todo o conteúdo corporativo indexado por Glean.

Passe um conector na matriz tools usando o tipo de ferramenta uc_connection com o campo name definido para 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 solicitação que usa um conector em que o usuário não se autenticou, a resposta é concluída com status: "failed" e um erro oauth contendo um URL de login:

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

Abra a URL em um navegador, conclua o fluxo OAuth e, em seguida, realize a execução novamente da mesma solicitação.

O passo 4 (Opcional): Adicionar uma ferramenta de função do lado do cliente​

Use as ferramentas function quando quiser que seu aplicativo execute lógica personalizada juntamente com as ferramentas hospedadas no Databricks. Declare uma ferramenta de função com type: "function", um name, um description opcional e um objeto parameters de esquema JSON:

Python
response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "<user prompt>"}],
  tools=[
    {
      "type": "function",
      "name": "<client-side-function-name>",
      "description": "<description of what this function does>",
      "parameters": {
        "type": "object",
        "properties": {"<param-name>": {"type": "string"}},
        "required": ["<param-names>"],
        "additionalProperties": False,
      },
    }
  ],
)

A API do Supervisor não armazena o estado da conversa entre as solicitações, portanto, uma chamada de função do lado do cliente leva duas etapas:

  1. Turno 1. O modelo retorna um item function_call (por exemplo, “chamar get_weather com location=Paris”) em vez de uma resposta final.
  2. Seu código realiza a execução da função localmente e produz um resultado.
  3. Turno 2. Chame responses.create() novamente, passando a entrada original mais o function_call do modelo mais um novo function_call_output com seu resultado. O modelo usa o resultado para produzir a resposta final.

Exemplo de ferramenta de função do lado do cliente

Python
import json
from databricks_openai import DatabricksOpenAI

client = DatabricksOpenAI(use_ai_gateway=True)
MODEL = "databricks-claude-sonnet-4-5"

GET_WEATHER = {
    "type": "function",
    "name": "get_weather",
    "description": "Get the current weather for a location.",
    "parameters": {
        "type": "object",
        "properties": {"location": {"type": "string"}},
        "required": ["location"],
        "additionalProperties": False,
    },
}

def run_get_weather(args):
    return json.dumps({
        "location": args["location"],
        "temp_c": 18,
        "condition": "sunny",
    })

CLIENT_TOOLS = {"get_weather": run_get_weather}
TOOLS = [GET_WEATHER]

input_list = [{"role": "user", "content": "What's the weather in Paris?"}]

# Turn 1 — model emits a function_call
resp = client.responses.create(model=MODEL, input=input_list, tools=TOOLS)

# Echo the model's turn into history, then execute pending client function_calls
input_list += [item.model_dump() for item in resp.output]
for item in resp.output:
    if item.type == "function_call" and item.name in CLIENT_TOOLS:
        args = json.loads(item.arguments)
        # Execute the client-side function with the model's arguments
        # and append the result so the model can use it on the next turn.
        tool_output = CLIENT_TOOLS[item.name](args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": tool_output,
        })

# Turn 2 — model produces the final answer using the tool result
final = client.responses.create(model=MODEL, input=input_list, tools=TOOLS)
print(final.output_text)

Para obter mais padrões (transmissão, ferramentas de cliente hospedadas e cliente, aprovação MCP, solução de problemas), consulte a habilidade de chamada de função do lado do cliente da API do Supervisor.

O passo 5: Habilitar rastreamento​

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

Usando o cliente databricks-openai Python, passe-o via 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={
    &quot;trace_destination&quot;: {
      &quot;catalog_name&quot;: &quot;&lt;catalog&gt;&quot;,
      &quot;schema_name&quot;: &quot;&lt;schema&gt;&quot;,
      &quot;table_prefix&quot;: &quot;&lt;table-prefix&gt;&quot;
    }
  }
)

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 o loop do agente da API do Supervisor em um único rastreamento de ponta a ponta. Propague os 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={
      &quot;trace_destination&quot;: {
        &quot;catalog_name&quot;: &quot;&lt;catalog&gt;&quot;,
        &quot;schema_name&quot;: &quot;&lt;schema&gt;&quot;,
        &quot;table_prefix&quot;: &quot;&lt;table-prefix&gt;&quot;
      }
    },
    extra_headers=trace_headers,
  )

Modo em segundo plano​

O modo em segundo plano permite realizar a execução de fluxos de trabalho de agente de longa duração que envolvem múltiplas chamadas de ferramenta e raciocínio complexo sem esperar que eles terminem de forma síncrona. Envie sua solicitação com background=True, receba um ID de resposta imediatamente e consulte o resultado quando estiver pronto. Isso é especialmente útil para agentes que consultam múltiplas fontes de dados ou encadeiam várias 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"

Sondar o resultado​

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

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 em segundo plano com MCP​

Para segurança, a API do Supervisor requer 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, passe um mcp_approval_response de volta no campo input com a história completa da conversa:

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

As respostas do modo em segundo plano são retidas no banco de dados por um máximo de 30 dias.

Ferramentas suportadas​

Você define ferramentas na matriz tools da sua solicitação. Todo objeto de ferramenta compartilha três campos de nível superior:

  • type (string, obrigatório): O discriminador que seleciona o tipo de ferramenta.
  • name (strings, opcional): Nome de exibição exibido para o modelo.
  • description (strings, opcional): Dica para o modelo sobre quando chamar esta ferramenta.

Além disso, cada objeto de ferramenta carrega um objeto de configuração aninhado cuja key corresponde ao valor type. A tabela abaixo documenta a configuração aninhada para cada tipo de ferramenta compatível.

Tipo de ferramenta

Exemplo

Escopo

genie_space

JSON
{
  "type": "genie_space",
  "name": "Customer reviews",
  "genie_space": {
    "space_id": "<id>"
  }
}

genie

dashboard

JSON
{
  "type": "dashboard",
  "name": "Sales dashboard",
  "dashboard": {
    "dashboard_id": "<id>"
  }
}

dashboards

uc_function

JSON
{
  "type": "uc_function",
  "name": "Flag urgent review",
  "uc_function": {
    "name": "<catalog>.<schema>.<function>"
  }
}

unity-catalog

table

JSON
{
  "type": "table",
  "name": "Customer reviews",
  "table": {
    "name": "<catalog>.<schema>.<table_name>"
  }
}

unity-catalog

knowledge_assistant

JSON
{
  "type": "knowledge_assistant",
  "name": "Internal docs",
  "knowledge_assistant": {
    "knowledge_assistant_id": "<id>"
  }
}

model-serving

serving_endpoint

JSON
{
  "type": "serving_endpoint",
  "name": "Custom agent",
  "serving_endpoint": {
    "name": "<endpoint-name>"
  }
}

model-serving

web_search

JSON
{
  "type": "web_search",
  "name": "Web search",
  "web_search": {}
}

model-serving

vector_search_index

JSON
{
  "type": "vector_search_index",
  "name": "Product docs",
  "vector_search_index": {
    "name": "<catalog>.<schema>.<index>",
    "columns": ["title", "content"]
  }
}

vector-search

volume

JSON
{
  "type": "volume",
  "volume": {
    "name": "<catalog>.<schema>.<volume>",
    "description": "Searches files in a Unity Catalog volume"
  }
}

unity-catalog

app

JSON
{
  "type": "app",
  "name": "Support agent",
  "app": {
    "name": "<app-name>"
  }
}

apps

uc_connection

JSON
{
  "type": "uc_connection",
  "name": "GitHub",
  "uc_connection": {
    "name": "system_ai_agent_github_mcp"
  }
}

unity-catalog

function

JSON
{
  "type": "function",
  "name": "get_weather",
  "description": "Get the current weather for a location.",
  "parameters": {
    "type": "object",
    "properties": { "location": { "type": "string" } },
    "required": ["location"]
  }
}

Nenhuma

Para serving_endpoint, somente os endpoints ResponseAgent, ChatCompletions e ChatAgent são compatíveis.

Para app, somente aplicativos MCP (com o prefixo mcp-) e aplicativos ResponseAgent personalizados (com o prefixo agent-) são compatíveis.

Para uc_connection, use o nome de conexão criado para um servidor MCP externo, ou um conector system_ai_agent_* gerenciado pelo sistema (veja O passo 3 (Opcional): Conectar-se a serviços de terceiros com conexões gerenciadas pelo sistema). Servidores MCP personalizados em Apps não são suportados.

Execução de código​

Quando uma solicitação precisa de compute, o Supervisor executa o código gerado pelo modelo em uma sessão de compute serverless isolada para analisar dados, transformar arquivos ou executar cálculos. Ele suporta comandos Python (default), SQL e shell. O Supervisor escreve e executa o código em si quando necessário, de modo que não é preciso ativar, configurar ou fornecer o código.

A execução de código é executada em um sandbox restrito com:

  • Sem acesso à internet. Ele bloqueia toda a saída de rede, independentemente da política de rede do seu workspace, portanto, o código em execução no sandbox não pode alcançar endpoints externos.
  • Somente acesso Databricks com escopo. Não possui acesso a dados próprio. Ele pode ler as tabelas do Unity Catalog que você declara com a ferramenta table na mesma solicitação.

Parâmetros compatíveis​

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

  • model: um dos seguintes modelos compatíveis. Deve-se alterar este campo para alternar entre provedores sem alterar o restante do 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 da conversa a serem enviadas.

  • tools: definições de ferramentas hospedadas (genie_space, dashboard, uc_function, table, knowledge_assistant, serving_endpoint, web_search, vector_search_index, volume, app, uc_connection) e ferramentas de função do lado do cliente (function). Consulte o passo 4 (Opcional): Adicionar uma ferramenta de função do lado do cliente.

  • instructions: um prompt do sistema para dar guia ao comportamento do supervisor.

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

  • background: defina como true para realizar a execução da solicitação de forma assíncrona. Retorna um ID de resposta que você consulta com responses.retrieve(). Consulte Modo de plano de fundo.

  • trace_destination: objeto opcional com campos catalog_name, schema_name e table_prefix. Quando configurada, a API do Supervisor escreve um rastro do loop completo do agente para as tabelas especificadas do Unity Catalog. Passe via extra_body no cliente Python.

A API não oferece suporte a parâmetros de inferência como temperature. O servidor os gerencia internamente.

Autorização​

A API Supervisor realiza a execução do loop do agente com as credenciais do chamador, portanto, as ferramentas que ele invoca respeitam as permissões do Unity Catalog do chamador. Ao chamar a API diretamente, o cliente DatabricksOpenAI autentica como você.

Ao chamar a API do Supervisor de um aplicativo Databricks, é possível executar ferramentas como a entidade de serviço Databricks do aplicativo (autorização do aplicativo) ou como o usuário solicitante (autorização do usuário). Para autorização do aplicativo, conceda as permissões da entidade de serviço do Databricks do aplicativo para cada ferramenta. Para autorização do usuário, encaminhe os tokens do usuário para o cliente DatabricksOpenAI e adicione os escopos de autorização do usuário necessários. Consulte Execução de ferramentas como o usuário solicitante.

Limitações​

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

  • Runtime do modo de segundo plano : as solicitações do modo de segundo plano têm um tempo máximo de execução de 30 minutos.
  • Transmissão em modo de segundo plano : 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.
  • Elegibilidade de workspace para pesquisa na web : A ferramenta web_search não está disponível em workspaces com compliance HIPAA/BAA ativado. Está disponível apenas em regiões com um modelo nativo com capacidade de pesquisa na web ou com processamento entre geografias ativado. Solicitações que incluem web_search de workspaces não qualificados são rejeitadas.

Recursos adicionais​

Nesta página