API Supervisor (Beta)

Importante

Este recurso está em versão Beta. Os administradores de contas podem controlar o acesso a esta funcionalidade a partir da página de Pré-visualizações . Ver Gerir as pré-visualizações de Azure Databricks.

A API Supervisor simplifica a criação de agentes personalizados em Azure Databricks com suporte para modo em segundo plano para tarefas de longa duração. Defines o modelo, as ferramentas e as instruções num único pedido para um endpoint compatível com OpenResponses (POST /mlflow/v1/responses), e Azure Databricks executa o ciclo do agente por ti: chamando repetidamente o modelo, selecionando e executando ferramentas, e sintetizando uma resposta final.

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

  • Agente Supervisor Bricks (recomendado): Totalmente declarativo com otimização por feedback humano para máxima qualidade.
  • API Supervisor: Construa um agente personalizado programaticamente — escolha modelos em tempo de execução, controle que ferramentas usar por pedido ou itere durante o desenvolvimento. Também é a escolha certa quando precisas de controlo sobre a escolha do modelo ao transferir a gestão do loop de agentes para o Azure Databricks.
  • API unificadas ou nativas do AI Gateway: Escreva o seu próprio loop de agentes. O Azure Databricks fornece apenas a camada de inferência do LLM. Use APIs unificadas sempre que possível para permitir modelos de comutação, ou APIs nativas específicas de fornecedores (/openai, /anthropic, /gemini) ao portar código existente para Azure Databricks ou ao utilizar funcionalidades específicas de cada fornecedor.

Requisitos

Passo 1: Criar uma chamada LLM de um único turno

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

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)

Passo 2: Adicionar ferramentas alojadas para executar o loop do agente

Quando inclui ferramentas no pedido, o Azure Databricks gere um ciclo de múltiplas voltas em seu nome: o modelo decide que ferramentas chamar, o Azure Databricks executa-as, devolve os resultados ao modelo e 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)

Passo 3 (Opcional): Ligue-se a serviços de terceiros com ligações geridas pelo sistema

O Azure Databricks fornece ligações geridas por sistema para serviços populares de terceiros como Google Drive, GitHub, Atlassian e SharePoint. Estas ligações são uma alternativa rápida à configuração do seu próprio servidor MCP externo — pode ainda usar o uc_connection tipo de ferramenta para se ligar a qualquer servidor MCP externo que tenha configurado por si próprio.

As ligações geridas pelo sistema exigem que os Conectores de Terceiros para Agentes Beta estejam ativados no seu espaço de trabalho. Ver Gerir as pré-visualizações de Azure Databricks.

Os seguintes conectores são suportados:

Connector Description
system_ai_agent_google_drive Pesquise e leia ficheiros no Google Drive.
system_ai_agent_github_mcp Aceda a repositórios, issues e pull requests do GitHub.
system_ai_agent_atlassian_mcp Pesquise e gere recursos atlassianos (Jira, Confluence).
system_ai_agent_sharepoint Pesquise e leia ficheiros do SharePoint.

Insira um conector no tools array usando a ferramenta do tipo uc_connection com o campo name definido para 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 Utilizador-para-Máquina (U2M)

Cada utilizador autentica-se individualmente. Os tokens OAuth não são partilhados entre utilizadores. No primeiro pedido que utiliza um conector que o utilizador não autenticou, a resposta termina com status: "failed" e com um erro que contém uma URL para início de sessão:

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

Abra o URL num navegador, complete o fluxo OAuth e depois execute novamente o mesmo pedido.

Passo 4: Ativar o rastreio

Passe um trace_destination no corpo do pedido para enviar rastros do ciclo do agente para as tabelas do Catálogo Unity. Cada pedido gera um rastreio que captura a sequência completa de chamadas de modelo e execuções de ferramentas. Se não definires trace_destination, não são escritos registos. Para detalhes de configuração, consulte Armazenamento de traços OpenTelemetry no Unity Catalog.

Usando o cliente databricks-openai Python, passe via 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 devolver o traço diretamente na resposta da API, passe "databricks_options": {"return_trace": True} em extra_body.

