Agent Server

Een agentserver is de bibliotheek die je agentcode omzet in een service. Het plaatst de agentlus in een HTTP-server, definieert de API die clients aanroepen om de agent te laten draaien, beheert clientverbindingen en bepaalt wat er gebeurt wanneer een run wordt onderbroken. De agentserver draait op de agent-runtime. Om te leren hoe de lagen in elkaar passen, zie Deploy agents on Azure Databricks.

Agent servers on Azure Databricks

Azure Databricks biedt drie agent-servers. Voor nieuwe agenten beveelt Databricks DurableAgentServer aan.

Agent server Package Client-API Duurzame uitvoering Wordt gebruikt door
DurableAgentServer (aanbevolen) databricks_agentkit, in het databricks-agentbricks pakket Invocation API op /api/invocations: synchrone, streaming- en achtergrondtaken, met herverbinding van streams Een runtime store die agentbricks deploy inricht, plus crashherstel via een recovery handler Projecten die je maakt met de Agent Bricks CLI
LongRunningAgentServer (verouderd) databricks_ai_bridge.long_running, in het databricks-ai-bridge[agent-server] pakket OpenAI Responses API op /responses, met achtergrondruns en hervatting van de stream Uitvoerstatus in een Lakebase-database die je zelf instelt. Na een crash gaat een nieuwe poging verder met de run vanuit het eventlogboek van de onderbroken poging. De agent-openai-advanced en agent-langgraph-advancedapp-sjablonen
MLflow AgentServer (verouderd) mlflow.genai.agent_server, in het mlflow pakket OpenAI Responses API op /responses: synchrone en streaming uitvoeringen None De basis-app-sjablonen, zoals agent-openai-agents-sdk

LongRunningAgentServer breidt de MLflow AgentServer uit, en beide dienen agenten die de MLflow ResponsesAgent-interface implementeren. Om een agent te deployen en te onderhouden die een daarvan gebruikt, zie Agents uitvoeren op Databricks Apps met de legacy agent server. Om een agent op een van deze servers te bevragen, zie Agents die zijn geïmplementeerd op Azure Databricks opvragen.

DurableAgentServer

DurableAgentServer is de Agent Bricks-agentserver. Het verpakt je agentlus in een HTTP-server die de aanroep-API aanbiedt, elke run volgt en runs herstelt die door een crash of herstart zijn onderbroken. Agenten die je aanmaakt met de Agent Bricks CLI gebruiken standaard DurableAgentServer.

DurableAgentServer biedt:

  • Eén API voor elke verzoekmodus: synchrone, streaming- en achtergrondaanroepen, plus streamherverbinding, allemaal bediend door dezelfde handler.
  • Idempotente aanroepen: Een door de client gegenereerde aanroep-ID zorgt ervoor dat een hernieuwd verzoek geen dubbele uitvoering start.
  • Geordende sessies: Aanroepen in dezelfde sessie worden één voor één uitgevoerd, in volgorde.
  • Persistente run-status: Wanneer deze is geïmplementeerd, overleven runstatus, gebeurtenissen en resultaten de herstarts van de worker.
  • Crashherstel: De server detecteert onderbroken runs en start een vervangingspoging.
  • Autorisatie van de verzoekgebruiker: Tools kunnen handelen met de rechten van de gebruiker die het verzoek heeft verzonden.
  • Aangepaste endpoints: DurableAgentServer is een FastAPI-applicatie, dus je kunt je eigen routes toevoegen.

Requirements

DurableAgentServer heeft de volgende vereisten:

  • Python 3.10 en hoger.
  • Het databricks-agentbricks pakket, inclusief de databricks_agentkit bibliotheek. Projecten die je maakt met agentbricks init declareren het als afhankelijkheid.

Uw agent registreren

Wanneer je een project maakt met agentbricks init, doet de CLI dit voor je. De gegenereerde runtime/main.py maakt de server aan en registreert de aanroep- en herstelhandlers van de template, dus je bewerkt alleen de agentcode in agent/. Volg de stappen in deze sectie om een bestaande agent te gebruiken of om je eigen handler te schrijven.

Maak een DurableAgentServer aan en registreer een asynchrone aanroepingshandler met @app.invoke. De handler ontvangt de input van het verzoek en een aanroepingscontext, en geeft een JSON-serialiseerbaar resultaat terug. Publiceer voortgang als gebeurtenissen met 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}

Je kunt één aanroepingshandler registreren, en de server start niet zonder een aanroepingshandler. De handler bedient elke verzoekmodus: de client kiest of hij op het resultaat wacht, events streamt of het verzoek op de achtergrond laat uitvoeren.

Om de server lokaal te draaien, start je hem met agentbricks dev. Projecten die je met agentbricks init maakt, bevatten een entrypoint dat de server met Uvicorn draait, en een app.yaml-bestand dat hetzelfde entrypoint start nadat je het hebt gedeployed.

Aanroepcontext

Het tweede argument van de handler is een InvocationContext:

