Rozhraní API pro správce (beta verze)

Important

Tato funkce je v beta verzi. Správci pracovního prostoru můžou tuto funkci povolit na stránce Previews . Viz Manage Azure Databricks preview.

Rozhraní API Supervisor zjednodušuje vytváření vlastních agentů na Azure Databricks s podporou pro režim na pozadí pro dlouhotrvající úlohy. Model, nástroje a pokyny definujete v jednom požadavku na OpenResponses kompatibilní koncový bod (POST ai-gateway/mlflow/v1/responses) a Azure Databricks spustí smyčku agenta pro vás: opakované volání modelu, výběr a spuštění nástrojů a syntetizace konečné odpovědi.

Existují tři přístupy k vytvoření přizpůsobeného agenta pro volání nástrojů na Azure Databricks:

  • Agent Bricks Supervisor Agent (doporučeno): Plně deklarativní s optimalizací lidské zpětné vazby pro nejvyšší kvalitu.
  • Rozhraní API správce: Programově sestavte vlastního agenta – vyberte modely za běhu, určete, které nástroje se mají použít pro jednotlivé požadavky, nebo iterace během vývoje. Správná volba také v případě, že potřebujete mít kontrolu nad výběrem modelu při přesměrování správy smyček agentů na Azure Databricks.
  • Sjednocená nebo nativní API AI Gateway: Napište vlastní smyčku agentu. Azure Databricks poskytuje pouze vrstvu odvození LLM. Pokud je to možné, používejte sjednocená rozhraní API k umožnění přepínání modelů nebo při portaci existujícího kódu na Azure Databricks využívejte nativní rozhraní API specifická pro poskytovatele (/openai, /anthropic, /gemini) nebo funkce specifické pro poskytovatele.

Požadavky

Krok 1: Vytvoření jednoturnového volání LLM

Začněte základním voláním bez nástrojů. Klient DatabricksOpenAI automaticky nakonfiguruje základní adresu URL a ověřování pro váš pracovní prostor:

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)

Krok 2: Přidání hostovaných nástrojů pro fungování smyčky agenta

Když do požadavku zahrnete nástroje, Azure Databricks za vás spravuje iterativní smyčku: model rozhodne, které nástroje volat, Azure Databricks je spustí, předá výsledky zpět do modelu a opakuje se, dokud model nevygeneruje konečnou odpověď.

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)

Krok 3 (volitelné): Připojení ke službám třetích stran pomocí systémových spravovaných připojení

Azure Databricks poskytuje systémem spravovaná připojení pro oblíbené služby třetích stran, jako jsou Google Drive, GitHub, Atlassian, SharePoint a Glean. Tato připojení představují rychlou alternativu k nastavení vlastního externího serveru MCP – stále můžete použít daný typ nástroje k připojení k libovolnému externímu serveru MCP, který jste si sami nakonfigurovali.

Systémová spravovaná připojení vyžadují, aby ve vašem pracovním prostoru byly povolené konektory třetích stran pro agenty Beta. Viz Manage Azure Databricks preview.

Podporují se následující konektory:

Connector Description
system_ai_agent_google_drive Hledání a čtení souborů z disku Google.
system_ai_agent_github_mcp Přístup k úložištím GitHub, problémům a žádostem o přijetí změn
system_ai_agent_atlassian_mcp Vyhledávání a správa prostředků Atlassian (Jira, Confluence).
system_ai_agent_sharepoint Hledání a čtení souborů z SharePoint
system_ai_agent_glean_mcp Vyhledávání v podnikovém obsahu indexované Gleanem

Předejte spojnici v tools poli pomocí uc_connection typu nástroje s name polem nastaveným na název spojnice:

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

Ověřování uživatelem na počítač (U2M)

Každý uživatel se ověřuje jednotlivě. Tokeny OAuth se mezi uživateli nesdílí. Při prvním požadavku používajícím konektor, který uživatel neověřil, se odpověď dokončí s status: "failed" a chyba oauth obsahující přihlašovací URL adresu se zobrazí.

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

Otevřete adresu URL v prohlížeči, dokončete tok OAuth a pak znovu spusťte stejný požadavek.

Krok 4 (volitelné): Přidání nástroje funkce na straně klienta

Nástroje function použijte, pokud chcete, aby aplikace spouštěla vlastní logiku společně s nástroji hostovanými Azure Databricks. Deklarujte funkční nástroj pomocí type: "function", name, volitelného description a objektu schématu JSON 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,
      },
    }
  ],
)

API Supervisoru neukládá mezi požadavky stav konverzace, takže volání funkce na straně klienta probíhá ve dvou krocích:

  1. Krok 1. Model vrátí položku function_call (například „volání get_weather s location=Paris“) místo konečné odpovědi.
  2. Váš kód spustí funkci místně a vytvoří výsledek.
  3. Otočte 2. Znovu zavolejte responses.create() a předejte původní vstup, function_call modelu a nový function_call_output s vaším výsledkem. Model použije výsledek k vytvoření konečné odpovědi.
