Agent Server

Agent server je knihovna, která promění kód agenta ve službu. Zapouzdřuje smyčku agenta v serveru HTTP, definuje API, které klienti volají ke spuštění agenta, spravuje klientská spojení a určuje, co se stane, když je běh přerušen. Agent server běží v runtime agenta. Chcete-li zjistit, jak vrstvy do sebe zapadají, viz Nasazení agentů na Azure Databricks.

Pro nové agenty Databricks doporučuje server agenta, který poskytuje AgentKit a který tato stránka popisuje. Pro srovnání se staršími servery agentů viz Porovnání serverů agentů ve službě Azure Databricks.

Requirements

Python 3.10 a vyšší.
Balíček databricks-agentbricks, který zahrnuje AgentKit. Projekty, které pomocí agentbricks init vytvoříte, to deklarují jako závislost.

AgentKit

AgentKit je knihovna Agent Bricks pro vytváření agentů, kteří běží na Agent Runtime. Poskytuje server agenta, který slouží vašemu agentovi, plus klienty a pomocníky pro paměť agenta, agentní relace, trasování a autentizaci. Projekty, které vytvoříte pomocí Agent Bricks CLI , používají AgentKit ve výchozím nastavení.

Server agenta

AgentKit poskytuje svůj agentní server prostřednictvím třídy DurableAgentServer. Agentní server obaluje váš agentní cyklus do HTTP serveru, který poskytuje API pro volání, sleduje každý běh a obnovuje běhy, které byly přerušeny pádem nebo restartem. Poskytuje:

Jedno API pro každý režim požadavků: synchronní, streamovací a volání na pozadí, plus opětovné připojení proudu, vše obsluhované stejným handlerem.
Idempotentní volání: ID generované klientem zajišťuje, že opakovaný požadavek nespustí duplicitní běh.
Řazené relace: Invokace ve stejné seanci probíhají jedno po druhém, v pořadí.
Trvalý stav běhu: Po nasazení stav běhu, události a výsledky přežijí restarty workeru.
Obnova po pádu: Server detekuje přerušené běhy a zahájí náhradní pokus.
Autorizace žadatele: Nástroje mohou jednat s oprávněními uživatele, který požadavek odeslal.
Vlastní endpointy: Agent server je aplikace FastAPI, takže si můžete přidávat vlastní routy.

Co AgentKit obsahuje

AgentKit je knihovna databricks_agentkit pro Python. Exportuje následující:

Export	Description
`DurableAgentServer`, `InvocationContext`	Agentní server a kontext, který předává vašim obslužným rutinám invoke a recovery handlerům.
`AgentKitClient`	Klient pro paměť agenta a úložiště relací agenta. Vytváří a získává úložiště a zpřístupňuje paměti a relace těchto úložišť jako objekty `Memory`, `MemoryStore`, `MemorySearchResult`, `Session`, `SessionStore` a `SessionItem`.
`configure_tracing`, `start_trace`	Nastavte MLflow trasování pro agenta a zahajte trasování pro jednotku práce.
`workspace_client`, `workspace_headers`	Vytvořte ověřenou sadu Databricks SDK `WorkspaceClient`, nebo získejte autentizační hlavičky pro přímé HTTP volání přímo z prostředí agenta.
`list_ai_gateway_model_services`	Vyjmenujte služby modelu, které může agent volat přes Unity Gateway.

Knihovna také obsahuje frameworkové pomocníky v databricks_agentkit.langgraph a databricks_agentkit.openai, které generované šablony používají k propojení každého frameworku s úložištěm relací. Pro paměťová API a API relací viz Paměť agenta a relace agentů.

Zaregistrujte svého agenta

Když vytvoříte projekt s agentbricks init, CLI to udělá za vás. Vygenerovaný runtime/main.py vytvoří server a registruje obslužné rutiny volání a obnovení šablony, takže kód agenta upravujete pouze v agent/. Postupujte podle kroků v této sekci, abyste nasadili stávajícího agenta nebo si napsali vlastního handlera.

Vytvořte objekt DurableAgentServer a registrujte obslužnou rutinu asynchronního volání pomocí @app.invoke. Handler přijímá input požadavku a kontext volání a vrací výsledek serializovatelný do JSON. Publikujte průběh jako události s 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}

Můžete zaregistrovat jednu obslužnou rutinu volání a server bez ní nezačne. Obslužná rutina podporuje všechny režimy požadavků: klient si vybírá, zda bude čekat na výsledek, streamovat události nebo běžet na pozadí.

Pro lokální spuštění serveru jej spusťte pomocí agentbricks dev. Projekty, které vytvoříte pomocí agentbricks init, zahrnují vstupní bod, který spustí server pomocí Uvicornu, a soubor app.yaml, který po nasazení spouští stejný vstupní bod.

Kontext vyvolání

Druhý argument handlera je InvocationContext:

Attribute	Description
`invocation_id`	ID, které klient poslal pro toto volání.
`session_id`	Sezení, ke kterému invokace patří, nebo `None`, pokud klient žádné neposlal.
`attempt`	Číslo pokusu. První pokus je `1`.
`is_recovery`	`True` když obslužná rutina obnovy provádí pokus o výměnu.
`emit(event)`	Uloží JSON událost, doručí ji streamovacím klientům a vrátí pozici události ve streamu.
`request_auth`	Resolver přihlašovacích údajů request-user, když agent vyžaduje autorizaci request-user. V opačném případě `None`.

Invocation API

DurableAgentServer poskytuje invocation API na adrese /api/invocations:

POST /api/invocations spouští vyvolání. Ve výchozím nastavení požadavek čeká na výsledek. Nastavte stream tak, aby přijímal události jako Server-Sent Events, nebo background pro okamžité vrácení s URL stavu.
GET /api/invocations/<id> vrací stav vyvolání a po jeho dokončení i jeho výstup.
GET /api/invocations/<id>/events?after=<event-id> streamuje uložené události, takže klient se může po přerušení připojení znovu připojit.

Pole požadavků, příklady a formáty odpovědí naleznete v tématu Agenti nasazení na Azure Databricks.

Idempotentnost

Klienti posílají UUID id při každém volání. Server považuje ID za klíč idempotence, zatímco si zachovává záznam volání: opětovné odeslání stejného požadavku vrátí stávající volání místo opětovného spuštění agenta. Opětovné použití ID pro jiný požadavek vrátí chybu 409 .

Sessions

Klienti mohou odeslat session_id, aby seskupili invokace do jedné konverzace. Server ukládá ID relace odděleně od input, předává jej vašemu handleru jako context.session_id, a provádí volání, která sdílejí ID relace jednu po druhé, v pořadí. Server neodvodí relaci z ID volání ani ze vstupu. Bez ID relace je volání bezrelacové.

Stav běhu

DurableAgentServer ukládá požadavek, stav, heartbeaty, události a výsledek každého vyvolání do Runtime Store.

Lokální vývoj: agentbricks dev používá Runtime Store v procesu. Invocation API se chová stejně, ale stav běhu se ztratí, když proces skončí, a server neobnoví přerušenou práci.
Nasazení agenti: agentbricks deploy zřídí dedikovanou databázi pro úložiště Runtime Store každého nasazení v projektu Lakebase spravovaném službou Azure Databricks a při opětovném nasazení ji znovu použije. Nemůžete použít svůj vlastní Lakebase projekt pro Runtime Store a sami jej nevytváříte ani nepřipojujete. Výsledky a události přežijí restarty pracovníka a jakákoli instance agenta může obsluhovat požadavky na stav a opětovné připojení. agentbricks deployments delete při nasazení odstraní Runtime Store.

Runtime Store uchovává stav spuštění serveru. Je oddělený od úložišť relací a paměti, které váš agent používá pro historii konverzací a dlouhodobou paměť.

Obnova po havárii

Pro obnovení běhů, které přeruší pád nebo restart pracovníka, registrujte obslužnou rutinu obnovení pomocí @app.recover. Když nasazený server zjistí, že se signály heartbeat běhu zastavily, zahájí pokus o náhradu na dostupném pracovníku a volá obslužnou rutinu pro obnovení s původním vstupem.

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

Pokud nezaregistrujete recovery handler, automatické obnovení se vypne a server při spuštění zaznamená varování.

Obnova probíhá následovně:

Když začne zotavení: Každý spuštěný pokus odešle heartbeat každých pár sekund. Pokud se signály heartbeat zastaví, například proto, že pracovník spadne, restartuje se nebo je během opětovného nasazení nahrazen, server během několika sekund detekuje uvízlé spuštění a zahájí pokus o nahrazení.
Když obnova nezačne: Pokud váš handler vyvolá výjimku, volání selže a server to nezkouší znovu. Zotavení se vztahuje na přerušené pracovníky, ne na chyby v kódu agenta.
Počet pokusů: Server neomezuje počet pokusů o obnovu. S každým pokusem o náhradu se context.attempt zvýší o jedno. Chcete-li zastavit po několika pokusech, zkontrolujte context.attempt ve své obsluze obnovení a vyvolejte chybu.
Manuální obnova: Obnovu nelze spustit ručně. Opětovné odeslání požadavku se stejným ID volání vrátí existující invokaci místo zahájení nového pokusu.

Recovery může spustit kód agenta více než jednou pro stejné volání. Přerušený pokus mohl již volat externí systémy před začátkem opakovaného pokusu, proto tato volání nastavte jako idempotentní.

Požadovat autorizaci uživatele

Ve výchozím nastavení běží nástroje vašeho agenta s oprávněními instančního objektu služby aplikace. Pro spuštění nástroje s oprávněními uživatele, který požadavek poslal, deklarujte autorizaci uživatele v agent.toml:

