Agent Server

Ein Agent-Server ist die Bibliothek, die deinen Agent-Code in einen Service umwandelt. Er kapselt die Agentenschleife in einen HTTP-Server, definiert die API, die Clients aufrufen, um den Agenten auszuführen, verwaltet die Client-Verbindungen und bestimmt, was passiert, wenn ein Run unterbrochen wird. Der Agent-Server läuft auf der Agent-Runtime. Um zu erfahren, wie die Schichten zusammenpassen, siehe Agents auf Azure Databricks bereitstellen.

Agent-Server auf Azure Databricks

Azure Databricks stellt drei Agent-Server bereit. Für neue Agenten empfiehlt Databricks DurableAgentServer.

Agent-Server	Package	Client-API	Langlebige Ausführung	Verwendet von
`DurableAgentServer` (empfohlen)	`databricks_agentkit`, im `databricks-agentbricks`-Paket	Invocation-API bei `/api/invocations`: synchron, streaming und Hintergrundausführungen mit Stream-Wiederverbindung	Ein Laufzeitspeicher, der `agentbricks deploy` bereitstellt, plus Absturzwiederherstellung durch einen Wiederherstellungshandler	Projekte, die du mit der Agent Bricks CLI erstellst,
`LongRunningAgentServer` (Vermächtnis)	`databricks_ai_bridge.long_running`, im `databricks-ai-bridge[agent-server]`-Paket	OpenAI Responses API bei `/responses`, mit Hintergrundläufen und Stream-Wiederaufnahme	Ausführungsstatus in einer Lakebase-Datenbank, die du selbst konfigurierst. Nach einem Absturz setzt ein neuer Versuch den Lauf aus dem Ereignisprotokoll des unterbrochenen Versuchs fort.	Die `agent-openai-advanced` und `agent-langgraph-advanced`App-Vorlagen
MLflow `AgentServer` (Legacy)	`mlflow.genai.agent_server`, im `mlflow`-Paket	OpenAI Responses API bei `/responses`: synchrone und Streaming-Läufe	None	Die Vorlagen der Basis-App, wie zum Beispiel `agent-openai-agents-sdk`

LongRunningAgentServer erweitert das MLflow AgentServer, und beide bedienen Agenten, die die MLflow-Schnittstelle ResponsesAgent implementieren. Um einen Agenten bereitzustellen und zu pflegen, der einen davon verwendet, siehe Run agents on Databricks Apps using the legacy agent server. Um einen Agenten auf einem dieser Server abzufragen, siehe Auf Azure Databricks bereitgestellte Agents abfragen.

`DurableAgentServer`

DurableAgentServer ist der Agent Bricks-Agentenserver. Es kapselt deine Agentenschleife in einem HTTP-Server, der die Aufruf-API bedient, jeden Durchlauf verfolgt und Läufe wiederherstellt, die durch einen Absturz oder Neustart unterbrochen werden. Agenten, die du mit der Agent Bricks CLI erstellst, verwenden standardmäßig DurableAgentServer.

DurableAgentServer bietet:

Eine API für jeden Anforderungsmodus: Synchrone, Streaming- und Hintergrundaufrufe sowie Stream-Wiederverbindung, alle vom selben Handler bedient.
Idempotente Aufrufe: Eine vom Client generierte Aufruf-ID stellt sicher, dass eine erneute Anfrage keinen doppelten Lauf startet.
Sequenzierte Sitzungen: Aufrufe in derselben Sitzung werden nacheinander, jeweils nur eine auf einmal, in der richtigen Reihenfolge ausgeführt.
Persistenter Laufzustand: Bei der Bereitstellung bleiben Laufstatus, Ereignisse und Ergebnisse nach Worker-Neustarts erhalten.
Absturz-Wiederherstellung: Der Server erkennt unterbrochene Läufe und startet einen erneuten Versuch.
Autorisierung im Namen des anfragenden Benutzers: Tools können mit den Berechtigungen des Benutzers agieren, der die Anfrage gesendet hat.
Benutzerdefinierte Endpunkte: DurableAgentServer Ist eine FastAPI-Anwendung, sodass du deine eigenen Routen hinzufügen kannst.

Anforderungen

DurableAgentServer hat folgende Anforderungen:

Python 3.10 und höher.
Das Paket databricks-agentbricks , das die Bibliothek databricks_agentkit beinhaltet. Projekte, die du mit agentbricks init erstellst, deklarieren es als Abhängigkeit.

Registrieren Sie Ihren Agenten

