API Supervisor (Beta)

L'API Supervisor semplifica la creazione di agenti personalizzati in Azure Databricks con supporto per la modalità in background per le attività a lungo termine. È possibile definire il modello, gli strumenti e le istruzioni in una richiesta a un endpoint OpenResponses-compatible endpoint (POST ai-gateway/mlflow/v1/responses) e Azure Databricks esegue il ciclo dell'agente per l'utente: chiamare ripetutamente il modello, selezionare ed eseguire strumenti e sintetizzare una risposta finale.

Esistono tre approcci per creare un agente personalizzato che chiama gli strumenti in Azure Databricks:

• Agent Brick Supervisor Agent (scelta consigliata): completamente dichiarativo con l'ottimizzazione del feedback umano per ottenere la massima qualità.
• API supervisore: creare un agente personalizzato a livello di codice: scegliere modelli in fase di esecuzione, controllare quali strumenti usare per ogni richiesta o eseguire l'iterazione durante lo sviluppo. Anche la scelta giusta quando è necessario controllare la selezione del modello durante lo scarico della gestione del ciclo degli agenti su Azure Databricks.
• API unificate o native del gateway di intelligenza artificiale: scrivere un ciclo di agenti personalizzato. Azure Databricks fornisce solo il livello di inferenza LLM. Usare api unificate, se possibile, per abilitare il cambio di modelli o API native specifiche del provider (/openai, /anthropic, /gemini) quando si esegue la conversione di codice esistente in Azure Databricks o usando funzionalità specifiche del provider.

Requisiti

• Il Gateway di intelligenza artificiale Unity per agenti e LLM è stato abilitato per il tuo account. Vedere Gestire le anteprime di Azure Databricks.
  • Poiché l'API Supervisor viene eseguita tramite Unity AI Gateway, si applicano funzionalità del gateway di intelligenza artificiale, ad esempio tabelle di inferenza, limiti di frequenza e fallback. Il rilevamento dell'utilizzo non è supportato in questa versione beta.
• Archiviare le tracce OpenTelemetry nel catalogo unity abilitato per l'account. Vedere Gestire le anteprime di Azure Databricks.
  • Archivia le tracce dal ciclo dell'agente dell'API Supervisor nelle tabelle del catalogo Unity.
• Un'area di lavoro Azure Databricks in una regione supportata.
• Catalogo Unity abilitato per l'area di lavoro. Vedere Abilitare un'area di lavoro per il Catalogo Unity.
• Gli strumenti passati (Genie Spaces, funzioni di Unity Catalog, server MCP, assistenti della conoscenza, le app) devono essere già configurati e accessibili.
• Pacchetto databricks-openai installato: pip install databricks-openai

Passaggio 1: Creare una chiamata LLM a turno singolo

Iniziare con una chiamata di base senza strumenti. Il DatabricksOpenAI client configura automaticamente l'URL di base e l'autenticazione per l'area di lavoro:

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)

Passaggio 2: Aggiungere strumenti ospitati per eseguire il ciclo operativo dell'agente

Quando si includono strumenti nella richiesta, Azure Databricks gestisce un ciclo a più turni per conto dell'utente: il modello decide quali strumenti chiamare, Azure Databricks li esegue, li invia al modello e si ripete finché il modello non produce una risposta finale.

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)

Passaggio 3 (facoltativo): Connettersi a servizi di terze parti con connessioni gestite dal sistema

Azure Databricks fornisce connessioni gestite dal sistema per i servizi di terze parti più diffusi, ad esempio Google Drive, GitHub, Atlassian, SharePoint e Glean. Queste connessioni sono un'alternativa rapida alla configurazione del proprio server MCP esterno . È comunque possibile usare il uc_connection tipo di strumento per connettersi a qualsiasi server MCP esterno configurato manualmente.

Le connessioni gestite dal sistema richiedono che i connettori di terze parti per Agents Beta siano abilitati nell'area di lavoro. Vedere Gestire le anteprime di Azure Databricks.

Sono supportati i connettori seguenti:

Passare un connettore nell'array tools usando uno strumento di tipo uc_connection con il campo name impostato sul nome del connettore:

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

Autenticazione da utente a computer (U2M)

Ogni utente esegue l'autenticazione singolarmente. I token OAuth non vengono condivisi tra gli utenti. Nella prima richiesta che usa un connettore l'utente non ha eseguito l'autenticazione, la risposta viene completata con status: "failed" e viene visualizzato un oauth errore contenente un URL di accesso:

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

Aprire l'URL in un browser, completare il flusso OAuth, quindi eseguire nuovamente la stessa richiesta.

Passaggio 4 (facoltativo): Aggiungi uno strumento funzione sul lato client

Usa gli strumenti function quando vuoi che l'applicazione esegua una logica personalizzata insieme agli strumenti ospitati in Azure Databricks. Dichiarare uno strumento per le funzioni con type: "function", un nameoggetto facoltativo descriptione un oggetto Schema parameters 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,
      },
    }
  ],
)

L'API Supervisor non archivia lo stato della conversazione tra le richieste, quindi una chiamata di funzione lato client richiede due turni:

1. Turno 1. Il modello restituisce un function_call elemento (ad esempio, "chiamare get_weather con location=Paris") anziché una risposta finale.
2. Il codice esegue la funzione in locale e produce un risultato.
3. Turno 2. Richiama responses.create() di nuovo, passando l'input originale più il function_call del modello più un nuovo function_call_output con il tuo risultato. Il modello usa il risultato per produrre la risposta finale.

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)

Per altri scenari (streaming, hosted e strumenti client, approvazione MCP, risoluzione dei problemi), consulta la skill di chiamata di funzioni lato client dell'API Supervisor.

Passaggio 5: Abilitare la traccia

Passare un oggetto trace_destination nel corpo della richiesta per inviare tracce dal ciclo dell'agente alle tabelle del catalogo Unity. Ogni richiesta genera una traccia che acquisisce la sequenza completa di chiamate del modello ed esecuzioni degli strumenti. Se non si imposta trace_destination, non vengono scritte tracce. Per informazioni dettagliate sulla configurazione, vedere Archiviare tracce OpenTelemetry nel Unity Catalog.

Usando il client databricks-openai Python, passalo tramite 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>"
    }
  }
)

Per restituire anche la traccia direttamente nella risposta dell'API, passare "databricks_options": {"return_trace": True}extra_body.

È anche possibile usare la tracciabilità distribuita di MLflow per combinare le tracce dal codice dell'applicazione e il ciclo dell'agente API del Supervisor in una singola traccia end-to-end. Propagare le intestazioni del contesto di traccia usando il 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,
  )

Modalità sfondo

La modalità in background consente di eseguire flussi di lavoro dell'agente a esecuzione prolungata che coinvolgono più chiamate di strumenti e ragionamenti complessi senza attendere che vengano completati in modo sincrono. Invia la richiesta con background=True, ricevi immediatamente un ID di risposta ed esegui il polling del risultato quando è pronto. Ciò è particolarmente utile per gli agenti che eseguono query su più origini dati o concatenano più strumenti in una singola richiesta.

Creare una richiesta in background

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"

Eseguire il polling del risultato

Usare responses.retrieve() per controllare lo stato finché non raggiunge lo stato del terminale:

from time import sleep

while response.status in {"queued", "in_progress"}:
  sleep(2)
  response = client.responses.retrieve(response.id)

print(response.output_text)

Modalità in background con MCP

Per la sicurezza, l'API supervisore richiede l'approvazione esplicita dell'utente prima di eseguire qualsiasi chiamata allo strumento MCP in modalità in background. Quando il ciclo dell'agente seleziona uno strumento MCP, la risposta viene completata utilizzando un mcp_approval_request. È possibile esaminare il nome dello strumento, l'etichetta del server e gli argomenti che il modello intende passare:

{
  "type": "mcp_approval_request",
  "id": "<tool-call-id>",
  "arguments": "{\"query\": \"what is Databricks\", \"count\": 5}",
  "name": "you-search",
  "server_label": "<server-label>",
  "status": "completed"
}

Per approvare la chiamata allo strumento e continuare il ciclo dell'agente, passare un mcp_approval_response indietro nel campo input con la cronologia completa della conversazione.

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

Strumenti supportati

Gli strumenti vengono definiti nella tools matrice della richiesta. Ogni oggetto strumento condivide tre campi di primo livello:

• type (stringa, obbligatorio): Il discriminatore che seleziona il tipo di strumento.
• name (stringa, facoltativa): nome visualizzato nel modello.
• description (stringa, facoltativa): hint per il modello su quando chiamare questo strumento.

Inoltre, ogni oggetto strumento include un oggetto di configurazione annidato la cui chiave corrisponde al type valore. La tabella seguente illustra la configurazione annidata per ogni tipo di strumento supportato.

Per serving_endpointsono supportati solo gli endpoint ResponseAgent, ChatCompletions e ChatAgent.

Per app, sono supportate solo le app MCP (con il mcp- prefisso) e le app ResponseAgent personalizzate (con il agent- prefisso).

Per uc_connection, usare il nome di connessione creato per un server MCP esterno o un system_ai_agent_* connettore gestito dal sistema (vedere Passaggio 3 (facoltativo): Connettersi a servizi di terze parti con connessioni gestite dal sistema. I server MCP personalizzati nelle app non sono ancora supportati.

Esecuzione del codice

Quando una richiesta richiede il calcolo, il supervisore esegue il codice generato dal modello in una sessione di calcolo serverless in modalità sandbox per analizzare i dati, trasformare i file o eseguire calcoli. Supporta i comandi Python (impostazione predefinita), SQL e shell. Il supervisore scrive ed esegue il codice stesso quando necessario, in modo da non abilitare, configurare o fornire il codice.

L'esecuzione del codice viene eseguita in una sandbox bloccata con:

• Nessun accesso a Internet. Blocca tutto il traffico di rete in uscita, indipendentemente dalla policy di rete dell'area di lavoro, quindi il codice eseguito nella sandbox non può raggiungere endpoint esterni.
• Solo accesso limitato ad Azure Databricks. Non ha accesso ai dati propri. Può leggere le tabelle del catalogo Unity dichiarate con lo table strumento nella stessa richiesta.

Parametri supportati

Ogni richiesta all'API supervisore accetta i parametri seguenti.

• model: uno dei modelli supportati seguenti. Modificare questo campo per cambiare provider senza modificare il resto del codice.
  • 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: i messaggi di conversazione da inviare.
• tools: definizioni degli strumenti ospitati (genie_space, dashboard, uc_function, table, knowledge_assistant, serving_endpoint, web_search, vector_search_index, volume, app, uc_connection) e strumenti funzione lato client (function). Vedi Passaggio 4 (Facoltativo): Aggiungere uno strumento di funzione lato client.
• instructions: una richiesta di sistema per guidare il comportamento del supervisore.
• stream: impostare su true per trasmettere le risposte.
• background: impostato su true per eseguire la richiesta in modo asincrono. Restituisce un ID di risposta che viene interrogato con responses.retrieve(). Vedi Modalità sfondo.
• trace_destination: oggetto facoltativo con catalog_namecampi , schema_namee table_prefix . Se impostata, l'API Supervisor scrive una traccia del ciclo completo dell'agente nelle tabelle del catalogo Unity specificate. Passare tramite extra_body nel client Python.

L'API non supporta parametri di inferenza, temperaturead esempio . Il server gestisce questi elementi internamente.

Authorization

L'API Supervisor esegue il ciclo dell'agente con le credenziali del chiamante, in modo che gli strumenti richiamati rispettino le autorizzazioni del catalogo Unity del chiamante. Quando chiami direttamente l'API, il DatabricksOpenAI client si autentica come te.

Quando chiami l'API Supervisor da un'app di Azure Databricks, puoi eseguire gli strumenti come entità servizio dell'app (autorizzazione dell'app) oppure come utente richiedente (autorizzazione utente). Per autorizzare l'app, concedere autorizzazioni all'entità servizio dell'app per ogni strumento. Per l'autorizzazione utente, inoltrare il token dell'utente al DatabricksOpenAI client e aggiungere gli ambiti di autorizzazione utente necessari. Vedere Eseguire gli strumenti come utente richiedente.

Limitazioni

L'API supervisore presenta le limitazioni seguenti:

• Runtime in modalità in background: le richieste in modalità in background hanno un tempo massimo di esecuzione di 30 minuti.
• Streaming in modalità in background: stream e background non possono trovarsi true nella stessa richiesta.
• Esecuzione durevole: il ripristino automatico da errori o interruzioni con garanzie di esecuzione esattamente una volta per il ciclo dell'agente non è supportato.
• Idoneità dello spazio di lavoro per la ricerca web: lo strumento web_search non è disponibile negli spazi di lavoro con la conformità HIPAA/BAA abilitata. È disponibile solo nelle aree con un modello nativo con supporto per la ricerca Web o l'elaborazione tra aree geografiche abilitata. Le richieste che includono web_search da aree di lavoro non idonee vengono rifiutate.

Risorse aggiuntive

• Creare un agente personalizzato usando l'API Supervisor (Beta)
• Usare l'agente supervisore per creare un sistema multi-agente coordinato
• Eseguire query sugli endpoint del Gateway di Intelligenza Artificiale Unity
• Gateway di intelligenza artificiale Unity per agenti e llms