Příklad nástroje funkce na straně klienta 
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)

Další vzory (streamování, hostované plus klientské nástroje, schválení MCP, řešení potíží) najdete v dovednosti volání funkce na straně klienta rozhraní API správce.

Krok 5: Povolení trasování

Odešlete trasování ze smyčky agenta do tabulek katalogu Unity tím, že v těle požadavku uvedete trace_destination. Každý požadavek vygeneruje trasování, které zachycuje úplnou posloupnost volání modelu a provádění nástrojů. Pokud nenastavíte trace_destination, žádné stopy nebudou zapsány. Podrobnosti o nastavení najdete v tématu Ukládání trasování OpenTelemetry v katalogu Unity.

Pomocí klienta databricks-openai Python ho předejte přes 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>"
    }
  }
)

Pokud chcete také vrátit trasování přímo v odpovědi rozhraní API, předejte ho v rámci "databricks_options": {"return_trace": True}extra_body.

Distribuované trasování MLflow můžete použít také ke kombinování trasování z kódu aplikace a smyčky agenta rozhraní API správce do jednoho kompletního trasování. Propagujte hlavičky kontextu trasování pomocí pole 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,
  )

Režim pozadí

Režim na pozadí umožňuje spouštět dlouhotrvající pracovní postupy agentů, které zahrnují více volání nástrojů a složité důvody, aniž byste čekali na jejich dokončení synchronně. Odešlete svoji žádost pomocí background=True, okamžitě obdržíte ID odpovědi a odešlete dotaz na výsledek, až bude připravený. To je zvlášť užitečné pro agenty, kteří dotazuje více zdrojů dat nebo zřetězí několik nástrojů společně v rámci jednoho požadavku.

Vytvořte požadavek na pozadí

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"

Hlasování o výsledku

Slouží responses.retrieve() ke kontrole stavu, dokud nedosáhne stavu terminálu:

from time import sleep

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

print(response.output_text)

Režim pozadí s MCP

Pro zabezpečení vyžaduje rozhraní API správce explicitní schválení uživatele před spuštěním jakéhokoli volání nástroje MCP v režimu pozadí. Jakmile agent-smyčka vybere nástroj MCP, odpověď se dokončí pomocí mcp_approval_request. Můžete zkontrolovat název nástroje, popisek serveru a argumenty, které model hodlá předat:

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

Pokud chcete potvrdit volání nástroje a pokračovat v činnosti agenta, odešlete zpět mcp_approval_response do pole input s úplnou historií konverzace:

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

Note

Odpovědi na režim pozadí se uchovávají v databázi po dobu maximálně 30 dnů.

Podporované nástroje

Nástroje definujete v tools poli vaší žádosti. Každý objekt nástroje sdílí tři pole nejvyšší úrovně:

  • type (řetězec, povinné): Rozlišovací parametr, který určuje typ nástroje.
  • name (řetězec, volitelné): Zobrazovaný název zobrazený pro model.
  • description (řetězec, volitelné): Pokyn pro model, kdy má tento nástroj použít.

Každý objekt nástroje navíc nese vnořený objekt konfigurace, jehož klíč odpovídá hodnotě type . Následující tabulka dokumentuje vnořenou konfiguraci pro každý podporovaný typ nástroje.

Typ nástroje Example Scope
genie_space {
"type": "genie_space",
"name": "Customer reviews",
"genie_space": {
"space_id": "<id>"
}
}		 genie
dashboard {
"type": "dashboard",
"name": "Sales dashboard",
"dashboard": {
"dashboard_id": "<id>"
}
}		 dashboards
uc_function {
"type": "uc_function",
"name": "Flag urgent review",
"uc_function": {
"name": "<catalog>.<schema>.<function>"
}
}		 unity-catalog
table {
"type": "table",
"name": "Customer reviews",
"table": {
"name": "<catalog>.<schema>.<table_name>"
}
}		 unity-catalog
knowledge_assistant {
"type": "knowledge_assistant",
"name": "Internal docs",
"knowledge_assistant": {
"knowledge_assistant_id": "<id>"
}
}		 model-serving
serving_endpoint {
"type": "serving_endpoint",
"name": "Custom agent",
"serving_endpoint": {
"name": "<endpoint-name>"
}
}		 model-serving
web_search {
"type": "web_search",
"name": "Web search",
"web_search": {}
}		 model-serving
vector_search_index {
"type": "vector_search_index",
"name": "Product docs",
"vector_search_index": {
"name": "<catalog>.<schema>.<index>",
"columns": ["title", "content"]
}
}		 vector-search
volume {
"type": "volume",
"volume": {
"name": "<catalog>.<schema>.<volume>",
"description": "Searches files in a Unity Catalog volume"
}
}		 unity-catalog
app {
"type": "app",
"name": "Support agent",
"app": {
"name": "<app-name>"
}
}		 apps
uc_connection {
"type": "uc_connection",
"name": "GitHub",
"uc_connection": {
"name": "system_ai_agent_github_mcp"
}
}		 unity-catalog
function {
"type": "function",
"name": "get_weather",
"description": "Get the current weather for a location.",
"parameters": {
"type": "object",
"properties": { "location": { "type": "string" } },
"required": ["location"]
}
}		 None