Wenn Sie ein Projekt mit agentbricks initerstellen, übernimmt die CLI dies für Sie. Der generierte runtime/main.py erstellt den Server und registriert die Aufruf- und Wiederherstellungshandler der Vorlage, sodass man nur den Agentencode in agent/ bearbeitet. Folgen Sie den Schritten in diesem Abschnitt, um einen bestehenden Agenten einzubinden oder Ihren eigenen Handler zu schreiben.

Erstelle ein DurableAgentServer und registriere einen asynchronen Invocation-Handler mit @app.invoke. Der Handler erhält das input der Anfrage und einen Aufrufkontext und liefert ein JSON-serialisierbares Ergebnis. Veröffentlichen Sie den Fortschritt als Ereignisse mit context.emit.

from databricks_agentkit import DurableAgentServer, InvocationContext

app = DurableAgentServer()


@app.invoke
async def invoke(input, context: InvocationContext) -> dict:
    await context.emit({"type": "status", "message": "Looking that up"})
    answer = await run_my_agent(input, session_id=context.session_id)
    return {"answer": answer}

Du kannst einen Invocation-Handler registrieren, und der Server startet nicht ohne einen. Der Handler bedient jeden Anfragemodus: Der Client entscheidet, ob er auf das Ergebnis wartet, Ereignisse streamt oder im Hintergrund ausgeführt wird.

Um den Server lokal zu betreiben, starte ihn mit agentbricks dev. Projekte, die du mit agentbricks init erstellst, beinhalten einen Entrypoint, der den Server mit Uvicorn betreibt, und eine app.yaml Datei, die denselben Entrypoint nach dem Deployment startet.

Aufrufkontext

Das zweite Argument des Handlers ist ein InvocationContext:

Attribut	Description
`invocation_id`	Die ID, die der Client für diesen Aufruf gesendet hat.
`session_id`	Die Sitzung, zu der der Aufruf gehört, oder `None`, wenn der Client keine Sitzung gesendet hat.
`attempt`	Die Versuchsnummer. Der erste Versuch ist `1`.
`is_recovery`	`True` wenn der Wiederherstellungs-Handler einen Ersetzungsversuch durchführt.
`emit(event)`	Speichert ein JSON-Event, liefert es an Streaming-Clients und gibt die Position des Events im Stream zurück.
`request_auth`	Der Anmeldeinformations-Resolver für den anfordernden Benutzer, wenn der Agent eine Autorisierung des anfordernden Benutzers erfordert. Andernfalls, `None`.

Invocation-API

DurableAgentServer bedient die Aufruf-API unter /api/invocations:

POST /api/invocations beginnt einen Aufruf. Standardmäßig wartet die Anfrage auf das Ergebnis. Legen Sie stream fest, um Ereignisse als Server-Sent Events zu empfangen, oder background, um sofort mit einer Status-URL zurückzukehren.
GET /api/invocations/<id> gibt den Status eines Aufrufs zurück und nach Abschluss dessen Ausgabe.
Mit GET /api/invocations/<id>/events?after=<event-id> werden gespeicherte Ereignisse gestreamt, sodass ein Client sich nach einer abgebrochenen Verbindung wieder verbinden kann.

Für Anfragefelder, Beispiele und Antwortformate siehe Abfrageagenten, die auf Azure Databricks bereitgestellt sind.

Idempotenz

Die Clients senden bei jeder Aufrufung eine UUID id . Der Server behandelt die ID als Idempotenzschlüssel, während er den Aufruf-Datensatz beibehält: Das erneute Senden derselben Anfrage bringt den bestehenden Aufruf zurück, anstatt den Agenten erneut auszuführen. Die Wiederverwendung einer ID für eine andere Anfrage liefert einen 409 Fehler.

Sitzungen

Klienten können ein session_id senden, um Invocations zu einer einzigen Konversation zu gruppieren. Der Server speichert die Sitzungs-ID separat von input, gibt sie an deinen Handler als context.session_id und führt Aufrufe, die jeweils eine Sitzungs-ID teilen, jeweils nacheinander in der angegebenen Reihenfolge aus. Der Server leitet keine Sitzung aus der Aufruf-ID oder dem Input ab. Ohne Sitzungs-ID erfolgt ein Aufruf ohne Sitzung.

Ausführungsstatus

DurableAgentServer speichert die Anfrage, den Status, die Herzschläge, Ereignisse jeder Invocation und das Ergebnis in einem Runtime Store.

