API Supervisor (Beta)

Importante

Questa funzionalità è in versione beta. Gli amministratori dell'account possono controllare l'accesso a questa funzionalità dalla pagina Anteprime . Vedere Gestire le anteprime di Azure Databricks.

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

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

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 e SharePoint. 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:

Connettore Descrizione
system_ai_agent_google_drive Cercare e leggere i file da Google Drive.
system_ai_agent_github_mcp Accedere ai repository GitHub, problemi aperti e pull request.
system_ai_agent_atlassian_mcp Cercare e gestire le risorse atlassian (Jira, Confluence).
system_ai_agent_sharepoint Cercare e leggere i file da SharePoint.

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: 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
}

Note

Le risposte in modalità in background vengono mantenute nel database per un massimo di 30 giorni.

Strumenti supportati

Gli strumenti vengono definiti nella tools matrice della richiesta. Ogni voce specifica un type oggetto di configurazione con la stessa chiave. Ad esempio, uno strumento Genie Space ha un oggetto "type": "genie_space" e un oggetto "genie_space": {...}. L'API supporta i tipi di strumenti seguenti:

Tipo di strumento Descrizione Scope
genie_space Esegue una query su uno spazio Genie per rispondere alle domande sui dati. Parametri: id, description. genie
uc_function Chiama una funzione del catalogo Unity come strumento agente. Parametri: name, description. unity-catalog
uc_connection Si connette a un server MCP esterno tramite una connessione al catalogo Unity. Parametri: name, description. Per le connessioni di sistema gestite da Azure Databricks, impostare name su un connettore system_ai_agent_* (vedere Passaggio 3 (facoltativo): Collegarsi a servizi di terze parti con connessioni gestite dal sistema). Nota: i server MCP personalizzati nelle app non sono ancora supportati. unity-catalog
app Chiama un endpoint dell'app Azure Databricks. Parametri: name, description. apps
knowledge_assistant Chiama un endpoint di Knowledge Assistant . Parametri: knowledge_assistant_id, description. model-serving

Parametri supportati

Ogni richiesta all'API supervisore accetta i parametri seguenti.

  • input: i messaggi di conversazione da inviare.
  • tools: definizioni degli strumenti ospitati (genie_space, uc_function, knowledge_assistantapp, , uc_connection).
  • 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.

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.
  • Chiamata di funzioni lato client: sono supportati solo gli strumenti ospitati. Non è possibile passare function le definizioni degli strumenti affinché il client le esegua, e nella stessa richiesta non è possibile combinare gli strumenti ospitati con gli strumenti lato function client.
  • 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.
  • Azure Databricks L'OBO delle app non è supportato: l'autorizzazione per conto dell'utente non è supportata per l'API di supervisione. Per utilizzare l'API Supervisor nelle applicazioni Azure Databricks, utilizzare l'autorizzazione del sistema e concedere le autorizzazioni degli strumenti.

Passaggi successivi

  • Last updated on