Agent Server

En agentserver är biblioteket som omvandlar din agentkod till en tjänst. Den omsluter agentloopen i en HTTP-server, definierar API:et som klienterna anropar för att köra agenten, hanterar klientanslutningar och avgör vad som händer när en körning avbryts. Agent server körs på agent runtime. För att lära dig hur lagren hänger ihop, se Distribuera agenter på Azure Databricks.

Agentservrar på Azure Databricks

Azure Databricks tillhandahåller tre agentservrar. För nya agenter rekommenderar Databricks DurableAgentServer.

LongRunningAgentServer utökar MLflow AgentServer, och båda stöder agenter som implementerar MLflow-gränssnittet ResponsesAgent. För att distribuera och underhålla en agent som använder en av dem, se Kör agenter på Databricks Apps med den äldre agentservern. För att göra en fråga mot en agent på någon av dessa servrar, se Query agents deployed on Azure Databricks.

DurableAgentServer

DurableAgentServer är agentservern för Agent Bricks. Den omsluter din agentloop i en HTTP-server som betjänar anrops-API:et, spårar varje körning och återupptar körningar som en krasch eller omstart avbryter. Agenter som du skapar med Agent Bricks CLI använder DurableAgentServer som standard.

DurableAgentServer innehåller:

• Ett API för varje förfrågningsläge: synkrona, strömmande och bakgrundsanrop, plus återanslutning av strömmen, allt hanterat av samma hanterare.
• Idempotenta anrop: Ett klientgenererat invokerings-ID säkerställer att en begäran som försöks igen inte startar en duplicerad körning.
• Ordnade sessioner: Invocations i samma session körs en i taget, i ordning.
• Beständigt körningstillstånd: När den har distribuerats bevaras körningsstatus, händelser och resultat vid omstarter av arbetare.
• Kraschåterställning: Servern upptäcker avbrutna körningar och startar ett ersättningsförsök.
• Den begärande användarens behörighet: Verktyg kan agera med behörigheterna för den användare som skickade förfrågan.
• Anpassade endpoints: DurableAgentServer är en FastAPI-applikation, så du kan lägga till egna rutter.

Kravspecifikation

DurableAgentServer har följande krav:

• Python 3.10 och uppåt.
• Paketet databricks-agentbricks, som innehåller biblioteket databricks_agentkit. Projekt som du skapar med agentbricks init har detta deklarerat som ett beroende.

Registrera din agent

När du skapar ett projekt med agentbricks init, gör CLI detta åt dig. Den genererade runtime/main.py-filen skapar servern och registrerar mallens anrops- och återställningshanterare, så du redigerar bara agentkoden i agent/. Följ stegen i detta avsnitt för att använda en befintlig agent eller skriva din egen hanterare.

Skapa en DurableAgentServer och registrera en asynkron anropshanterare med @app.invoke. Hanteraren tar emot förfrågans input och en anropskontext, och returnerar ett JSON-serialiserbart resultat. Publicera statusuppdateringar som händelser med 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 kan registrera en enda anropshanterare, och servern startar inte utan en. Hanteraren hanterar varje förfrågningsläge: klienten väljer om den vill vänta på resultatet, strömma händelser eller köra i bakgrunden.

För att köra servern lokalt, starta den med agentbricks dev. Projekt som du skapar med agentbricks init inkluderar en entrypoint som kör servern med Uvicorn, och en app.yaml-fil som startar samma entrypoint efter att du distribuerat.

Anropskontext

Handlarens andra argument är ett InvocationContext:

Anrops-API

DurableAgentServer betjänar anrops-API:et vid /api/invocations:

• POST /api/invocations startar ett anrop. Som standard väntar förfrågan på resultatet. Ställ stream in att ta emot händelser som Server-Sent-händelser, eller background för att returnera omedelbart med en status-URL.
• GET /api/invocations/<id> returnerar en anrops status och, efter att den är klar, dess utdata.
• GET /api/invocations/<id>/events?after=<event-id> strömmar tidigare lagrade händelser, så att en klient kan återansluta efter en avbruten anslutning.

För förfrågningsfält, exempel och svarsformat, se Fråga agenter som distribuerats på Azure Databricks.

Idempotens

Klienterna skickar en UUID id med varje anrop. Servern behandlar ID:t som en idempotensnyckel medan den behåller anropsposten: att skicka samma begäran igen returnerar det befintliga anropet istället för att köra agenten igen. Att återanvända ett ID för en annan förfrågan ger ett 409 felmeddelande.

Sessions

Klienter kan skicka en session_id för att gruppera invokationer i en och samma konversation. Servern lagrar sessions-ID:t separat från input, skickar det till din handler som context.session_id, och kör anrop som delar ett sessions-ID ett i taget, i ordning. Servern härleder inte en session från anrops-ID eller indata. Utan ett sessions-ID är anropet sessionslöst.

Körningstillstånd

DurableAgentServer lagrar varje anrops begäran, status, hjärtslag, händelser och resultat i en Runtime Store.

• Lokal utveckling: agentbricks dev använder en Runtime Store i processen. Anrops-API:et beter sig på samma sätt, men körningstillståndet förloras när processen stannar, och servern startar inte om avbrutet arbete.
• Distribuerade agenter: agentbricks deploy etablerar en dedikerad databas för varje distributions Runtime Store i ett Azure Databricks-hanterat Lakebase-projekt och återanvänder den när du distribuerar om. Du kan inte använda ditt eget Lakebase-projekt för Runtime Store, och du skapar eller binder det inte själv. Resultat och händelser överlever omstarter av arbetare, och varje instans av agenten kan hantera status- och återanslutningsförfrågningar. agentbricks deployments delete tar bort Runtime Store vid distributionen.

