API do Supervisor (Beta)

A API Supervisor simplifica a construção de agentes personalizados no Azure Databricks com suporte para o modo background para tarefas de longa execução. Você define o modelo, as ferramentas e as instruções em uma solicitação para um ponto de extremidade compatível com OpenResponses (POST ai-gateway/mlflow/v1/responses) e Azure Databricks executa o loop do agente para você: chamar repetidamente o modelo, selecionar e executar ferramentas e sintetizar uma resposta final.

Há três abordagens para criar um agente de chamada de ferramenta personalizado no Azure Databricks:

• Agente Supervisor do Agent Bricks (recomendado): totalmente declarativo com otimização de feedback humano para alcançar a mais alta qualidade.
• API do Supervisor: crie um agente personalizado programaticamente— escolha modelos em runtime, controle quais ferramentas usar por solicitação ou itere durante o desenvolvimento. Além disso, é a escolha certa quando você precisa de controle sobre a seleção do modelo enquanto delega o gerenciamento do loop do agente ao Azure Databricks.
• APIs unificadas ou nativas do AI Gateway: Desenvolva seu próprio loop de agente. Azure Databricks fornece apenas a camada de inferência LLM. Use APIs unificadas sempre que possível para habilitar a alternância de modelos ou APIs nativas específicas do provedor (/openai, /anthropic, /gemini) ao portar o código existente para Azure Databricks ou usar recursos específicos do provedor.

Requirements

• Governança de IA com o Gateway de IA do Unity habilitado para sua conta. Consulte Gerenciar visualizações do Azure Databricks.
  • Como a API de Supervisor é executada por meio do Gateway de IA do Unity, os recursos do Gateway de IA, como tabelas de inferência, limites de taxa e fallbacks, se aplicam. Não há suporte para o acompanhamento de uso nesta versão beta.
• Armazene rastreamentos OpenTelemetry no Catálogo do Unity habilitados para sua conta. Consulte Gerenciar visualizações do Azure Databricks.
  • Armazena rastreamentos do loop do agente da API do Supervisor nas tabelas do Unity Catalog.
• Um espaço de trabalho Azure Databricks em uma região suportada.
• Catálogo do Unity habilitado para seu ambiente de trabalho. Consulte Habilitar um workspace para o Unity Catalog.
• As ferramentas que você passa (Genie Spaces, funções do Catálogo do Unity, servidores MCP, assistentes de conhecimento, Aplicativos) já devem estar configuradas e acessíveis.
• O pacote databricks-openai instalado: pip install databricks-openai

Etapa 1: Criar uma chamada LLM de turno único

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

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)

Etapa 2: Adicionar ferramentas hospedadas para executar o loop do agente

Quando você inclui ferramentas na solicitação, Azure Databricks gerencia um loop de vários turnos em seu nome: o modelo decide quais ferramentas chamar, Azure Databricks as executa, alimenta os resultados de volta para o modelo e se repete até que o modelo produza uma resposta final.

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)

Etapa 3 (opcional): conectar-se a serviços de terceiros com conexões gerenciadas pelo sistema

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

As conexões gerenciadas pelo sistema exigem que os Conectores de Terceiros para Agentes Beta sejam habilitados em seu workspace. Consulte Gerenciar visualizações do Azure Databricks.

Há suporte para os seguintes conectores:

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

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 U2M (usuário para máquina)

Cada usuário é autenticado individualmente. Os tokens OAuth não são compartilhados entre os usuários. Na primeira solicitação que usa um conector que o usuário não autenticou, a resposta é concluída com um status: "failed" e um oauth erro que contém uma URL de login.

{
  "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 execute novamente a mesma solicitação.

Etapa 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 junto com as ferramentas hospedadas no Azure Databricks. Declare uma ferramenta de função com type: "function", um name, um description opcional e um objeto parameters de Esquema JSON:

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 de conversa entre solicitações, portanto, uma chamada de função do lado do cliente tem duas voltas:

1. Vire 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 executa a função localmente e produz um resultado.
3. Gire 2. Chame responses.create() novamente, passando a entrada original, mais o function_call do modelo e um novo function_call_output com seu resultado. O modelo usa o resultado para produzir a resposta final.

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, hospedagem e ferramentas do cliente, aprovação de MCP, solução de problemas), consulte a habilidade de chamada de funções no cliente da API Supervisor.

Etapa 5: Habilitar o 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 capturando a sequência completa de chamadas de modelo e execuções de ferramentas. Se você não definir trace_destination, nenhum rastro será gravado. Para obter detalhes de instalação, consulte Os rastreamentos da Store OpenTelemetry no Catálogo do Unity.

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

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 aplicativo e do loop do agente de API do Supervisor em um único rastreamento de ponta a ponta. Propagar cabeçalhos de contexto de rastreamento usando o campo extra_headers:

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 em segundo plano

O modo em segundo plano permite executar fluxos de trabalho de agente de execução longa que envolvem várias chamadas de ferramenta e raciocínio complexo sem esperar que eles sejam concluídos de forma síncrona. Envie sua solicitação com background=True, receba uma ID de resposta imediatamente e pesquise o resultado quando ele estiver pronto. Isso é especialmente útil para agentes que consultam várias fontes de dados ou encadeiam várias ferramentas em uma única solicitação.

Criar uma solicitação em segundo plano

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"

Sondagem para o resultado