Pro serving_endpoint jsou podporovány pouze koncové body ResponseAgent, ChatCompletions a ChatAgent.

Pro app jsou podporovány pouze aplikace MCP (s předponou mcp-) a vlastní aplikace ResponseAgent (s předponou agent-).

Pro uc_connection použijte název připojení, který jste vytvořili pro externí server MCP, nebo system_ai_agent_* konektor spravovaný systémem (viz Krok 3 (volitelné): Připojení ke službám třetích stran pomocí připojení spravovaných systémem). Vlastní servery MCP v aplikacích se nepodporují.

Provádění kódu

Pokud požadavek vyžaduje výpočet, správce spouští modelem vygenerovaný kód v bezserverové relaci bez serveru v izolovaném prostoru ( sandbox) za účelem analýzy dat, transformace souborů nebo spouštění výpočtů. Podporuje příkazy Python (výchozí), SQL a shell. Správce zapíše a spustí samotný kód v případě potřeby, takže kód nepovolíte, nakonfigurujete ani nezadáte.

Spouštění kódu probíhá v přísně zabezpečeném sandboxu s:

  • Přístup k internetu není k dispozici. Blokuje veškerou odchozí síťovou komunikaci bez ohledu na síťové zásady vašeho pracovního prostoru, takže kód spuštěný v sandboxu nemůže přistupovat k externím koncovým bodům.
  • Přístup omezený pouze na Azure Databricks. Nemá vlastní přístup k datům. Může číst tabulky Katalogu Unity, které deklarujete pomocí table nástroje ve stejném požadavku.

Podporované parametry

Každý požadavek na rozhraní API správce přijímá následující parametry.

  • input: konverzační zprávy, které se mají odeslat.
  • tools: definice hostovaných nástrojů (genie_space, , , dashboarduc_function, table, knowledge_assistantserving_endpoint, , web_search, vector_search_index, , volume, ) appa nástroje funkce na straně klienta (uc_connection). function Viz krok 4 (volitelné): Přidání nástroje funkce na straně klienta
  • instructions: systémová výzva k vedení chování nadřízeného.
  • stream: nastavte hodnotu true pro streamování odpovědí.
  • background: nastavte, aby true se požadavek spustil asynchronně. Vrací ID odpovědi, s jehož pomocí se dotazujete pomocí responses.retrieve(). Viz režim pozadí.
  • trace_destination: volitelný objekt s catalog_name, schema_namea table_prefix pole. Při nastavení zapíše rozhraní API správce trasování celé smyčky agenta do zadaných tabulek katalogu Unity. Předávat přes extra_body v klientovi Python.

Rozhraní API nepodporuje parametry odvození, například temperature. Server je spravuje interně.

Authorization

Supervisor API spouští smyčku agenta s přihlašovacími údaji volajícího, takže nástroje, které volá, respektují oprávnění volajícího v Unity Catalog. Když voláte rozhraní API přímo, klient DatabricksOpenAI se autentizuje jako vy.

Při volání rozhraní API správce z aplikace Azure Databricks můžete spustit nástroje buď jako instanční objekt aplikace (autorizace aplikace), nebo jako žádající uživatel (autorizace uživatele). Pro autorizaci aplikací udělte oprávnění instančního objektu aplikace pro každý nástroj. Pro autorizaci uživatele předáte token DatabricksOpenAI uživatele klientovi a přidejte požadované obory autorizace uživatele. Viz Spouštět nástroje jako žadatel.

Limitations

Rozhraní API pro správce má následující omezení:

  • Režim běhu na pozadí: Žádosti v režimu na pozadí mají maximální dobu trvání 30 minut.
  • Streamování v režimu na pozadí: stream a background nemůže být true oba ve stejném požadavku.
  • Trvalé spuštění: Automatické obnovení při selhání nebo přerušení s přesně jednou zárukou spuštění smyčky agenta není podporováno.
  • Dostupnost vyhledávání na webu v pracovních prostorech: Nástroj web_search není k dispozici v pracovních prostorech se zapnutým souladem s předpisy HIPAA/BAA. Je k dispozici pouze v oblastech s nativním modelem podporujícím vyhledávání na webu nebo s povoleným zpracováním napříč zeměpisnými oblastmi. Žádosti, které zahrnují web_search z nezpůsobilých pracovních prostorů, se odmítají.

Další zdroje informací

  • Last updated on