API de Supervisor (Beta)

Importante

Esta característica se encuentra en su versión beta. Los administradores de cuentas pueden controlar el acceso a esta característica desde la página Vistas previas . Consulte Administrar versiones preliminares de Azure Databricks.

La API Supervisor facilita la creación de agentes personalizados en Azure Databricks con compatibilidad con el modo background para tareas de larga duración. El modelo, las herramientas y las instrucciones se definen en una solicitud a un OpenResponses punto de conexión compatible con (POST /mlflow/v1/responses) y Azure Databricks ejecuta el bucle del agente para usted: llamar repetidamente al modelo, seleccionar y ejecutar herramientas y sintetizar una respuesta final.

Hay tres enfoques para crear un agente de llamada a herramientas personalizado en Azure Databricks:

  • Agent Bricks Supervisor Agent (recomendado): totalmente declarativo con optimización de retroalimentación humana para obtener la más alta calidad.
  • API de supervisor: cree un agente personalizado mediante programación: elija modelos en tiempo de ejecución, controle qué herramientas usar por solicitud o iteración durante el desarrollo. También es la elección correcta cuando necesita tener control sobre la selección del modelo mientras delega la gestión de los ciclos del agente a Azure Databricks.
  • API unificadas o nativas de AI Gateway: escriba su propio bucle de agente. Azure Databricks proporciona solo la capa de inferencia de LLM. Use las API unificadas siempre que sea posible para habilitar los modelos de conmutación o las API nativas específicas del proveedor (/openai, /anthropic, /gemini) al migrar código existente a Azure Databricks o mediante características específicas del proveedor.

Requisitos

Paso 1: Creación de una llamada LLM de un solo turno

Comience con una llamada básica sin herramientas. El DatabricksOpenAI cliente configura automáticamente la dirección URL base y la autenticación para el área de trabajo:

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)

Paso 2: Agregar herramientas hospedadas para ejecutar el bucle del agente

Al incluir herramientas en la solicitud, Azure Databricks administra un bucle de varios turnos en su nombre: el modelo decide qué herramientas llamar, Azure Databricks las ejecuta, devuelve los resultados al modelo y se repite hasta que el modelo genera una respuesta 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)

Paso 3: Habilitar el seguimiento

Coloque un trace_destination en el cuerpo de la solicitud para enviar trazas del ciclo del agente a las tablas de Unity Catalog. Cada solicitud genera un seguimiento que captura la secuencia completa de llamadas de modelo y ejecuciones de herramientas. Si no establece trace_destination, no se escribe ningún registro. Para obtener más información sobre la configuración, consulte Store MLflow traces in Unity Catalog (Almacenar seguimientos de MLflow en el catálogo de Unity).

Con el cliente databricks-openai Python, páselo a través de 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 devolver el rastro directamente también en la respuesta de la API, pase "databricks_options": {"return_trace": True}extra_body.

También puede usar el seguimiento distribuido de MLflow para combinar seguimientos del código de la aplicación y el bucle del agente de la API de Supervisor en un único seguimiento de un extremo a otro. Propagación de encabezados de contexto de seguimiento mediante el extra_headers campo :

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 fondo

El modo en segundo plano permite ejecutar flujos de trabajo de agente de larga duración que implican varias llamadas de herramientas y razonamiento complejo sin esperar a que finalicen de forma sincrónica. Envíe la solicitud con background=True, reciba un identificador de respuesta inmediatamente y sondee el resultado cuando esté listo. Esto es especialmente útil para los agentes que consultan varios orígenes de datos o encadenan varias herramientas juntas en una sola solicitud.

Crea una solicitud en 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"

Sondear el resultado

Use responses.retrieve() para comprobar el estado hasta que alcance un 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 fondo con MCP

Por razones de seguridad, la Supervisor API requiere la aprobación explícita del usuario antes de ejecutar cualquier llamada de herramienta MCP en modo de segundo plano. Cuando el bucle del agente selecciona una herramienta MCP, la respuesta se completa con .mcp_approval_request Puede revisar el nombre de la herramienta, la etiqueta del servidor y los argumentos que el modelo pretende pasar:

{
  "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 aprobar la llamada a la herramienta y continuar el bucle del agente, devuelva un mcp_approval_response en el campo input con el historial completo de la conversación:

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

Note

Las respuestas en modo en segundo plano se conservan en la base de datos durante un máximo de 30 días.

Herramientas compatibles

Las herramientas se definen en la matriz de la tools solicitud. Cada entrada especifica un type objeto de configuración y con la misma clave. Por ejemplo, una herramienta espacial de Genie tiene un "type": "genie_space" y un "genie_space": {...} objeto. La API admite los siguientes tipos de herramientas:

Tipo de herramienta Descripción Ámbito
genie_space Consulta un espacio de Genie para responder a preguntas sobre los datos. Parámetros: id, description. genie
uc_function Llama a una función de Unity Catalog como herramienta del agente. Parámetros: name, description. unity-catalog
uc_connection Se conecta a través de una conexión del Catálogo de Unity a un servidor MCP externo. Parámetros: name, description. Nota: Aún no se admiten servidores MCP personalizados en aplicaciones. unity-catalog
app Llama a un endpoint de una aplicación de Azure Databricks. Parámetros: name, description. apps
knowledge_assistant Llama a un Knowledge Assistant endpoint. Parámetros: knowledge_assistant_id, description. model-serving

Parámetros admitidos

Cada solicitud a supervisor API acepta los parámetros siguientes.

  • input: los mensajes de conversación que se van a enviar.
  • tools: definiciones de herramientas hospedadas (genie_space, uc_function, knowledge_assistant, app, uc_connection).
  • instructions: un mensaje del sistema para guiar el comportamiento del supervisor.
  • stream: se establece en true para transmitir respuestas.
  • background: se establece en true para ejecutar la solicitud de forma asincrónica. Devuelve un identificador de respuesta que consulta con responses.retrieve(). Consulte Modo de fondo.
  • trace_destination: objeto opcional con los campos catalog_name, schema_name y table_prefix. Cuando se establece, la Supervisor API escribe una traza del ciclo completo del agente en las tablas especificadas del Catálogo de Unity. Pase por extra_body en el cliente de Python.

La API no admite parámetros de inferencia como temperature. El servidor administra estos datos internamente.

Limitaciones

La API supervisor tiene las siguientes limitaciones:

  • Tiempo de ejecución del modo en segundo plano: las solicitudes de modo en segundo plano tienen un tiempo de ejecución máximo de 30 minutos.
  • Llamada a funciones del lado cliente: solo se admiten las herramientas hospedadas. No puedes pasar function definiciones de herramientas para que el cliente las ejecute y no se pueden mezclar herramientas alojadas con herramientas de cliente function en la misma solicitud.
  • Streaming en modo de fondo: stream y background no pueden estar true en la misma solicitud.
  • Ejecución duradera: no se admite la recuperación automática de errores o interrupciones con garantías de ejecución exactamente una vez para el bucle del agente.
  • Azure Databricks Apps OBO no se admite: no se admite la autorización en nombre del usuario para la API supervisor. Para usar la API de Supervisor en Azure Databricks Apps, use autorización del sistema y conceda permisos para las herramientas.

Pasos siguientes

  • Last updated on