Lokale Entwicklung: agentbricks dev verwendet einen In-Process-Runtime Store. Die Aufruf-API verhält sich genauso, aber der Laufzustand geht verloren, wenn der Prozess stoppt und der Server die unterbrochene Arbeit nicht neu startet.
Bereitgestellte Agents: agentbricks deploy stellt eine dedizierte Datenbank für den Runtime Store jeder Bereitstellung in einem von Azure Databricks verwalteten Lakebase-Projekt bereit und verwendet sie bei einer erneuten Bereitstellung wieder. Du kannst dein eigenes Lakebase-Projekt nicht für den Runtime Store verwenden und erstellst oder bindest es nicht selbst. Ergebnisse und Ereignisse überdauern Worker-Neustarts, und jede Instanz des Agenten kann Status- und Wiederverbindungsanfragen bearbeiten. agentbricks deployments delete entfernt den Runtime Store mit dem Deployment.

Der Runtime Store enthält den Ausführungszustand des Servers. Es ist getrennt von den Sitzungs- und Speichern, die dein Agent für Gesprächshistorie und Langzeitgedächtnis nutzt.

Wiederherstellung nach Absturz

Um Läufe wiederherzustellen, die durch den Absturz oder Neustart eines Workers unterbrochen werden, registrieren Sie einen Recovery-Handler mit @app.recover. Wenn ein eingesetzter Server erkennt, dass die Heartbeats eines Runs ausgeblieben sind, startet er einen Ersatzversuch auf einem verfügbaren Worker und ruft den Wiederherstellungshandler mit der ursprünglichen Eingabe auf.

@app.recover
async def recover(input, context: InvocationContext) -> dict:
    # Resume from the agent's last checkpoint in the session store,
    # or replay the input if that's safe for your agent.
    return await resume_my_agent(input, session_id=context.session_id)

Wenn du keinen Wiederherstellungshandler registrierst, wird die automatische Wiederherstellung deaktiviert und der Server meldet eine Warnung, wenn er startet.

Die Wiederherstellung funktioniert wie folgt:

Wenn die Wiederherstellung beginnt: Jeder Laufversuch sendet alle paar Sekunden einen Heartbeat. Wenn der Herzschlag stoppt, zum Beispiel weil der Worker abstürzt, neu startet oder während einer Neu-Bereitstellung ersetzt wird, erkennt der Server den veralteten Run innerhalb von Sekunden und startet einen Ersatzversuch.
Wenn die Fehlerbehandlung nicht startet: Wenn dein Handler eine Ausnahme auslöst, schlägt der Aufruf fehl und der Server versucht es nicht erneut. Die Wiederherstellung deckt unterbrochene Worker ab, keine Fehler im Agentencode.
Anzahl der Versuche: Der Server begrenzt die Anzahl der Wiederherstellungsversuche nicht. Jeder Ersatzversuch erhöht context.attempt um eins. Um nach einer bestimmten Anzahl von Versuchen aufzuhören, prüfe context.attempt in deinem Wiederherstellungs-Handler und gib einen Fehler aus.
Manuelle Wiederherstellung: Du kannst die Wiederherstellung nicht manuell auslösen. Das erneute Senden einer Anfrage mit derselben Aufruf-ID gibt den bestehenden Aufruf zurück, anstatt einen neuen Versuch zu starten.

Recovery kann deinen Agentencode mehrmals für denselben Aufruf ausführen. Ein unterbrochener Versuch könnte bereits externe Systeme aufgerufen haben, bevor der Ersatzversuch beginnt, also machen Sie diese Aufrufe idempotent.

AgentKit-Bibliothek

DurableAgentServer ist Teil der AgentKit-Bibliothek, databricks_agentkit, die das databricks-agentbricks-Paket enthält. Projekte, die Sie mit agentbricks init erstellen, importieren daraus. Die Bibliothek exportiert folgende Helfer:

Export	Description
`DurableAgentServer`, `InvocationContext`	Der Agent-Server und der Kontext, den er an deine Aufruf- und Wiederherstellungs-Handler weitergibt.
`AgentKitClient`	Ein Client für verwalteten Speicher- und Sessionspeicher. Es erstellt und erhält Stores und stellt die Speicher und Sitzungen der Stores als `Memory`, `MemoryStore`, `MemorySearchResult`, `Session`, `SessionStore` und `SessionItem` Objekte zur Verfügung.
`configure_tracing`, `start_trace`	Richte MLflow-Tracing für den Agenten ein und starte einen Trace um eine Arbeitseinheit.
`workspace_client`, `workspace_headers`	Erstellen Sie ein authentifiziertes Databricks-SDK `WorkspaceClient`oder erhalten Sie Authentifizierungsheader für direkte HTTP-Aufrufe aus der Umgebung des Agenten.
`list_ai_gateway_model_services`	Listen Sie die Modelldienste auf, die der Agent über Unity Gateway aufrufen kann.

Die Bibliothek enthält außerdem Framework-Helfer in databricks_agentkit.langgraph und databricks_agentkit.openai, die die generierten Vorlagen verwenden, um jedes Framework mit dem Session Store zu verbinden. Für die Speicher- und Sitzungs-APIs siehe Managed Agent memory und Managed agent sessions.

