Supervisor-API (Beta)

Api:et för övervakare förenklar byggandet av anpassade agenter på Azure Databricks med stöd för bakgrundsläge för långvariga uppgifter. Du definierar modellen, verktygen och instruktionerna i en begäran till en OpenResponses-kompatibel slutpunkt (POST ai-gateway/mlflow/v1/responses) och Azure Databricks kör agentloopen åt dig: anropar modellen upprepade gånger, väljer och kör verktyg och syntetiserar ett slutligt svar.

Det finns tre metoder för att skapa en anpassad verktygsanropsagent på Azure Databricks:

• Agent Bricks Supervisor Agent (rekommenderas): Helt deklarativ med mänsklig feedbackoptimering för bästa kvalitet.
• Api för övervakare: Skapa en anpassad agent programmatiskt – välj modeller vid körning, kontrollera vilka verktyg som ska användas per begäran eller iterera under utvecklingen. Också rätt val när du behöver kontroll över modellval vid avlastning av agentloophantering till Azure Databricks.
• AI Gateway-enhetliga eller inbyggda API:er: Skriv en egen agentloop. Azure Databricks tillhandahåller endast LLM-slutsatsdragningsskiktet. Använd enhetliga API:er där det är möjligt för att aktivera växlingsmodeller eller providerspecifika interna API:er (/openai, /anthropic, /gemini) när du porterar befintlig kod till Azure Databricks eller använder providerspecifika funktioner.

Requirements

• Unity AI Gateway för agenter och LLM:er har aktiverats för ditt konto. Se Hantera förhandsversioner av Azure Databricks.
  • Eftersom API:et för övervakare körs via Unity AI Gateway gäller AI Gateway-funktioner som slutsatsdragningstabeller, hastighetsbegränsningar och återställningar. Användningsspårning stöds inte i den här betaversionen.
• Lagra OpenTelemetry-spårningar i Unity Catalog aktiverat för ditt konto. Se Hantera förhandsversioner av Azure Databricks.
  • Lagrar spår från supervisor-API-agent-slinga i Unity Catalog-tabeller.
• En Azure Databricks arbetsyta i en stödd region.
• Unity Catalog har aktiverats för din arbetsyta. Se Aktivera en arbetsyta för Unity Catalog.
• De verktyg som du skickar (Genie Spaces, Unity Catalog-funktioner, MCP-servrar, kunskapsassistenter, appar) måste redan vara konfigurerade och tillgängliga.
• Paketet databricks-openai har installerats: pip install databricks-openai

Steg 1: Skapa ett LLM-anrop med en enda tur

Börja med ett grundläggande anrop utan verktyg. Klienten DatabricksOpenAI konfigurerar automatiskt bas-URL:en och autentiseringen för din arbetsyta:

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)

Steg 2: Lägg till värdbaserade verktyg för att köra agentloopen

När du lägger till verktyg i begäran hanterar Azure Databricks en loop med flera svängar åt dig: modellen bestämmer vilka verktyg som ska anropas, Azure Databricks kör dem, matar tillbaka resultaten till modellen och upprepas tills modellen genererar ett slutligt svar.

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)

Steg 3 (valfritt): Anslut till tjänster från tredje part med systemhanterade anslutningar

Azure Databricks tillhandahåller systemhanterade anslutningar för populära tredjepartstjänster som Google Drive, GitHub, Atlassian, SharePoint och Glean. Dessa anslutningar är ett snabbt alternativ till att konfigurera en egen extern MCP-server – du kan fortfarande använda verktygstypen uc_connection för att ansluta till valfri extern MCP-server som du har konfigurerat själv.

Systemhanterade anslutningar kräver att tredjepartsanslutningarna för Agents Beta är aktiverade på din arbetsyta. Se Hantera förhandsversioner av Azure Databricks.

Följande kontakter stöds:

Skicka en anslutning i matrisen tools med hjälp av verktygstypen uc_connection med fältet name inställt på anslutningens namn:

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

Användare-till-maskin (U2M) autentisering

Varje användare autentiserar individuellt. OAuth-token delas inte mellan användare. På den första begäran som använder en anslutning och som användaren inte har autentiserat, slutförs svaret med status: "failed" och ett oauth-fel som innehåller en URL för inloggning:

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

