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 do espaço de trabalho podem ativar esse 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 ai-gateway/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",
      "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"
      }
    },
    {
      "type": "sandbox"
    },
  ],
  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, SharePoint e Glean. 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.

system_ai_agent_glean_mcp

Pesquise em todo o conteúdo empresarial indexado pelo Glean.

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 (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 opcional description e um objeto JSON Schema parameters :

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 requisições, portanto, uma chamada de função do lado do cliente requer duas etapas:

  1. Turno 1. O modelo retorna um item function_call (por exemplo, "chame get_weather com location=Paris") em vez de uma resposta final.
  2. Seu código executa a 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 utiliza 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 mais padrões (transmissão, ferramentas hospedadas e de cliente, aprovação MCP, resolução de problemas), consulte a habilidade de chamada de função do lado do cliente API do Supervisor.

o passo 5: 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={
    &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 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={
      &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 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 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 (string, opcional): Nome de exibição mostrado ao modelo.
  • description (string, opcional): Dica para o modelo sobre quando chamar esta ferramenta.

Além disso, cada objeto de ferramenta contém um objeto de configuração aninhado cuja chave 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

sandbox

JSON
{
  "type": "sandbox"
}

Nenhuma

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, apenas os endpoints ResponseAgent, ChatCompletions e ChatAgent têm suporte.

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

Para uc_connection, use o nome da conexão que você criou para um servidor MCP externo ou um conector gerenciado pelo sistema system_ai_agent_* (consulte o passo 3 (opcional): Conecte-se a serviços de terceiros com conexões gerenciadas pelo sistema). Servidores MCP personalizados em Aplicativos ainda não são compatíveis.

Ferramenta Sandbox​

A ferramenta sandbox permite que o agente execute código gerado pelo modelo em uma sessão de compute serverless isolada para analisar dados, transformar arquivos e calcular resultados. Ele suporta Python (default), SQL e comandos de shell. O modelo escreve o código e a API do Supervisor o executa, portanto você não precisa fornecer o código.

A ferramenta não requer nenhuma configuração. Passe-o como {"type": "sandbox"}:

Python
response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "Compute the month-over-month growth from the revenue table and plot it."}],
  tools=[
    {
      "type": "table",
      "table": {"name": "<catalog>.<schema>.revenue"}
    },
    {
      "type": "sandbox"
    }
  ],
)

O sandbox não usa seus próprios campos de acesso a dados. Em vez disso, ele pode ler as tabelas do Unity Catalog declaradas com a ferramenta table na mesma solicitação. Os arquivos do workspace estão disponíveis em /Workspace.

O sandbox bloqueia todo o acesso à internet de saída (saída de rede) independentemente da política de rede do seu workspace. O código em execução no sandbox não pode alcançar endpoints externos.

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, dashboard, uc_function, table, knowledge_assistant, serving_endpoint, web_search, vector_search_index, volume, app, uc_connection, sandbox) e ferramentas de função do lado do cliente (function). Consulte o passo 4 (Opcional): Adicione uma ferramenta de função do lado do cliente e uma ferramenta sandbox.

  • 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.
  • 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.
  • Elegibilidade do workspace para pesquisa na Web : A ferramenta web_search não está disponível em workspaces com compliance HIPAA/BAA habilitado. Está disponível apenas em regiões com um modelo nativo com capacidade de pesquisa na web ou processamento entre geografias ativado. Solicitações que incluem web_search de workspaces não elegíveis são rejeitadas.

Próximos passos​

Nesta página