ügynökszerver

Az agent server az a könyvtár, amely az ügynökkódot szolgáltatássá alakítja. Az ügynök ciklusát egy HTTP-szerverbe csomagolja, meghatározza az API-t, amelyet az ügyfelek az ügynök futtatásához hívnak, kezeli az ügyfélkapcsolatokat, és meghatározza, mi történik, ha egy futást megszakítanak. Az ügynökszerver az ügynök-futtatókörnyezeten fut. A rétegek összeilleszkedésének megismeréséhez lásd: Ügynökök üzembe helyezése az Azure Databricksben.

Új ügynökök esetén a Databricks azt az agentkiszolgálót ajánlja, amelyet az AgentKit biztosít, és amelyet ez az oldal is leír. Az örökölt ügynökkiszolgálókkal való összehasonlításhoz lásd: Ügynökkiszolgálók összehasonlítása az Azure Databricksben.

Requirements

  • Python 3.10 és annál magasabb.
  • A databricks-agentbricks csomag, beleértve az AgentKitet. Azok a projektek, amelyeket a(z) agentbricks init használatával hozol létre, függőségként deklarálják azt.

AgentKit

Az AgentKit az Agent Bricks könyvtára, amely az Agent Runtime-on futó ügynökök építésére szolgál. Biztosítja az ügynökkiszolgálót, amely kiszolgálja az ügynököt, valamint a klienseket és segítőket az ügynök memóriájához, ügynök-munkamenetekhez, nyomon követéshez és hitelesítéshez. Az Agent Bricks CLI-val létrehozott projektek alapértelmezetten az AgentKit-et használják.

agentszerver

Az AgentKit az ügynök szerverét az DurableAgentServer osztályon keresztül biztosítja. Az agent server HTTP-szerverben futtatja az ügynök hurkot, amely az invocation API-t szolgálja, nyomon követi az egyes futásokat, és helyreállítja azokat a futásokat, amelyeket egy összeomlás vagy újraindítás megszakít. A következő lehetőségeket biztosítja:

  • Minden kérésmódhoz egy API: szinkron, streaminges és háttérhívások, valamint stream újrakapcsolódás, amelyeket ugyanaz a kezelő szolgál ki.
  • Idempotens hívások: Egy kliens által generált hívásazonosító biztosítja, hogy egy újrapróbált kérés ne indítson el duplikált végrehajtást.
  • Rendezett munkamenetek: A hívások ugyanabban a munkamenetben egyenként, sorrendben futnak.
  • Állandó futási állapot: Telepítéskor a futtatás státusza, az események és az eredmények túlélik a feldolgozó újraindításait.
  • Helyreállítás összeomlás után: A szerver észleli a megszakított futásokat, és helyreállítási kísérletet indít.
  • A kérést küldő felhasználó jogosultsága: Az eszközök a kérést küldő felhasználó jogosultságaival működhetnek.
  • Egyedi végpontok: Az ügynökszerver egy FastAPI-alkalmazás, így saját végpontokat adhatsz hozzá.

Mit tartalmaz az AgentKit.

Az AgentKit a databricks_agentkit Python könyvtár. Exportálja a következőket:

Export Description
DurableAgentServer, InvocationContext Az ügynök szerver és a kontextus, amelyet az invoke és recovery kezelőinek továbbít.
AgentKitClient Kliens ügynökmemória- és ügynöksession-tárolókhoz. Létrehoz és lekér tárolókat, és a tárolók memóriáit és munkameneteit Memory, MemoryStore, MemorySearchResult, SessionStore, Session és SessionItem objektumokként elérhetővé teszi.
configure_tracing, start_trace Állítsd be az MLflow követést az agent számára, és indítsd el a nyomkövetést egy munkaegység körül.
workspace_client, workspace_headers Hozz létre egy hitelesített Databricks SDK-t WorkspaceClient, vagy szerezz hitelesítési fejléceket közvetlen HTTP hívásokhoz az ügynök környezetéből.
list_ai_gateway_model_services Sorold fel azokat a modellszolgáltatásokat, amelyeket az ügynök a Unity Gateway-en keresztül hívhat.

A könyvtár a databricks_agentkit.langgraph és databricks_agentkit.openai keretrendszer-segítőit is tartalmazza, amelyeket a generált sablonok arra használnak, hogy az egyes keretrendszereket a munkamenettárhoz kapcsolják. A memória- és munkamenet-API-król lásd: Ügynök memória és Ügynökmunkamenetek.

Regisztrálja az agentet

