Supervisor-API (bèta)

De Supervisor-API vereenvoudigt het bouwen van aangepaste agents op Azure Databricks met ondersteuning voor background-modus voor langlopende taken. U definieert het model, de hulpprogramma's en instructies in één aanvraag voor een OpenResponses-compatibel eindpunt (POST ai-gateway/mlflow/v1/responses) en Azure Databricks voert de agentlus voor u uit: herhaaldelijk het model aanroepen, hulpprogramma's selecteren en uitvoeren en een eindantwoord synthetiseren.

Er zijn drie benaderingen voor het bouwen van een aangepaste agent voor het aanroepen van hulpprogramma's op Azure Databricks:

• Agent Bricks Supervisor Agent (aanbevolen): Volledig declaratief met optimalisatie van menselijke feedback voor de hoogste kwaliteit.
• Supervisor-API: programmeer programmatisch een aangepaste agent: kies modellen tijdens runtime, bepaal welke hulpprogramma's per aanvraag moeten worden gebruikt of itereer tijdens de ontwikkeling. Ook de juiste keuze wanneer u controle nodig hebt over de modelkeuze, terwijl u het beheer van de agentloop naar Azure Databricks overdraagt.
• Geïntegreerde of systeemeigen API's van AI Gateway: schrijf uw eigen agentlus. Azure Databricks biedt alleen de LLM-deductielaag. Gebruik waar mogelijk geïntegreerde API's om schakelmodellen of providerspecifieke systeemeigen API's (/openai, /anthropic, /gemini) in te schakelen bij het overzetten van bestaande code naar Azure Databricks of het gebruik van providerspecifieke functies.

Requirements

• AI-governance met Unity AI Gateway ingeschakeld voor uw account. Zie Azure Databricks previews beheren.
  • Omdat de Supervisor-API wordt uitgevoerd via Unity AI Gateway, zijn AI Gateway-functies zoals deductietabellen, frequentielimieten en terugvalbewerkingen van toepassing. Het bijhouden van gebruik wordt niet ondersteund in deze bètaversie.
• OpenTelemetry-traceringen zijn opgeslagen in Unity Catalog dat is ingeschakeld voor uw account. Zie Azure Databricks previews beheren.
  • Slaat traceringen op uit de Supervisor API-agentlus in Unity Catalog-tabellen.
• Een Azure Databricks werkruimte in een ondersteunde regio.
• Unity Catalog ingeschakeld voor uw werkruimte. Zie Een werkruimte inschakelen voor Unity Catalog.
• De hulpprogramma's die u doorgeeft (Genie Spaces, Unity Catalog-functies, MCP-servers, kennisassistenten, apps) moeten al zijn geconfigureerd en toegankelijk zijn.
• Het databricks-openai pakket is geïnstalleerd: pip install databricks-openai

Stap 1: Een LLM-aanroep met één beurt maken

Begin met een eenvoudige aanroep zonder hulpprogramma's. De DatabricksOpenAI client configureert automatisch de basis-URL en verificatie voor uw werkruimte:

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)

Stap 2: Gehoste hulpprogramma's toevoegen om de agentlus uit te voeren

Wanneer u hulpprogramma's in de aanvraag opneemt, beheert Azure Databricks namens u een lus met meerdere functies: het model bepaalt welke hulpprogramma's moeten worden aangeroepen, Azure Databricks deze uitvoert, voert de resultaten terug naar het model en herhaalt deze totdat het model een definitief antwoord produceert.

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)

Stap 3 (optioneel): Verbinding maken met services van derden met door het systeem beheerde verbindingen

Azure Databricks biedt door het systeem beheerde verbindingen voor populaire services van derden, zoals Google Drive, GitHub, Atlassian, SharePoint en Glean. Deze verbindingen zijn een snel alternatief voor het instellen van uw eigen externe MCP-server . U kunt nog steeds het uc_connection hulpprogrammatype gebruiken om verbinding te maken met elke externe MCP-server die u zelf hebt geconfigureerd.

Voor door het systeem beheerde verbindingen moet de Third Party Connectors for Agents Beta zijn ingeschakeld in uw werkruimte. Zie Azure Databricks previews beheren.

De volgende connectors worden ondersteund:

Geef een verbindingslijn door in de tools matrix met behulp van het uc_connection hulpprogrammatype, waarbij het name veld is ingesteld op de naam van de connector:

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

Gebruikers-naar-machine-verificatie (U2M)

Elke gebruiker wordt afzonderlijk geverifieerd. OAuth-tokens worden niet gedeeld tussen gebruikers. Bij de eerste aanvraag die gebruikmaakt van een connector die de gebruiker niet heeft geverifieerd, wordt het antwoord voltooid met status: "failed" en een oauth fout met een aanmeldings-URL:

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

