Supervisor-API (Beta)

Important

Den här funktionen finns i Beta. Kontoadministratörer kan styra åtkomsten till den här funktionen från sidan Förhandsversioner . Se Hantera förhandsversioner av Azure Databricks.

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

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

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

Connector Description
system_ai_agent_google_drive Sök efter och läsa filer från Google Drive.
system_ai_agent_github_mcp Få åtkomst till GitHub-arkiv, ärenden och pull-begäranden.
system_ai_agent_atlassian_mcp Sök efter och hantera Atlassian-resurser (Jira, Confluence).
system_ai_agent_sharepoint Sök efter och läsa filer från SharePoint.

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

Anmärkning

Svar i bakgrundsläge behålls i databasen i högst 30 dagar.

Verktyg som stöds

Du definierar verktyg i tools matrisen för din begäran. Varje post anger ett type och ett konfigurationsobjekt med samma nyckel. Ett Genie Space-verktyg har "type": "genie_space" och ett "genie_space": {...}-objekt. API:et stöder följande verktygstyper:

Verktygstyp Description Omfång
genie_space Frågar ett Genie Space för att besvara frågor om dina data. Parametrar: id, description. genie
uc_function Anropar en Unity Catalog-funktion som ett agentverktyg. Parametrar: name, description. unity-catalog
uc_connection Ansluter till en extern MCP-server via en Unity Catalog-anslutning. Parametrar: name, description. För Azure Databricks-hanterade systemanslutningar anger du name till en system_ai_agent_*-anslutning (se Steg 3 (valfritt): Anslut till tjänster från tredje part med systemhanterade anslutningar). Obs! Anpassade MCP-servrar i appar stöds ännu inte. unity-catalog
app Anropar en Azure Databricks appslutpunkt. Parametrar: name, description. apps
knowledge_assistant Anropar en endpunkt för Kunskapsassistenten. Parametrar: knowledge_assistant_id, description. model-serving

Parametrar som stöds

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

  • input: konversationsmeddelanden som ska skickas.
  • tools: värdbaserade verktygsdefinitioner (genie_space, uc_function, knowledge_assistant, app, uc_connection).
  • 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.

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.
  • Funktionsanrop på klientsidan: Endast värdbaserade verktyg stöds. Du kan inte skicka function verktygsdefinitioner för klienten att köra och du kan inte blanda värdbaserade verktyg med verktyg på klientsidan function i samma begäran.
  • 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.
  • Azure Databricks Apps OBO stöds inte: Auktorisering på användarens vägnar stöds inte för Supervisor-API:et. Använd systemauktorisering och bevilja behörigheter för dina verktyg om du vill använda api:et För övervakare i Azure Databricks Appar.

Nästa steg

  • Last updated on