Autorisierung des anfragenden Benutzers

Standardmäßig laufen die Tools deines Agenten mit den Berechtigungen des Service Principal der App. Um ein Tool mit den Berechtigungen des Benutzers auszuführen, der die Anfrage gesendet hat, deklarieren Sie die Benutzerautorisierung in agent.toml:

Für ein verwaltetes Tool setzen Sie auth = "user" auf den Tool-Eintrag fest. Die agentbricks tools add Befehle für MCP-Server, Sandboxen und Genie Agents schreiben auth = "user" standardmäßig. Übergeben Sie --auth app, um stattdessen die Identität der App zu verwenden.
Für ein Tool, das du im Code schreibst, deklariere die Anforderung und alle API-Scopes, die Agent Bricks nicht ableiten kann:
```
[auth.user]
required = true
additional_api_scopes = ["sql"]
```

Wenn ein Agent eine Benutzerautorisierung benötigt, DurableAgentServer liest er die Zugangsdaten des Benutzers aus den vertrauenswürdigen Databricks Apps Request-Headern und speichert sie nur für den aktiven Versuch im Speicher. Der Runtime Store speichert die Zugangsdaten nicht. In Ihrem Handler erhalten Sie einen Workspace-Client für den Benutzer von context.request_auth:

@app.invoke
async def invoke(input, context: InvocationContext) -> dict:
    user_client = context.request_auth.client_for("user")
    me = user_client.current_user.me()
    return {"answer": f"Hello, {me.user_name}"}

client_for("app") gibt einen Client zurück, der den Service-Principal der App nutzt. Der Resolver schließt, wenn der Versuch endet, also rufe ihn im Handler auf, anstatt den Client zu speichern. Wenn du den Agent lokal mit agentbricks dev ausführst, verwendet client_for("user") deine lokalen Zugangsdaten.

Wenn Sie deployen, agentbricks deploy fordern Sie die Benutzerscopes von Databricks Apps an, die Ihre Tools benötigen. Um fehlende Scopes zu einer bestehenden App hinzuzufügen, übergeben Sie --allow-user-scope-update. Siehe Konfigurieren der Autorisierung in einer Databricks-App.

Request-User-Aufrufe verwenden dieselben synchronen, Streaming-, Hintergrund- und Reconnection-APIs. Da der Server die Zugangsdaten des Benutzers nicht speichert, kann er eine unterbrochene Request-User-Invocation nicht wiederherstellen. Der Ersatzversuch scheitert mit dem MCP_USER_AUTH_RECOVERY_UNSUPPORTED-Fehler, bevor deine Handler ausgeführt werden.

Benutzerdefinierte Endpunkte hinzufügen

DurableAgentServer ist eine FastAPI-Anwendung. Füge Routen neben der Invocation API hinzu, so wie du sie zu jeder FastAPI-App hinzufügst:

@app.get("/status")
async def status() -> dict:
    return {"ready": True}

Rahmenvorlagen

agentbricks init erzeugt zwei Verzeichnisse:

agent/ enthält deinen Framework-Code: das Modell, Prompts und Tools.
runtime/ enthält den Adapter, der das Framework mit DurableAgentSerververbindet, sowie den Entrypoint, der die Aufruf- und Wiederherstellungshandler des Adapters registriert.

Der Adapter übersetzt jeden Aufruf in einen Aufruf zur Agentenschleife des Frameworks und übersetzt die Ausgabe des Frameworks in Ereignisse und ein Ergebnis. Beide Vorlagen registrieren einen Recovery-Handler. Die LangGraph-Vorlage wird ab dem letzten Checkpoint im Sitzungsspeicher fortgesetzt, und die OpenAI Agents SDK-Vorlage spielt die Anfrage in derselben Sitzung erneut ab. Um einen vorhandenen Agenten einzubinden, fügen Sie einen Adapter und einen DurableAgentServer Entrypoint hinzu und setzen Sie server = "agentbricks" im Abschnitt [agent] von agent.toml.

Limitations

Du kannst den Agentenserver einer bestehenden Bereitstellung nicht ändern. Um zwischen DurableAgentServer und deinem eigenen Server zu wechseln, erstelle ein neues Projekt mit der gewünschten agentbricks init --server-Option und stelle es unter einem neuen Namen bereit.
Das Ändern des Feldes server in agent.toml konvertiert den vorhandenen Servercode nicht zu DurableAgentServer.
Das Anfordern der Benutzerautorisierung erfordert server = "agentbricks".

Weitere Ressourcen

Feedback

War diese Seite hilfreich?

Zuletzt aktualisiert um 2026-10-08