Runtime Store håller serverns exekveringstillstånd. Det är separat från sessions- och minneslagren som din agent använder för samtalshistorik och långtidsminne.

Återställning efter krasch

För att återställa körningar som avbryts när en arbetare kraschar eller startas om, registrera en återställningshanterare med @app.recover. När en driftsatt server upptäcker att hjärtslagen för en körning har upphört, startar den ett ersättningsförsök på en tillgänglig arbetare och anropar återställningshanteraren med den ursprungliga inmatningen.

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

Om du inte registrerar en återställningshanterare stängs automatisk återställning av och servern loggar en varning när den startar.

Återhämtningen fungerar enligt följande:

• När återställningen startar: Varje körningsförsök skickar en heartbeat med några sekunders mellanrum. Om heartbeat-signalerna stannar, till exempel för att arbetaren kraschar, startar om eller byts ut under en omdistribution, upptäcker servern den föråldrade körningen inom några sekunder och startar ett ersättningsförsök.
• När återhämtningen inte startar: Om din hanterare utlöser ett undantag misslyckas anropet och servern försöker inte igen. Återhämtning täcker avbrutna worker-processer, inte fel i din agentkod.
• Antal försök: Servern begränsar inte antalet återställningsförsök. Varje försök att byta ut ökar context.attempt med en. För att sluta efter ett visst antal försök, kontrollera context.attempt i din återställningshanterare och utlös ett fel.
• Manuell återställning: Du kan inte trigga återställning manuellt. Att skicka om en begäran med samma anrops-ID returnerar det befintliga anropet istället för att starta ett nytt försök.

Recovery kan köra din agentkod mer än en gång för samma anrop. Ett avbrutet försök kan redan ha anropat externa system innan ersättningsförsöket startar, så gör dessa anrop idempotenta.

AgentKit-bibliotek

DurableAgentServer är en del av AgentKit-biblioteket, databricks_agentkitsom paketet databricks-agentbricks inkluderar. Projekt som du skapar med agentbricks init importeras från den. Biblioteket exporterar följande hjälpfunktioner:

Biblioteket inkluderar också ramverkshjälpare i databricks_agentkit.langgraph och databricks_agentkit.openai, som de genererade mallarna använder för att koppla varje ramverk till sessionslagret. För minnes- och sessions-API:er, se Managed agent memory och Managed agent sessions.

Begär användarauktorisering

Som standard körs din agents verktyg med behörigheter från appens service principal. För att köra ett verktyg med behörigheterna för användaren som skickade förfrågan, deklarera användarautorisering i agent.toml:

• För ett hanterat verktyg, ange auth = "user" på verktygsposten. Kommandon agentbricks tools add för MCP-servrar, sandlådor och Genie Agents skriver till auth = "user" som standard. Skicka --auth app för att använda appens identitet istället.

• För ett verktyg som du skriver i kod, deklarera kravet och eventuella API-scopes som Agent Bricks inte kan härleda:

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

När en agent kräver användarauktorisation DurableAgentServer läser användarens inloggningsuppgifter från de betrodda Databricks Apps request-headers och behåller dem i minnet endast för det aktiva försöket. Runtime Store lagrar inte inloggningsuppgiften. I din handler, hämta en workspace-klient för användaren från 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") returnerar en klient som använder appens tjänsthuvudnamn. Resolvern stängs när försöket är slut, så kalla den inne i hanteraren istället för att lagra klienten. När du kör agenten lokalt med agentbricks dev använder client_for("user") dina lokala inloggningsuppgifter.

När du distribuerar begär agentbricks deploy de användarscopes för Databricks Apps som dina verktyg behöver. För att lägga till saknade omfång i en befintlig app, skicka med --allow-user-scope-update. Se Konfigurera auktorisering i en Databricks-app.

Request-user-anrop använder samma synkrona, strömnings-, bakgrunds- och återanslutnings-API:er. Eftersom servern inte lagrar användarens inloggningsuppgifter kan den inte återställa ett avbrutet användaranrop för en begäran. Ersättningsförsöket misslyckas med felet MCP_USER_AUTH_RECOVERY_UNSUPPORTED innan dina hanterare körs.

Lägg till anpassade endpoints

DurableAgentServer är en FastAPI-applikation. Lägg till rutter vid sidan av anrops-API:et på samma sätt som du lägger till dem i vilken FastAPI-app som helst:

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

Ramverksmallar

agentbricks init genererar två kataloger:

• agent/ innehåller din ramverkskod: modellen, promptarna och verktygen.
• runtime/ innehåller adaptern som kopplar ramverket till DurableAgentServer, och ingångspunkten som registrerar adapterns anrops- och återställningshanterare.

Adaptern översätter varje anrop till ett anrop till ramverkets agentloop och översätter ramverkets utdata till händelser och ett resultat. Båda mallarna registrerar en återställningshanterare. LangGraph-mallen återupptas från sin senaste kontrollpunkt i sessionslagret, och OpenAI Agents SDK-mallen upprepar begäran i samma session. För att använda en befintlig agent, lägg till en adapter och en DurableAgentServer entrypoint, och ställ in server = "agentbricks" i avsnittet [agent] i agent.toml.

Limitations

• Du kan inte ändra agentservern för en befintlig driftsättning. För att växla mellan DurableAgentServer och din egen server, skapa ett nytt projekt med det agentbricks init --server alternativ du vill ha och distribuera det under ett nytt namn.
• Att ändra server fältet i agent.toml omvandlar inte befintlig serverkod till DurableAgentServer.
• Begäran om användarautorisering kräver server = "agentbricks".

Ytterligare resurser

• Agent Runtime
• Frågeagenter distribuerade på Azure Databricks
• Agent Bricks CLI