Pro spravovaný nástroj nastavte auth = "user" v položce nástroje. Příkazy agentbricks tools add pro MCP servery, sandboxy a Genie Agents ve výchozím nastavení zapisují auth = "user". Předejte --auth app a místo toho použijte identitu aplikace.
Pro nástroj, který píšete v kódu, deklarujte požadavek a případné rozsahy API, které Agent Bricks nedokáže odvodit:
```
[auth.user]
required = true
additional_api_scopes = ["sql"]
```

Když agent vyžaduje autorizaci uživatele, DurableAgentServer čte uživatelské přihlašovací údaje z důvěryhodných hlaviček požadavků Databricks Apps a uchovává je v paměti pouze pro aktivní pokus. Runtime Store přihlašovací údaj neukládá. Ve vašem handleru získejte klienta pro pracovní prostor pro uživatele z: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") vrací klienta, který používá instanční objekt služby aplikace. Resolver se zavírá, když pokus skončí, takže ho volejte uvnitř handleru místo ukládání klienta. Když spustíte agenta lokálně s agentbricks dev, client_for("user") používá vaše místní přihlašovací údaje.

Při nasazení si agentbricks deploy vyžádá uživatelské rozsahy Databricks Apps, které vaše nástroje potřebují. Pro přidání chybějících rozsahů do existující aplikace zadejte --allow-user-scope-update. Viz Konfigurace autorizace v aplikaci Databricks.

Volání request-user používají stejná synchronní, streamingová, na pozadí a pro opětovné připojení API. Protože server neukládá přihlašovací údaje uživatele, nemůže obnovit přerušené vyvolání požadavku uživatelem. Pokus o výměnu selže s chybou MCP_USER_AUTH_RECOVERY_UNSUPPORTED dřív, než se spustí vaše handlery.

Přidejte vlastní endpointy

DurableAgentServer je aplikace FastAPI. Přidávejte trasy vedle invocation API stejným způsobem, jakým je přidáváte do jakékoli aplikace FastAPI:

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

Šablony Framework

agentbricks init generuje dva adresáře:

agent/ Obsahuje váš kód rámce: model, prompty a nástroje.
runtime/ obsahuje adaptér, který spojuje framework s DurableAgentServer, a vstupní bod, který registruje handlery pro volání a zotavení.

Adaptér převádí každé volání na volání agentní smyčky frameworku a překládá výstup frameworku na události a výsledek. Obě šablony registrují recovery handler. Šablona LangGraph pokračuje od svého posledního kontrolního bodu v úložišti relací a šablona OpenAI Agents SDK přehraje požadavek ve stejné relaci. Chcete-li použít existujícího agenta, přidejte adaptér a vstupní bod DurableAgentServer a nastavte server = "agentbricks" v části [agent] souboru agent.toml.

Porovnání serverů agenta v Azure Databricks

Azure Databricks poskytuje tři servery agentů: server agentů AgentKit a dva starší servery agentů, které používají dřívější šablony aplikací.

Server agenta	Balíček	Adresa API klienta	Odolné provedení	Používáno kým
AgentKit (`DurableAgentServer`, doporučeno)	`databricks_agentkit`, v balíčku `databricks-agentbricks`	Invocation API na `/api/invocations`: synchronní, streamované a běhy na pozadí, s opětovným připojením ke streamu	Runtime Store, který zajišťuje `agentbricks deploy`, plus obnovení po pádu prostřednictvím obslužné rutiny pro obnovení	Projekty, které vytváříte pomocí Agent Bricks CLI
`LongRunningAgentServer` (starší verze)	`databricks_ai_bridge.long_running`, v balíčku `databricks-ai-bridge[agent-server]`	OpenAI Responses API v `/responses` se spuštěními na pozadí a obnovením streamu	Stav spuštění v databázi Lakebase, kterou nakonfigurujete. Po pádu nový pokus pokračuje v běhu z logu událostí přerušeného pokusu.	Šablony `agent-openai-advancedagent-langgraph-advanced` a
MLflow `AgentServer` (starší verze)	`mlflow.genai.agent_server`, v balíčku `mlflow`	OpenAI Responses API na `/responses`: synchronní a streamovací běhy	None	Základní šablony aplikací, například `agent-openai-agents-sdk`

LongRunningAgentServer rozšiřuje MLflow AgentServer, a oba slouží agentům, kteří implementují rozhraní MLflow ResponsesAgent . Informace o nasazení a údržbě agenta, který používá jeden z nich, najdete v Spuštění agentů v Databricks Apps pomocí staršího serveru agentů. Pro dotazování agenta na kterémkoli z těchto serverů viz Dotazování agentů nasazených na Azure Databricks.

Limitations

Nemůžete změnit server agenta u existujícího nasazení. Pro přepínání mezi DurableAgentServer a vlastním serverem vytvořte nový projekt s požadovanou agentbricks init --server možností a nasaďte ho pod novým názvem.
Změna server pole v agent.toml nepřevede existující serverový kód do DurableAgentServer.
Autorizace požadavku uživatelem vyžaduje server = "agentbricks".

Dodatečné zdroje

Váš názor

Byla tato stránka užitečná?

Poslední aktualizace v 2026-10-15