Também pode usar o rastreamento distribuído do MLflow para combinar traços do código da sua aplicação e do loop do agente da API Supervisor num único traço de ponta a ponta. Propagar cabeçalhos de contexto de traço 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 de fundo

O modo em segundo plano permite-lhe executar fluxos de trabalho de agentes de longa duração que envolvem múltiplas chamadas de ferramenta e raciocínios complexos sem esperar que terminem sincronizados. Submeta o seu pedido com background=True, receba imediatamente um ID de resposta e solicite o resultado quando estiver pronto. Isto é especialmente útil para agentes que consultam múltiplas fontes de dados ou encadeiam várias ferramentas num único pedido.

Criar um pedido de antecedentes

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 estado 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 de fundo com MCP

Para segurança, a API Supervisor requer aprovação explícita do utilizador antes de executar qualquer chamada de ferramenta MCP em modo de segundo plano. Quando o loop do agente seleciona uma ferramenta MCP, a resposta termina com um mcp_approval_request. Pode rever o nome da ferramenta, o rótulo do servidor e os argumentos que o modelo pretende aprovar:

{
  "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 função e continuar o ciclo do agente, devolva um mcp_approval_response 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 em modo de fundo são mantidas na base de dados durante um máximo de 30 dias.

Ferramentas suportadas

Define ferramentas no tools array do seu pedido. Cada entrada especifica um type e um objeto de configuração com a mesma chave. Por exemplo, uma ferramenta Genie Space tem "type": "genie_space" e um "genie_space": {...} objeto. A API suporta os seguintes tipos de ferramentas:

Tipo de ferramenta Description Scope
genie_space Consulta um Genie Space para responder a perguntas sobre os seus dados. Parâmetros: id, description. genie
uc_function Chama uma função do Unity Catalog como uma ferramenta agente. Parâmetros: name, description. unity-catalog
uc_connection Liga-se a um servidor MCP externo através de uma ligação Unity Catalog. Parâmetros: name, description. Para ligações de sistema geridas por Azure Databricks, defina name para um conector system_ai_agent_* (ver Passo 3 (Opcional): Ligue a serviços de terceiros com ligações geridas pelo sistema). Nota: servidores MCP personalizados nas Apps ainda não são suportados. unity-catalog
app Chama um endpoint do 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 suportados

Cada pedido à API do Supervisor aceita os seguintes parâmetros.

  • input: mensagens da conversa a enviar.
  • tools: definições de ferramentas hospedadas (genie_space, uc_function, knowledge_assistant, app, uc_connection).
  • instructions: um prompt do sistema para orientar o comportamento do supervisor.
  • stream: definir como true transmitir respostas.
  • background: define para true executar o pedido de forma assíncrona. Devolve um ID de resposta que consultas com responses.retrieve(). Ver modo de fundo.
  • trace_destination: objeto opcional com catalog_name, schema_name, e table_prefix campos. Quando definido, a API Supervisor escreve um traço do ciclo completo do agente nas tabelas do Unity Catalog especificadas. Passa via extra_body no cliente do Python.

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

Limitações

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

  • Tempo de execução em modo de fundo: Pedidos em modo de fundo têm um tempo máximo de execução de 30 minutos.
  • Chamada de funções do lado do cliente: Apenas ferramentas alojadas são suportadas. Não podes passar function definições de ferramentas para o cliente executar, nem misturar ferramentas alojadas com ferramentas do lado function do cliente no mesmo pedido.
  • Transmitir em modo de fundo: stream e background não podem estar true ambos no mesmo pedido.
  • Execução duradoura: A recuperação automática de falhas ou interrupções com garantias de execução exatamente uma vez para o ciclo do agente não é suportada.
  • Azure Databricks Apps OBO não suportado: A autorização em nome do utilizador não é suportada para a API do Supervisor. Para usar a API Supervisor nas Azure Databricks Apps, use system authorization e conceda permissões para as suas ferramentas.

Passos seguintes

  • Last updated on