Open de URL in een browser, voltooi de OAuth-stroom en voer dezelfde aanvraag opnieuw uit.

Stap 4 (optioneel): Een functiehulpprogramma aan de clientzijde toevoegen

Gebruik function-hulpprogramma's wanneer u wilt dat uw toepassing aangepaste logica uitvoert naast Azure Databricks gehoste hulpprogramma's. Declareer een functiehulpprogramma met type: "function", een name, een optionele descriptionen een JSON-schemaobject parameters :

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

De Supervisor-API slaat de gespreksstatus tussen aanvragen niet op, dus een functieaanroep aan de clientzijde neemt twee beurten in beslag:

1. Draai 1. Het model retourneert een function_call item (bijvoorbeeld 'aanroepen get_weather met location=Paris') in plaats van een definitief antwoord.
2. De code voert de functie lokaal uit en produceert een resultaat.
3. Draai 2. Roep responses.create() opnieuw aan en geef de oorspronkelijke invoer, de function_call van het model en een nieuwe function_call_output met je resultaat mee. Het model gebruikt het resultaat om het uiteindelijke antwoord te produceren.

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)

Zie de vaardigheid voor het aanroepen van functies aan de clientzijde van de Supervisor-API voor meer patronen (streaming, gehost plus clienthulpprogramma's, MCP-goedkeuring, probleemoplossing).

Stap 5: Tracering inschakelen

Geef een trace_destination door in de aanvraagbody om de traceringen van de agentlus naar Unity Catalog-tabellen te verzenden. Elke aanvraag genereert een tracering die de volledige reeks modeloproepen en uitvoeringen van hulpprogramma's vastlegt. Als u trace_destination niet instelt, worden er geen traces geschreven. Zie Store OpenTelemetry-traceringen in Unity Catalog voor meer informatie over de installatie.

Gebruik de databricks-openai Python-client en geef deze door 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>"
    }
  }
)

Als u de trace ook rechtstreeks in het API-antwoord wilt retourneren, geeft u "databricks_options": {"return_trace": True} door in extra_body.

U kunt ook gedistribueerde tracering van MLflow gebruiken om traceringen uit uw toepassingscode en de Supervisor API-agentlus te combineren tot één end-to-end-trace. Traceringscontextheader doorgeven met behulp van het extra_headers veld

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

Achtergrondmodus

Met de achtergrondmodus kunt u langlopende agentwerkstromen uitvoeren die betrekking hebben op meerdere hulpprogrammaaanroepen en complexe redeneringen zonder te wachten tot ze synchroon zijn voltooid. Dien uw aanvraag in met background=True, ontvang onmiddellijk een antwoord-id en peil het resultaat wanneer deze gereed is. Dit is met name handig voor agents die meerdere gegevensbronnen opvragen of verschillende hulpprogramma's samenvoegen in één aanvraag.

Een achtergrondaanvraag maken

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"

Stemming voor het resultaat

Gebruik responses.retrieve() dit om de status te controleren totdat deze de terminalstatus bereikt:

from time import sleep

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

print(response.output_text)

Achtergrondmodus met MCP

Voor beveiliging vereist de Supervisor-API expliciete goedkeuring van gebruikers voordat een MCP-hulpprogrammaaanroep wordt uitgevoerd in de achtergrondmodus. Wanneer de agentlus een MCP-hulpprogramma selecteert, wordt het antwoord voltooid met een mcp_approval_request. U kunt de naam van het hulpprogramma, het serverlabel en de argumenten controleren die het model wil doorgeven:

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

Als u de aanroep van het hulpprogramma wilt goedkeuren en de agentlus wilt voortzetten, geeft u een mcp_approval_response terug in het input veld door met de volledige gespreksgeschiedenis:

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

Ondersteunde hulpprogramma's

U definieert hulpprogramma's in de tools matrix van uw aanvraag. Elk hulpprogrammaobject deelt drie velden op het hoogste niveau:

• type (tekenreeks, vereist): de discriminator die het type hulpprogramma selecteert.
• name (string, optioneel): Weergavenaam die aan het model wordt getoond.
• description (tekenreeks, optioneel): Hint naar het model over wanneer dit hulpprogramma moet worden aangeroepen.

Daarnaast heeft elk hulpprogrammaobject een geneste configuratieobject waarvan de sleutel overeenkomt met de type waarde. De onderstaande tabel documenteert de geneste configuratie-instellingen voor elk ondersteund tooltype.

Alleen serving_endpointResponseAgent-, ChatCompletions- en ChatAgent-eindpunten worden ondersteund.

Voor appworden alleen MCP-apps (met het mcp- voorvoegsel) en aangepaste ResponseAgent-apps (met het agent- voorvoegsel) ondersteund.

Gebruik uc_connectionde verbindingsnaam die u hebt gemaakt voor een externe MCP-server of een system_ai_agent_* door het systeem beheerde connector (zie stap 3 (optioneel): Verbinding maken met services van derden met door het systeem beheerde verbindingen. Aangepaste MCP-servers in apps worden niet ondersteund.

Code-uitvoering

Wanneer een aanvraag rekenkracht nodig heeft, voert de Supervisor model gegenereerde code uit in een serverloze rekensessie in de sandbox om gegevens te analyseren, bestanden te transformeren of berekeningen uit te voeren. Het ondersteunt Python (standaard), SQL- en shell-opdrachten. De Supervisor schrijft en voert de code zelf uit wanneer dat nodig is, zodat u de code niet inschakelt, configureert of opgeeft.

Uitvoering van code wordt uitgevoerd in een vergrendelde sandbox met:

• Geen internettoegang. Hiermee worden alle uitgaande netwerkuitgangen geblokkeerd, ongeacht het netwerkbeleid van uw werkruimte, zodat code die wordt uitgevoerd in de sandbox geen externe eindpunten kan bereiken.
• Alleen beperkte toegang tot Azure Databricks. Het heeft geen eigen gegevenstoegang. Het kan de Unity Catalog-tabellen lezen die u declareert met het table hulpprogramma in dezelfde aanvraag.

Ondersteunde parameters

Elke aanvraag voor de Supervisor-API accepteert de volgende parameters.

• model: een van de volgende ondersteunde modellen. Wijzig dit veld om van provider te wisselen zonder de rest van uw code te wijzigen.
  • 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: de gespreksberichten die moeten worden verzonden.
• tools: definities van gehoste hulpprogramma's (genie_space, dashboard, uc_function, table, knowledge_assistant, serving_endpoint, web_search, vector_search_index, volume, app, uc_connection) en functiehulpprogramma's aan de clientzijde (function). Zie stap 4 (optioneel): Voeg een functiehulpprogramma aan de clientzijde toe.
• instructions: een systeemprompt om het gedrag van de supervisor te begeleiden.
• stream: ingesteld op true het streamen van antwoorden.
• background: ingesteld op true om de aanvraag asynchroon uit te voeren. Retourneert een antwoord-id waarmee u pollt responses.retrieve(). Zie de achtergrondmodus.
• trace_destination: optioneel object met catalog_name, schema_nameen table_prefix velden. Wanneer deze is ingesteld, schrijft de Supervisor-API een tracering van de volledige agentlus naar de opgegeven Unity Catalog-tabellen. Passeer via extra_body in de Python-client.

De API biedt geen ondersteuning voor deductieparameters zoals temperature. De server beheert deze intern.

Authorization

De Supervisor-API voert de agentlus uit met de referenties van de aanroeper, dus de hulpprogramma's die worden aangeroepen, respecteren de Unity Catalog-machtigingen van de aanroeper. Wanneer u de API rechtstreeks aanroept, authenticeert de DatabricksOpenAI client zich namens u.

Wanneer u de Supervisor-API aanroept vanuit een Azure Databricks-app, kunt u hulpprogramma's uitvoeren als de service-principal van de app (app-autorisatie) of als de aanvragende gebruiker (gebruikersautorisatie). Voor app-autorisatie verleent u de service-principalmachtigingen van de app voor elk hulpprogramma. Voor gebruikersautorisatie stuurt u het token van de gebruiker door naar de DatabricksOpenAI-client en voegt u de vereiste gebruikersautorisatie-scopes toe. Zie Hulpprogramma's uitvoeren als de aanvragende gebruiker.

Limitations

De Supervisor-API heeft de volgende beperkingen:

• Runtime achtergrondmodus: aanvragen voor achtergrondmodus hebben een maximale uitvoeringstijd van 30 minuten.
• Streamen in de achtergrondmodus: stream en background kunnen niet beide true in hetzelfde verzoek zijn.
• Duurzame uitvoering: Automatisch herstel na fouten of onderbrekingen met exactly-once uitvoeringsgaranties voor de agentlus wordt niet ondersteund.
• Geschiktheid voor zoeken op internet: de web_search tool is niet beschikbaar in werkruimten waarin HIPAA/BAA-naleving is ingeschakeld. Het is alleen beschikbaar in regio's met een systeemeigen model dat geschikt is voor zoeken op internet of verwerking van meerdere geografien is ingeschakeld. Aanvragen die web_search bevatten van niet in aanmerking komende werkruimtes worden afgewezen.

Aanvullende informatiebronnen

• Een aangepaste agent bouwen met behulp van de Supervisor-API (bèta)
• Supervisor Agent gebruiken om een gecoördineerd multiagentsysteem te maken
• Querymodelservices
• AI-governance met Unity AI Gateway