Use responses.retrieve() para verificar o status até atingir um estado terminal:

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 no modo em segundo plano. Quando o loop do agente seleciona uma ferramenta MCP, a resposta é concluída com um mcp_approval_request. Você pode examinar o nome da ferramenta, o rótulo do servidor e os argumentos que o modelo pretende passar:

{
  "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 de ferramenta e continuar o loop do agente, passe um mcp_approval_response de volta no campo input com o histórico completo da conversa.

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

Ferramentas com suporte

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

• type (cadeia de caracteres, obrigatório): o discriminador que seleciona o tipo de ferramenta.
• name (cadeia de caracteres, opcional): nome de exibição mostrado para o modelo.
• description (cadeia de caracteres, opcional): dica para o modelo sobre quando chamar essa ferramenta.

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

Para serving_endpoint, há suporte apenas para os endpoints ResponseAgent, ChatCompletions e ChatAgent.

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

Para uc_connectionusar o nome da conexão que você criou para um servidor MCP externo ou um system_ai_agent_* conector gerenciado pelo sistema (consulte a Etapa 3 (Opcional): conecte-se a serviços de terceiros com conexões gerenciadas pelo sistema). Não há suporte para servidores MCP personalizados em Aplicativos.

Execução de código

Quando uma solicitação precisa de computação, o Supervisor executa o código gerado por modelo em uma sessão de computação sem servidor em área restrita para analisar dados, transformar arquivos ou executar cálculos. Ele dá suporte a comandos Python (padrão), SQL e shell. O Supervisor grava e executa o próprio código quando necessário, para que você não habilite, configure ou forneça o código.

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

• Sem acesso à Internet. Ele bloqueia todo o tráfego de saída da rede, independentemente da política de rede do seu espaço de trabalho, portanto o código em execução na sandbox não pode acessar endpoints externos.
• Acesso somente ao Azure Databricks com escopo definido. Não tem acesso próprio a dados. Ele pode ler as tabelas do Catálogo do Unity que você declara com a table ferramenta na mesma solicitação.

Parâmetros com suporte

Cada solicitação à API supervisor aceita os parâmetros a seguir.

• model: um dos seguintes modelos com suporte. Altere esse campo para alternar provedores sem alterar o restante do código.
  • Claude-Haiku-4.5 (databricks-claude-haiku-4-5)
  • Claude-Opus-4.1 (databricks-claude-opus-4-1)
  • Claude-Opus-4.5 (databricks-claude-opus-4-5)
  • Claude-Opus-4.6 (databricks-claude-opus-4-6)
  • Claude-Sonnet-4 (databricks-claude-sonnet-4)
  • Claude-Sonnet-4.5 (databricks-claude-sonnet-4-5)
  • Claude-Sonnet-4.6 (databricks-claude-sonnet-4-6)

• input: as mensagens de conversa a serem enviadas.
• tools: definições de ferramenta hospedada (genie_space, , dashboard, uc_function, table, knowledge_assistant, serving_endpoint, web_search, vector_search_index, , volume, app, ) uc_connectione ferramentas de função do lado do cliente (function). Consulte a Etapa 4 (Opcional): Adicionar uma ferramenta de função do lado do cliente.
• instructions: um prompt do sistema para orientar o comportamento do supervisor.
• stream: definir como true para transmitir respostas.
• background: definido para true executar a solicitação de forma assíncrona. Retorna um ID de resposta que você consulta com responses.retrieve(). Consulte o modo Plano de Fundo.
• trace_destination: objeto opcional com catalog_name, schema_namee table_prefix campos. Quando configurada, a API do Supervisor grava uma trilha do loop completo do agente nas tabelas especificadas do Unity Catalog. Passe por extra_body no cliente Python.

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

Authorization

A API do Supervisor executa o loop do agente com as credenciais do chamador, portanto, as ferramentas invocadas respeitam as permissões do Catálogo do Unity do chamador. Quando você chama a API diretamente, o DatabricksOpenAI cliente é autenticado como você.

Ao chamar a API do Supervisor de um aplicativo Azure Databricks, você pode executar ferramentas como a entidade de serviço do aplicativo (autorização de aplicativo) ou como o usuário solicitante (autorização do usuário). Para autorizar o aplicativo, conceda permissões ao principal de serviço do aplicativo em cada ferramenta. Para autorização do usuário, encaminhe o token do usuário para o DatabricksOpenAI cliente e adicione os escopos de autorização de usuário necessários. Veja Executar ferramentas como o usuário solicitante.

Limitations

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

• Runtime do modo de tela de fundo: as solicitações de modo de plano de fundo têm um tempo máximo de execução de 30 minutos.
• Streaming no modo em segundo plano: e stream não podem ambos estar como background na mesma solicitação.
• Execução durável: não há suporte para recuperação automática de falhas ou interrupções com garantias de execução exatamente uma vez para o loop do agente.
• Elegibilidade do workspace para pesquisa na Web: A ferramenta web_search não está disponível em workspaces com conformidade com HIPAA/BAA habilitada. Ele só está disponível em regiões com um modelo nativo compatível com pesquisa na Web ou processamento entre geografias habilitado. As solicitações que incluem web_search de espaços de trabalho não elegíveis são rejeitadas.

Recursos adicionais

• Criar um agente personalizado usando a API do Supervisor (Beta)
• Usar o Supervisor Agent para criar um sistema de vários agentes coordenado
• Serviços de modelo de consulta
• Governança de IA com o Gateway de IA do Unity