Supervisor-API (bèta)

Belangrijk

Deze functie bevindt zich in de bètaversie. Accountbeheerders kunnen de toegang tot deze functie beheren vanaf de pagina Previews . Zie Azure Databricks previews beheren.

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

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

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

Connector Description
system_ai_agent_google_drive Bestanden zoeken en lezen vanuit Google Drive.
system_ai_agent_github_mcp Toegang tot GitHub opslagplaatsen, problemen en pull-aanvragen.
system_ai_agent_atlassian_mcp Atlassian-resources zoeken en beheren (Jira, Confluence).
system_ai_agent_sharepoint Bestanden zoeken en lezen uit SharePoint.

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

Note

Antwoorden in de achtergrondmodus worden maximaal 30 dagen bewaard in de database.

Ondersteunde hulpprogramma's

U definieert hulpprogramma's in de tools matrix van uw aanvraag. Elke vermelding geeft een type en een configuratieobject met dezelfde sleutel op. Bijvoorbeeld, een Genie Space-hulpprogramma heeft een "type": "genie_space" en een "genie_space": {...} object. De API ondersteunt de volgende hulpprogrammatypen:

Type hulpprogramma Description Scope
genie_space Query's uitvoeren op een Genie-ruimte om vragen over uw gegevens te beantwoorden. Parameters: id, description. genie
uc_function Roept een Unity Catalog-functie aan als agenthulpprogramma. Parameters: name, description. unity-catalog
uc_connection Maakt verbinding met een externe MCP-server via een Unity Catalog-verbinding. Parameters: name, description. Voor Azure Databricks-beheerde systeemverbindingen stelt u name in op een system_ai_agent_*-connector (zie Step 3 (optioneel): Verbinding maken met services van derden met door het systeem beheerde verbindingen). Opmerking: aangepaste MCP-servers in apps worden nog niet ondersteund. unity-catalog
app Roept een Azure Databricks App-eindpunt aan. Parameters: name, description. apps
knowledge_assistant Roept een Knowledge Assistant-eindpunt aan. Parameters: knowledge_assistant_id, description. model-serving

Ondersteunde parameters

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

  • input: de gespreksberichten die moeten worden verzonden.
  • tools: gehoste hulpprogrammadefinities (genie_space, uc_function, knowledge_assistant, app, , ). uc_connection
  • 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.

Limitations

De Supervisor-API heeft de volgende beperkingen:

  • Runtime achtergrondmodus: aanvragen voor achtergrondmodus hebben een maximale uitvoeringstijd van 30 minuten.
  • Functieaanroepen aan de clientzijde: alleen gehoste hulpprogramma's worden ondersteund. U kunt geen hulpprogrammadefinities doorgeven function die door de client moeten worden uitgevoerd en u kunt gehoste hulpprogramma's niet combineren met hulpprogramma's aan de clientzijde function in dezelfde aanvraag.
  • 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.
  • Azure Databricks Apps OBO niet ondersteund: Autorisatie namens de gebruiker wordt niet ondersteund voor de Supervisor-API. Als u de Supervisor-API in Azure Databricks Apps wilt gebruiken, gebruikt u systeemautorisatie en verleent u machtigingen voor uw hulpprogramma's.

Volgende stappen 

  • Last updated on