Ha a(z) agentbricks init használatával hozol létre egy projektet, a CLI ezt megteszi helyetted. A generált runtime/main.py létrehozza a szervert, és regisztrálja a sablon meghívási és helyreállítási kezelőit, így csak az ügynökkódot szerkeszted a(z) agent/ fájlban. Kövesd az ebben a szakaszban szereplő lépéseket, hogy meglévő agentet hozzáadj, vagy saját handlert írj.

Hozz létre egy DurableAgentServer-t, és regisztrálj egy aszinkron invocation handler-t @app.invoke-vel. A kezelő megkapja a kérés input-ját és a meghívási kontextust, majd visszaadja a JSON-szerializálható eredményt. Tedd közzé az előrehaladást eseményként.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}

Regisztrálhatsz egy invocation handlert, és a szerver nem indul el nélküle. A kezelő minden kérési módot kiszolgál: az ügyfél eldönti, hogy megvárja-e az eredményt, streameli-e az eseményeket, vagy a háttérben futtatja.

A szerver helyi futtatásához indítsd el a(z) agentbricks dev paranccsal. Azok a projektek, amelyeket a(z) agentbricks init használatával hoz létre, tartalmaznak egy belépőpontot, amely az Uvicornnal futtatja a szervert, valamint egy app.yaml fájlt, amely ugyanazt a belépési pontot indítja el a telepítés után.

Meghívási környezet

A kezelő második argumentuma egy InvocationContext:

Attribute Description
invocation_id Az azonosító, amit az ügyfél küldött ehhez a meghíváshoz.
session_id Az a munkamenet, amelyhez az invocation tartozik, vagy None, ha az ügyfél nem küldött egyet.
attempt A próbálkozás száma. Az első próbálkozás a következő: 1
is_recovery True amikor a helyreállítási kezelő cserekísérletet futtat
emit(event) Tárolja a JSON eseményt, továbbítja a streaming klienseknek, és visszaadja az esemény helyét a streamben.
request_auth A kérésfelhasználói hitelesítés feloldó modulja, amikor az ügynök kérésfelhasználói hitelesítést igényel. Ellenkező esetben None.

Invocation API

DurableAgentServer a(z) /api/invocations helyen szolgálja ki a meghívási API-t:

  • POST /api/invocations indít egy invokációt. Alapértelmezés szerint a kérés vár az eredményre. Állítsd stream úgy, hogy az eseményeket Server-Sent Eventsként fogadja, vagy background azonnal visszatérjen egy állapot-URL-lel.
  • GET /api/invocations/<id> visszaadja egy hívás állapotát, és miután a hívás befejeződött, a kimenetét is.
  • GET /api/invocations/<id>/events?after=<event-id> közvetíti a tárolt eseményeket, így a kliens újra csatlakozhat egy megszakadt kapcsolat után.

A kérésmezőket, példákat és válaszformátumokat lásd itt: Az Azure Databricksben üzembe helyezett lekérdezési ügynökök.

Idempotencia

Az ügyfelek minden invokációval küldenek egy UUID-t id. A szerver az ID-t idempotenciakulcsként kezeli, miközben megőrzi a hívási rekordot: ugyanazon kérés újbóli elküldése a meglévő hívási rekordot adja vissza ahelyett, hogy újra futtatná az ügynököt. Egy azonosító másik kéréshez való újrafelhasználása 409 hibát ad vissza.

Sessions

Az ügyfelek küldhetnek egy session_id elemet, hogy az invokációkat egy beszélgetésbe csoportosítsák. A szerver a session ID-t a(z) input elemétől külön tárolja, átadja azt a kezelőnek context.session_id néven, és az azonos session ID-val rendelkező invokációkat sorrendben, egyszerre egyet futtatja. A szerver nem következteti a munkamenetet sem az invocation ID-ből, sem a bemenetből. Sessionazonosító nélkül a meghívás munkamenet nélküli.

Futási állapot

DurableAgentServer minden egyes invocation kérését, állapotát, heartbeatjeit, eseményeit és eredményét a Runtime Store-ban tárolja.

  • Helyi fejlesztés: agentbricks dev folyamaton belüli Runtime Store-t használ. Az invocation API ugyanígy viselkedik, de a futtatási állapot elveszik, amikor a folyamat leáll, és a szerver nem indítja újra a megszakított munkát.
  • Telepített ügynökök: agentbricks deploy dedikált adatbázist biztosít minden telepítés Runtime Store-jához egy Azure Databricks által kezelt Lakebase projektben, és újrahasznosítja azt újratelepítéskor. Nem használhatod a saját Lakebase projektedet a Runtime Store-hoz, és nem te hozod létre vagy csatolod magad. Az eredmények és események túlélik a worker újraindításait, és az ügynök bármely példánya kezelheti a státusz- és újracsatlakozási kéréseket. agentbricks deployments delete eltávolítja a Runtime Store-t a telepítéssel együtt.