Öppna URL:en i en webbläsare, slutför OAuth-flödet och kör sedan samma begäran igen.

Steg 4 (valfritt): Lägg till ett funktionsverktyg på klientsidan

Använd function-verktyg när du vill att ditt program ska köra anpassad logik tillsammans med Azure Databricks värdbaserade verktyg. Deklarera ett funktionsverktyg med type: "function", ett name, ett valfritt descriptionoch ett JSON-schemaobjekt 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,
      },
    }
  ],
)

Övervakar-API:et lagrar inte konversationstillstånd mellan begäranden, så ett funktionsanrop på klientsidan tar två varv:

1. Vänd 1. Modellen returnerar ett function_call objekt (till exempel "anropa get_weather med location=Paris") i stället för ett slutligt svar.
2. Koden kör funktionen lokalt och ger ett resultat.
3. Sväng 2. Anropa responses.create() igen och skicka de ursprungliga indata plus modellens function_call plus en ny function_call_output med ditt resultat. Modellen använder resultatet för att skapa det slutliga svaret.

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)

Ytterligare mönster (strömning, värdbaserade lösningar och klientverktyg, MCP-godkännande och felsökning) finns i kompetensen för funktionsanrop på klientsidan i Supervisor API.

Steg 5: Aktivera spårning

Skicka en trace_destination i begärandetexten för att skicka spårningar från agentloopen till Unity Catalog-tabeller. Varje begäran genererar en spårning som samlar in hela sekvensen av modellanrop och verktygskörningar. Om du inte anger trace_destinationskrivs inga spårningar. Information om konfiguration finns i Lagra OpenTelemetry-spårningar i Unity Catalog.

Använd klienten databricks-openai Python och skicka den 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>"
    }
  }
)

Om du också vill returnera spårningen direkt i API-svaret skickar du "databricks_options": {"return_trace": True} in extra_body.

Du kan också använda distribuerad MLflow-spårning för att kombinera spårningar från din programkod och api-agentloopen Supervisor till en enda spårning från slutpunkt till slutpunkt. Sprid spårningskontextrubriker med hjälp av fältet 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,
  )

Bakgrundsläge

Med bakgrundsläget kan du köra långvariga agentarbetsflöden som omfattar flera verktygsanrop och komplexa resonemang utan att vänta på att de ska slutföras synkront. Skicka din begäran med background=True, ta emot ett svars-ID omedelbart och sök efter resultatet när det är klart. Detta är särskilt användbart för agenter som frågar efter flera datakällor eller kedjar ihop flera verktyg i en enda begäran.

Skapa en bakgrundsbegäran

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"

Sök efter resultatet

Använd responses.retrieve() för att kontrollera statusen tills den når ett terminaltillstånd:

from time import sleep

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

print(response.output_text)

Bakgrundsläge med MCP

För säkerhet kräver övervakar-API:et uttryckligt användargodkännande innan mcp-verktygsanrop körs i bakgrundsläge. När agentloopen väljer ett MCP-verktyg slutförs svaret med en mcp_approval_request. Du kan granska verktygsnamnet, serveretiketten och argumenten som modellen tänker skicka:

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

Om du vill godkänna verktygsanropet och fortsätta agentloopen skickar du en mcp_approval_response tillbaka i input fältet med den fullständiga konversationshistoriken:

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

Verktyg som stöds

Du definierar verktyg i tools matrisen för din begäran. Varje verktygsobjekt delar tre fält på den översta nivån:

• type (sträng, obligatorisk): Diskriminatorn som anger verktygstypen.
• name (sträng, valfritt): Visningsnamn som visas för modellen.
• description (sträng, valfritt): Tips till modellen om när verktyget ska anropas.

Dessutom har varje verktygsobjekt ett kapslat konfigurationsobjekt vars nyckel matchar type värdet. Tabellen nedan dokumenterar den kapslade konfigurationen för varje verktygstyp som stöds.

För serving_endpointstöds endast ResponseAgent-, ChatCompletions- och ChatAgent-slutpunkter.

För appstöds endast MCP-appar (med prefixet mcp- ) och anpassade ResponseAgent-appar (med agent- prefixet).

