API do Supervisor (Beta)

Importante

Esse recurso está em Beta. Os administradores da conta podem controlar o acesso a esse recurso na página Visualizações . Consulte Gerenciar visualizações do Azure Databricks.

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 /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.

Requisitos

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",
      "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)

Etapa 3: 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 como armazenar os rastreamentos do MLflow no Catálogo 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
}

Note

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

Ferramentas com suporte

Você define as ferramentas na tools matriz da sua solicitação. Cada entrada especifica um type e um objeto de configuração com a mesma chave. Por exemplo, uma ferramenta de espaço do Genie tem "type": "genie_space" e um objeto "genie_space": {...}. A API dá suporte aos seguintes tipos de ferramenta:

Tipo de ferramenta Descrição Scope
genie_space Consulta um espaço do Genie para responder perguntas sobre seus dados. Parâmetros: id, description. genie
uc_function Chama uma função do Unity Catalog como ferramenta de agente. Parâmetros: name, description. unity-catalog
uc_connection Conecta-se a um servidor MCP externo por meio de uma conexão do Catálogo do Unity. Parâmetros: name, description. Observação: ainda não há suporte para servidores MCP personalizados em Aplicativos. unity-catalog
app Chama um endpoint de um aplicativo Azure 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 com suporte

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

  • input: as mensagens de conversa a serem enviadas.
  • tools: definições de ferramenta hospedada (genie_space, , uc_function, knowledge_assistant, app, uc_connection).
  • 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.

Limitações

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.
  • Chamada de função do lado do cliente: há suporte apenas para ferramentas hospedadas. Não é possível passar function definições de ferramenta para o cliente executar, e não é possível misturar ferramentas hospedadas com ferramentas do lado do cliente function na mesma solicitação.
  • Streaming no modo em segundo plano: stream e background não podem ambos estar como true 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.
  • Azure Databricks Apps OBO sem suporte: autorização em nome de outro usuário não é suportada para a Supervisor API. Para usar a API de Supervisor em aplicativos Azure Databricks, use system authorization e conceda permissões para suas ferramentas.

Próximas Etapas 

  • Last updated on