A Runtime Store tárolja a szerver végrehajtási állapotát. Ez különálló a beszélgetési előzményekhez és hosszú távú memóriához használt munkamenet- és memóriatárolóktól.

Összeomlás utáni helyreállítás

Ahhoz, hogy helyreállítsuk azokat a futásokat, amelyeket egy feldolgozó összeomlása vagy újraindítása megszakít, regisztráljunk egy helyreállítási kezelőt a @app.recover-val. Amikor egy telepített szerver észleli, hogy a futás heartbeatjei leálltak, egy elérhető workerön helyettesítési kísérletet indít, és az eredeti bemenettel hívja a helyreállítási kezelőt.

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

Ha nem regisztrálsz egy helyreállítási kezelőt, az automatikus helyreállítás ki van kapcsolva, és a szerver figyelmeztetést naplóz az indításkor.

A helyreállítás a következőképpen működik:

  • Amikor a helyreállítás elkezdődik: Minden futó kísérlet néhány másodpercenként életjelet küld. Ha a heartbeat-ek leállnak, például mert a worker összeomlik, újraindul vagy lecserélik egy újratelepítés során, a szerver másodperceken belül észleli a beragadt futást, és helyettesítési kísérletet indít.
  • Amikor a helyreállítás nem indul el: Ha a kezelő kivételt jelez, a hívás sikertelen lesz, és a szerver nem próbálja újra. A helyreállítás a megszakított workerfolyamatokat fedi, nem az agent kódjában lévő hibákat.
  • A próbálkozások száma: A szerver nem korlátozza a helyreállítási kísérletek számát. Minden cserekísérlet eggyel növeli a(z) context.attempt értékét. A folyamat több próbálkozás utáni leállításához ellenőrizd a(z) context.attempt elemet a helyreállításkezelőben, és jelezz hibát.
  • Kézi helyreállítás: Nem lehet manuálisan elindítani a helyreállítást. Ha ugyanazzal az invokációazonosítóval újra küld egy kérést, akkor a meglévő invokáció jelenik meg, ahelyett, hogy új próbálkozás indulna.

A helyreállítás több alkalommal is futtathatja az ügynök kódját ugyanazon hívás esetén. Egy megszakított próbálkozás már hívhatott külső rendszereket, mielőtt a pótlólagos próbálkozás elkezdődik, ezért tedd ezeket a hívásokat idempotenssé.

Felhasználó-hitelesítés kérése

Alapértelmezés szerint az ügynök eszközei az alkalmazás szolgáltatásnevének jogosultságaival futnak. Egy olyan eszköz futtatásához, amely a kérést küldő felhasználó jogosultságaival rendelkezik, adja meg a felhasználói jogosultságot a következőkben: agent.toml

  • Kezelt eszköz esetén állítsd be a(z) auth = "user" elemet az eszközbejegyzésen. Az agentbricks tools add MCP-szerverek, sandboxok és Genie Agents parancsai alapértelmezés szerint a(z) auth = "user" fájlba írnak. Adja át a(z) --auth app értéket, hogy helyette az alkalmazás azonosítóját használja.

  • Egy kódban írt eszköznél adja meg a követelményt és azokat az API hatótávokat, amelyeket az Agent Bricks nem tud kikövetkeztetni:

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

Amikor egy ügynök felhasználói hitelesítést igényel, DurableAgentServer a felhasználó hitelesítési adatait a megbízható Databricks Apps kérésfejléceiből olvassa ki, és csak az aktív próbálkozás idejére tartja a memóriában. A Runtime Store nem tárolja a hitelesítő adatokat. A kezelőben szerezz egy workspace klienst a felhasználó számára a(z) context.request_auth használatával:

@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") egy klienst ad vissza, amely az alkalmazás szolgáltatásnevét használja. A resolver akkor zárul le, amikor a kísérlet véget ér, ezért hívd meg a kezelőn belül a kliens tárolása helyett. Amikor helyben futtatod az ügynököt agentbricks dev, client_for("user") a helyi hitelesítő adataidat használja.

Telepítéskor a Databricks Apps kéri azokat a felhasználói hatóköröket agentbricks deploy, amelyekre az eszközeidnek szükségük van. Ha hiányzó hatóköröket szeretnél hozzáadni egy meglévő alkalmazáshoz, add meg a(z) --allow-user-scope-update paramétert. Lásd: Engedélyezés konfigurálása Databricks-alkalmazásokban.