För uc_connectionanvänder du anslutningsnamnet som du har skapat för en extern MCP-server eller en system_ai_agent_* systemhanterad anslutningsapp (se Steg 3 (Valfritt): Anslut till tjänster från tredje part med systemhanterade anslutningar). Anpassade MCP-servrar i appar stöds ännu inte.

Körning av kod

När en begäran behöver beräknas kör övervakaren modellgenererad kod i en serverlös beräkningssession i begränsat läge för att analysera data, transformera filer eller köra beräkningar. Den stöder kommandona Python (standard), SQL och shell. Övervakaren skriver och kör själva koden när det behövs, så att du inte aktiverar, konfigurerar eller anger koden.

Kodkörning körs i en låst sandbox-miljö med:

• Ingen internetåtkomst. Den blockerar alla utgående nätverksutgående data oavsett din arbetsytas nätverksprincip, så kod som körs i sandbox-miljön kan inte nå externa slutpunkter.
• Åtkomst begränsad till Azure Databricks. Den har ingen egen dataåtkomst. Den kan läsa de Unity Catalog-tabeller som du deklarerar med table verktyget i samma begäran.

Parametrar som stöds

Varje begäran till övervakar-API:et godkänner följande parametrar.

• model: en av följande modeller som stöds. Ändra det här fältet om du vill byta leverantör utan att ändra resten av koden.
  • 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: konversationsmeddelanden som ska skickas.
• tools: värdbaserade verktygsdefinitioner (genie_space, dashboard, uc_function, table, knowledge_assistant, serving_endpoint, web_search, vector_search_index, volume, app, uc_connection) och funktionsverktyg på klientsidan (function). Se Steg 4 (valfritt): Lägg till ett funktionsverktyg på klientsidan.
• instructions: en systemfråga som vägleder övervakarens beteende.
• stream: ställd till true för att strömma svar.
• background: ställ in till true för att köra begäran asynkront. Returnerar ett svars-ID som du avsöker med responses.retrieve(). Se Bakgrundsläge.
• trace_destination: valfritt objekt med catalog_namefälten , schema_nameoch .table_prefix När det är inställt skriver övervakar-API:et en spårning av den fullständiga agentloopen till de angivna Unity Catalog-tabellerna. Skicka via extra_body i Python-klienten.

API:et stöder inte slutsatsdragningsparametrar som temperature. Servern hanterar dessa internt.

Authorization

Övervakar-API:et kör agentloopen med anroparens autentiseringsuppgifter, så de verktyg som anropas respekterar anroparens Behörigheter för Unity-katalogen. När du anropar API:et direkt autentiseras DatabricksOpenAI klienten som du.

När du anropar övervakar-API:et från en Azure Databricks app kan du köra verktyg antingen som appens tjänsthuvudnamn (appauktorisering) eller som den begärande användaren (användarauktorisering). För appauktorisering beviljar du appens tjänsthuvudnamn behörigheter för varje verktyg. För användarauktorisering vidarebefordrar du användarens token till DatabricksOpenAI klienten och lägger till de nödvändiga omfången för användarauktorisering. Se Kör verktyg som den begärande användaren.

Limitations

Api:et för övervakare har följande begränsningar:

• Körning av bakgrundsläge: Begäranden i bakgrundsläge har en maximal körningstid på 30 minuter.
• Direktuppspelning i bakgrundsläge: stream och background kan inte båda vara true i samma begäran.
• Varaktig körning: Automatisk återställning från fel eller avbrott, med garantier för exakt en gångs körningar för agentloopen, stöds inte.
• Behörighet för arbetsyta för webbsökning: Verktyget web_search är inte tillgängligt i arbetsytor med HIPAA/BAA-regelefterlevnad aktiverad. Den är endast tillgänglig i regioner med en webbsökningskompatibel intern modell eller bearbetning mellan geografiska områden aktiverad. Begäranden som inkluderar web_search från ej berättigade arbetsytor avvisas.

Ytterligare resurser

• Skapa en anpassad agent med hjälp av Api för övervakare (Beta)
• Använda övervakaragenten för att skapa ett samordnat system med flera agenter
• Fråga Unity AI Gateway-slutpunkter
• Unity AI Gateway för agenter och LLM:er