Attribute Description
invocation_id De ID die de client heeft gestuurd voor deze aanroeping.
session_id De sessie waar de aanroep bij hoort, of None als de client er geen heeft gestuurd.
attempt Het pogingnummer. De eerste poging is 1.
is_recovery True wanneer de recovery handler een vervangingspoging uitvoert.
emit(event) Slaat een JSON-event op, levert het aan streamingclients en geeft de positie van het event in de stream terug.
request_auth De request-user credential resolver, wanneer de agent request-user-autorisatie vereist. Anders None.

Invocation API

DurableAgentServer bedient de aanroep-API op /api/invocations:

  • POST /api/invocations start een aanroep. Standaard wacht het verzoek op het resultaat. Stel stream in om gebeurtenissen als Server-Sent Events te ontvangen, of stel background in om direct terug te keren met een status-URL.
  • GET /api/invocations/<id> geeft de status van een aanroeping terug en, nadat deze is voltooid, de output ervan.
  • GET /api/invocations/<id>/events?after=<event-id> streamt opgeslagen events, zodat een client na een verbroken verbinding opnieuw kan verbinden.

Voor verzoekvelden, voorbeelden en responsformaten, zie Query agents die zijn uitgerold op Azure Databricks.

Idempotentie

Clients sturen bij elke aanroep een UUID id . De server behandelt de ID als een idempotentiesleutel terwijl hij het aanroeprecord behoudt: het opnieuw verzenden van hetzelfde verzoek geeft de bestaande aanroep terug in plaats van de agent opnieuw uit te voeren. Het hergebruiken van een ID voor een ander verzoek levert een 409 foutmelding op.

Sessions

Klanten kunnen een session_id verzenden om groepsaanroepen in één gesprek te bundelen. De server slaat de sessie-ID apart op van input, geeft deze door aan je handler als context.session_id, en voert aanroepen met dezelfde sessie-ID één voor één uit, in volgorde. De server leidt geen sessie af uit de invocation-ID of de input. Zonder sessie-ID is een aanroeping sessieloos.

Uitvoeringsstatus

DurableAgentServer slaat van elke invocation het verzoek, de status, hartslagen, gebeurtenissen en het resultaat op in een Runtime Store.

  • Lokale ontwikkeling: agentbricks dev gebruikt een in-process Runtime Store. De aanroep-API gedraagt zich op dezelfde manier, maar de run state gaat verloren wanneer het proces stopt en de server het onderbroken werk niet opnieuw start.
  • Geïmplementeerde agents: agentbricks deploy maakt een toegewezen database aan voor de Runtime Store van elke deployment in een door Azure Databricks beheerd Lakebase-project, en hergebruikt deze bij opnieuw implementeren. Je kunt je eigen Lakebase-project niet gebruiken voor de Runtime Store, en hoef je het niet zelf aan te maken of te koppelen. Resultaten en gebeurtenissen overleven herstarts van de werker, en elke instantie van de agent kan status- en herverbindingsverzoeken afhandelen. agentbricks deployments delete verwijdert de Runtime Store met de deployment.

De Runtime Store bevat de uitvoeringsstatus van de server. Het is gescheiden van de sessie- en geheugenopslag die je agent gebruikt voor gespreksgeschiedenis en langetermijngeheugen.

Crashherstel

Om runs te herstellen die door een crash of herstart van een worker worden onderbroken, registreer je een recoveryhandler met @app.recover. Wanneer een gedeployede server detecteert dat de heartbeat-signalen van een run zijn gestopt, start hij een vervangende poging op een beschikbare worker en roept de recovery handler aan met de oorspronkelijke input.

@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)

Als je geen herstelhandler registreert, wordt automatisch herstel uitgeschakeld en geeft de server een waarschuwing wanneer het start.

Het herstel werkt als volgt:

  • Wanneer het herstel begint: Elke actieve poging stuurt elke paar seconden een hartslag. Als de hartslagen stoppen, bijvoorbeeld omdat de worker crasht, opnieuw opstart of wordt vervangen tijdens een heruitrol, detecteert de server de verouderde run binnen enkele seconden en start een vervangingspoging.
  • Wanneer recovery niet start: Als je handler een uitzondering genereert, mislukt de aanroep en probeert de server het niet opnieuw. Herstel dekt onderbroken workers, geen fouten in de code van je agent.
  • Aantal pogingen: De server beperkt het aantal herstelpogingen niet. Elke vervangingspoging verhoogt context.attempt met één. Om na een bepaald aantal pogingen te stoppen, controleer context.attempt in je herstelhandler en geef een foutmelding.
  • Handmatig herstel: Je kunt herstel niet handmatig activeren. Het opnieuw verzenden van een verzoek met dezelfde aanroep-ID geeft de bestaande aanroep terug in plaats van een nieuwe poging te starten.

Recovery kan je agentcode meer dan eens laten uitvoeren voor dezelfde aanroep. Een onderbroken poging kan al externe systemen hebben aangeroepen voordat de vervangingspoging begint, dus maak die oproepen idempotent.

AgentKit-bibliotheek

DurableAgentServer maakt deel uit van de AgentKit-bibliotheek, databricks_agentkit, die deel uitmaakt van het databricks-agentbricks-pakket. Projecten die je maakt door uit agentbricks init te importeren. De bibliotheek exporteert de volgende helpers:

Exporteren Description
DurableAgentServer, InvocationContext De agentserver en de context die deze doorgeeft aan je invoke- en recovery-handlers.
AgentKitClient Een client voor beheerd geheugen en sessieopslag. Het creëert en haalt stores op, en stelt de geheugens en sessies van de stores bloot als Memory, MemoryStore, MemorySearchResult, Session, SessionStore, , en SessionItem objecten.
configure_tracing, start_trace Stel MLflow-tracering op voor de agent en start een trace rond een eenheid van werk.
workspace_client, workspace_headers Maak een geauthenticeerde Databricks SDK WorkspaceClientaan, of haal authenticatieheaders voor directe HTTP-aanroepen vanaf de omgeving van de agent.
list_ai_gateway_model_services Vermeld de modelservices die de agent via Unity Gateway kan oproepen.

De bibliotheek bevat ook framework-helpers in databricks_agentkit.langgraph en databricks_agentkit.openai, die door de gegenereerde sjablonen worden gebruikt om elk framework te verbinden met de sessie-opslag. Voor de geheugen- en sessie-API's, zie Managed agent memory en Managed agent sessions.

Gebruikersautorisatie aanvragen

Standaard draaien de tools van je agent met de rechten van de serviceprincipal van de app. Om een tool met de rechten van de gebruiker die het verzoek heeft verzonden uit te voeren, geef gebruikersautorisatie op in agent.toml:

  • Voor een beheerde tool, stel auth = "user" in op de toolvermelding. De agentbricks tools add commando's voor MCP-servers, sandboxes en Genie Agents schrijven auth = "user" standaard. Geef --auth app door om in plaats daarvan de identiteit van de app te gebruiken.

  • Voor een tool die je in code schrijft, declareer de vereisten en eventuele API-scopes die Agent Bricks niet kan afleiden:

    [auth.user]
required = true
additional_api_scopes = ["sql"]

Wanneer een agent gebruikersautorisatie vereist, DurableAgentServer leest hij de inloggegevens van de gebruiker uit de vertrouwde Databricks Apps request-headers en bewaart deze alleen in het geheugen voor de actieve poging. De Runtime Store slaat de credential niet op. Haal in je handler een workspace-client voor de gebruiker op van 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") Geeft een client terug die gebruikmaakt van de service-principal van de app. De resolver sluit wanneer de poging eindigt, dus roep het binnen de handler aan in plaats van de client op te slaan. Wanneer je de agent lokaal draait met agentbricks dev, gebruikt client_for("user") je lokale inloggegevens.

Wanneer je deployeert, worden met agentbricks deploy de gebruikersscopes van Databricks Apps aangevraagd die je tools nodig hebben. Om ontbrekende scopes aan een bestaande app toe te voegen, geef --allow-user-scope-update door. Zie Autorisatie configureren in een Databricks-app.

Request-user aanroepen gebruiken dezelfde synchrone, streaming-, achtergrond- en herverbindings-API's. Omdat de server de inlogreferentie van de gebruiker niet opslaat, kan hij een onderbroken request-user aanroep niet herstellen. De vervangingspoging mislukt door de MCP_USER_AUTH_RECOVERY_UNSUPPORTED fout voordat je handlers worden uitgevoerd.

Voeg aangepaste eindpunten toe

DurableAgentServer is een FastAPI-applicatie. Voeg routes toe naast de aanroep-API op dezelfde manier als je ze toevoegt aan elke FastAPI-app:

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

Raamwerksjablonen

agentbricks init genereert twee directories:

  • agent/ Bevat je frameworkcode: het model, prompts en tools.
  • runtime/ bevat de adapter die het framework verbindt met DurableAgentServer, en het entrypoint dat de invoke- en recovery-handlers van de adapter registreert.

De adapter vertaalt elke aanroep in een aanroep naar de agent-lus van het framework, en vertaalt de output van het framework in gebeurtenissen en een resultaat. Beide templates registreren een recovery handler. De LangGraph-sjabloon wordt hervat vanaf het laatste checkpoint in de sessieopslag, en de OpenAI Agents SDK-sjabloon speelt het verzoek opnieuw af in dezelfde sessie. Om een bestaande agent toe te voegen, voeg je een adapter en een DurableAgentServer entrypoint toe, en stel je server = "agentbricks" in de [agent] sectie van agent.toml in.

Limitations

  • Je kunt de agentserver van een bestaande implementatie niet veranderen. Om te wisselen tussen DurableAgentServer en je eigen server, maak je een nieuw project aan met de agentbricks init --server optie die je wilt, en rol je het uit onder een nieuwe naam.
  • Het wijzigen van het server veld in agent.toml zet bestaande servercode niet om in DurableAgentServer.
  • Autorisatie voor de aanvraaggebruiker vereist server = "agentbricks".

Aanvullende bronnen

  • Laatst bijgewerkt om