A Request-user invokációk ugyanazokat a szinkron, streaming, háttér- és újrakapcsolási API-kat használják. Mivel a szerver nem tárolja a felhasználó hitelesítő adatait, nem tud helyreállítani egy megszakított kérés–felhasználó meghívást. A cserekísérlet hibával MCP_USER_AUTH_RECOVERY_UNSUPPORTED megbukik, mielőtt a kezelőid lefutnának.

Egyedi végpontok hozzáadása

DurableAgentServer egy FastAPI alkalmazás. Útvonalakat adj hozzá az invocation API mellé, ugyanúgy, ahogy bármelyik FastAPI alkalmazáshoz is hozzáadod őket:

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

Framework-sablonok

agentbricks init két könyvtárat generál:

  • agent/ tartalmazza a keretrendszered kódját: a modellt, a promptokat és eszközöket.
  • runtime/ tartalmazza azt az adaptert, amely összekapcsolja a keretrendszert a(z) DurableAgentServer elemmel, valamint a belépési pontot, amely regisztrálja az adapter invoke és recovery handlereit.

Az adapter minden meghívást a keretrendszer ügynök ciklusára való hívássá fordítja, és a keretrendszer kimenetét eseményekké és eredménnyé alakítja. Mindkét sablon regisztrál egy helyreállításkezelőt. A LangGraph sablon az utolsó checkpointjáról folytatódik a session store-ben, és az OpenAI Agents SDK sablon ugyanabban a munkamenetben ismétli a kérést. Egy meglévő ügynök beemeléséhez adj hozzá egy adaptert és egy DurableAgentServer entrypointot, és állítsd be a(z) server = "agentbricks" értéket a agent.toml[agent] szakaszában.

Az ügynökkiszolgálók összehasonlítása az Azure Databricksben

Az Azure Databricks három ügynökkiszolgálót biztosít: az AgentKit ügynökkiszolgálót és két régi ügynökkiszolgálót, amelyeket korábbi alkalmazássablonok használnak.

Agent-kiszolgáló Package Ügyfél API-címe Tartós megvalósítás Használta:
AgentKit (DurableAgentServer, ajánlott) databricks_agentkit, a databricks-agentbricks csomagban Invocation API a /api/invocations: szinkron, streaminges és háttérben futó műveletek, stream újracsatlakozással Egy Runtime Store, amely agentbricks deploy kiépít, plusz összeomlás utáni helyreállítás egy helyreállítási kezelőn keresztül Projektek, amelyeket az Agent Bricks CLI-val hozol létre
LongRunningAgentServer (örökölt) databricks_ai_bridge.long_running, a databricks-ai-bridge[agent-server] csomagban OpenAI Responses API a /responses oldalon, háttérfuttatásokkal és a stream folytatásával Futási állapot egy Ön által konfigurált Lakebase adatbázisban. Egy összeomlás után egy új próbálkozás onnan folytatja a futást, a megszakított próbálkozás eseménynaplója alapján. Az agent-openai-advanced és agent-langgraph-advancedalkalmazás sablonok
MLflow AgentServer (régi) mlflow.genai.agent_server, a mlflow csomagban OpenAI Responses API itt: /responses szinkron és streamelt futások None Az alap alkalmazás sablonok, például agent-openai-agents-sdk

LongRunningAgentServer kiterjeszti az MLflow-t AgentServer, és mindkettő olyan ügynököket szolgál ki, amelyek az MLflow ResponsesAgent interfészt valósítják meg. Az egyiküket használó ügynök üzembe helyezéséhez és karbantartásához lásd: Ügynökök futtatása Databricks Appsben a régi ügynökkiszolgáló használatával. Ha ügynököt szeretnél lekérdezni e kiszolgálók bármelyikén, lásd: Azure Databricksen üzembe helyezett ügynökök lekérdezése.

Limitations

  • Nem lehet megváltoztatni egy meglévő telepítés ügynökkiszolgálóját. A(z) DurableAgentServer és a saját szervered közötti váltáshoz hozz létre egy új projektet a kívánt agentbricks init --server beállítással, és telepítsd új néven.
  • A(z) server mező módosítása itt: agent.toml nem alakítja át a meglévő szerverkódot erre: DurableAgentServer.
  • A kérelmező felhasználó hitelesítéséhez server = "agentbricks" szükséges.

További erőforrások

  • Utolsó frissítés időpontja: