Háky agentů

Agent Hooks je klíčová schopnost frameworku Agent Framework pro uplatňování mechanismů řízení a běhových kontrol v jasně definovaných bodech během běhu agenta. Implementuje na frameworku nezávislý kontrakt AGENT-HOOKS-0.1, takže moduly pro vynucování zásad, schvalovací brány, rozpočtové kontroly, filtry obsahu a výstupní kontroly mohou využívat jedno společné řídicí rozhraní.

Důležité

Agent Hooks je řídicí rovina, ne rovina telemetrie. Každý interceptor vrací výsledek. V režimu enforce se framework řídí tímto verdiktem; v režimu evaluate_only verdikt zaznamenává, aniž by měnil běh. Používejte pozorovatelnost pro pasivní trasování, metriky a protokoly.

Agent Hooks zatím není pro .NET k dispozici. K přidání ovládacích prvků runtime do .NET agentů použijte middleware agenta, schválení nástrojů a bezpečnost agentů.

Agent Hooks je v Python experimentální. Metoda factory při prvním použití vrací ExperimentalWarning a její rozhraní API se může před všeobecnou dostupností změnit.

Kdy použít háky agenta

Použijte Agent Hooks, když vyvíjené nezávisle komponenty potřebují jeden sdílený a vymahatelný kontrakt pro vstup agenta, volání modelu, volání nástrojů a konečný výstup.

Schopnost	Použijte jej pro
Háky agentů	Standardizovaná rozhodnutí o zásadách, transformace, schvalování, rozpočty a výchozí řízení v rámci životního cyklu agenta.
Agentní middleware	Průřezové chování specifické pro aplikaci, které nevyžaduje kontrakt Agent Hooks ani jeho základní záruky běhového prostředí.
Zabezpečení agenta pomocí FIDES	Deterministické popisky a zásady toku informací pro nedůvěryhodný nebo důvěrný obsah
Schválení nástroje	Lidské potvrzení jednotlivých volání funkcí a nástrojů.
Pozorovatelnost	Pasivní trasování, metriky a protokoly, které neřídí provádění.

Co Agent Framework vynucuje

Když k agentovi přidáte Agent Hooks, Agent Framework uplatní koordinované vynucovací omezení napříč běhy agenta, voláními modelu a voláními nástrojů. Modul runtime poskytuje následující záruky:

• Uzavření při selhání: Zamítnutí zablokuje chráněnou akci. Neplatné kontexty, neplatná rozhodnutí, selhání interceptoru a selhání vynucování tiše neobcházejí kontrolní mechanismy.
• Zpětný zápis transformace: Transformace upravuje původní zprávy, argumenty nástroje, výsledky nástroje nebo konečnou odpověď, které se při provádění skutečně používají. Pokud transformaci nelze použít, běh skončí neúspěšně v uzavřeném stavu.
• Vyrovnávané streamování: K volajícímu se nedostane žádná aktualizace odpovědi, dokud úplná odpověď modelu i finální výstup neprojdou svými body zachycení.
• Perzistence řízená verdiktem: Perzistence čeká na verdikt, který se na ni vztahuje. Standardní persistování po běhu čeká na output; persistování historie pro každé volání služby čeká na každé post_model_call.
• Dokončení instalace sady: Části agenta, chatu a funkce se instalují jako jedna jednotka, takže nekompletní hranice vynucení není možné konfigurovat omylem.

Kontrakt je spíše kooperativním mechanismem než hranicí izolace mezi procesy. Zachytávače běží v hostitelském procesu a přijímají obsah potřebný pro rozhodování. Registrujte pouze interceptory, kterým důvěřujete.

Instalace háků agenta

Nainstalujte sadu Agent Hooks SDK jako přímou závislost:

pip install agent-hooks-sdk

Pokud používáte uv:

uv add agent-hooks-sdk

Závislost agent-hooks-sdk se importuje až při potřebě. Import agent_framework nenačte sadu SDK, pokud nevytvoříte sadu middlewaru Agent Hooks.

Poznámka:

agent-framework-core neobsahuje žádný agent-hooks navíc. Před vytvořením balíčku middlewaru Agent Hooks nainstalujte agent-hooks-sdk samostatně.

Přidání průsečíku

Interceptor obdrží objekt agent_hooks.AgentContext (mapování kontextu specifikace, nikoli agent_framework.AgentContext, který používá middleware agenta) a vrátí verdikt. Následující průsečík blokuje konečný výstup obsahující slovo secret. V příkladu client se předpokládá, že už je nakonfigurovaný chatovací klient rozhraní Agent Framework.

from agent_framework import Agent, create_agent_hooks_middleware
from agent_hooks import ALLOW, AgentContext, InterceptionBlocked, Verdict


class SecretEgressGuard:
    def intercept(self, context: AgentContext) -> Verdict:
        if (
            context["interception_point"] == "output"
            and "secret" in str(context["target"]).lower()
        ):
            return Verdict.deny(
                reason="secret_in_output",
                message="The final response contains restricted content.",
            )
        return ALLOW


hooks = create_agent_hooks_middleware(
    {"secret-egress": SecretEgressGuard()},
)

agent = Agent(
    client=client,
    instructions="You are a helpful assistant.",
    middleware=[hooks],
)

try:
    response = await agent.run("Summarize the account details.")
except InterceptionBlocked as exc:
    print(f"Blocked: {exc.result.verdict.reason}")

Předejte balíček jako jednu položku seznamu middleware agenta. Na každého agenta nainstalujte přesně jeden balíček Agent Hooks.

Průsečíkové body

Agent Framework generuje příslušné průsečíkové body automaticky:

Bod zachycení	Když je emitováno	Cíl transformace
agent_startup	Před prvním zadáním v relaci Agent Hooks	Nejde transformovat
input	Když agent obdrží externí požadavek	Vstupní obsah a role
pre_model_call	Před každou žádostí o model	Zprávy odeslané do modelu
post_model_call	Po každé úplné odpovědi modelu	Obsah odpovědi, volání nástrojů prováděná frameworkem a důvod ukončení
pre_tool_call	Před vyvoláním jednotlivých nástrojů spouštěných architekturou	Argumenty nástrojů
post_tool_call	Po úspěšném provedení nebo selhání nástroje	Výsledek nástroje
output	Předtím, než konečná odpověď dorazí k volajícímu	Konečný obsah odpovědi
agent_shutdown	Když se relace Agent Hooks dokončí, selže nebo zruší	Nejde transformovat

agent_startup.tools_registered je snímek nástroje Run-Start. Každý pre_model_call payload obsahuje ve svém volitelném poli tools skutečně použité nástroje pro dané volání modelu. To zahrnuje nástroje přidané během spuštění poskytovateli kontextu, připojenými servery MCP nebo progresivním zveřejněním. Pole se vynechá, pokud volání neobsahuje žádné nástroje nebo nelze promítnout sadu nástrojů.

Spuštění, které volá nástroj, obvykle generuje:

agent_startup input → → pre_model_call → post_model_call → pre_tool_call → post_tool_call → pre_model_call → post_model_call → → outputagent_shutdown

Verdikty

Smlouva má tři rozhodnutí: allow, denya transform. Sada Python SDK také poskytuje pomocné rutiny pro upozornění a odepření metodou "liftable".

Result	rozhraní API Python	Behavior
Povolit	ALLOW nebo Verdict(decision=Decision.ALLOW)	Pokračujte s cílem beze změny.
Povolit s upozorněním	Verdict.warn(...)	Pokračujte a zahrňte upozornění do záznamu zachycení.
Odmítnout	Verdict.deny(...)	Zablokujte stráženou akci.
Zamítnout čekající schválení	Verdict.escalate(...)	Zablokovat, pokud nakonfigurovaný mechanismus pro vyhodnocení schválení nevrátí kladné rozhodnutí.
Přeměna	Verdict(decision=Decision.TRANSFORM, transform=Transform(...))	Přepište hodnotu pod $targetpoložkou a pokračujte přepsanou hodnotou.

Blokace na úrovni běhu i modelu vyvolají InterceptionBlocked a zabrání tomu, aby se chráněný výsledek dostal k volajícímu nebo do další fáze. Na rozhraní nástroje politika zamítnutí zabrání provedení akce nástroje nebo zahodí její výsledek a vrátí modelu chybu řízení obsahující důvod daný politikou, bez datové části zamítnutého cíle. To umožňuje pokračovat ve smyčce agenta. Selhání hostitele nebo vynucení zastaví spuštění.

Přerušení spuštění z middlewaru funkcí

Importovat MiddlewareFailure z agent_framework. Middleware pro funkce obvykle převede běžnou výjimku na výsledek typu chyba nástroje a poté umožní, aby smyčka agenta pokračovala. Pokud middleware funkce nemůže bezpečně pokračovat, zvedněte MiddlewareFailure z podkladové výjimky. Modul runtime přeruší spuštění a rozšíří selhání do volajícího místo jeho převodu na výsledek nástroje.

Nezachytávejte MiddlewareFailure v middlewaru. Jeho zachycení umožní smyčce pokračovat a změní uzavřené chování při selhání na otevřené chování při selhání. Agent Hooks používá tento signál interně při selhání vrstvy vynucení funkce middlewaru. Předání vlastního middlewaru uzavřeného při selhání v sekvenci, například middleware=[policy_middleware].

Při souběžných voláních nástrojů běhové prostředí zruší ostatní právě probíhající souběžná volání dříve, než chybu propaguje dál. Zrušení funguje na principu spolupráce, takže synchronní nástroj, který už běží v pracovním vlákně, může dokončit své vedlejší účinky, ale jeho výsledek se zahodí.

Použití transformace

Cesta transformace musí začínat na $target. Průsečík může například nahradit konečný obsah odpovědi:

from agent_hooks import ALLOW, AgentContext, Decision, Transform, Verdict


class OutputRedactor:
    def intercept(self, context: AgentContext) -> Verdict:
        if context["interception_point"] != "output":
            return ALLOW

        return Verdict(
            decision=Decision.TRANSFORM,
            reason="redacted_output",
            transform=Transform(
                path="$target.content",
                value="[Response removed by policy]",
            ),
        )

Transformace se aplikují na hodnoty Agent Framework Content a zachovávají podporovaný formátovaný obsah, místo aby se každá hodnota převedla na prostý text. Poškozená cesta nebo nekompatibilní nahrazení se zavře, místo aby pokračovala s původní hodnotou.

Schvalování nástrojů a transformace argumentů

Mechanismus schvalování nástroje Agent Framework a mechanismus schvalování Agent Hooks jsou samostatné mechanismy. U funkčního nástroje s approval_mode="always_require" Agent Framework vytvoří žádost o schválení člověkem před spuštěním middlewaru funkce. pre_tool_call Transformace může proto změnit argumenty poté, co uživatel schválil původní hodnoty.

Warning

Neměňte argumenty pre_tool_call pro nástroje, které používají approval_mode="always_require". Transformujte volání nástroje v post_model_call tak, aby žádost o schválení ve frameworku obsahovala transformované hodnoty, nebo vraťte Verdict.escalate(...) v pre_tool_call a schválení vyřešte pomocí Agent Hooks resolver.

Streamování a trvalost

Agent Hooks zachovává streamovací API, ale používá sémantiku výstupu s ukládáním do vyrovnávací paměti. Agent Framework sestaví úplnou odpověď modelu, vygeneruje post_model_call, sestaví konečnou odpověď agenta a před vydáním jakýchkoli aktualizací vygeneruje output . Pokud některý z bodů odpověď odmítne, volající neobdrží žádné částečné aktualizace.

Toto chování vykupuje latenci při zpracování token po tokenu vynucením výstupu v režimu fail-closed. Výstupní transformace se rovněž promítne do aktualizací, které jsou nakonec předány volajícímu.

Perzistence je řízena bodem zachycení, který pokrývá operaci perzistence:

• Ve výchozím nastavení historie a další úlohy poskytovatele po spuštění čekají na výsledek output. Odepřený výstup se neuchová a po transformaci se zachová výstupní transformace.
• Když nastavíte require_per_service_call_history_persistence=True v konstruktoru Agent nebo v client.as_agent(...), každá výměna s modelem se uloží poté, co to povolí jeho verdikt post_model_call. Pozdější output odepření nezruší již povolenou historii.
• Pro výchozí zachování stavu po spuštění zůstávají pokusy o opětovné provedení až za konečným rozhodnutím output. Režim volání jednotlivých služeb místo toho zachovává každou odpověď modelu, která projde post_model_call.

Důležité

Pokud se obsah modelu nesmí stát trvalým, vynucujte zásadu v okamžiku post_model_callrequire_per_service_call_history_persistence=True. Zásada odchozí komunikace pouze pro výstup chrání to, co se dostane k volajícímu, ale zpětně neodstraní interakce s modelem, které už byly povoleny a uloženy v post_model_call.

Relace a záznamy auditu

Ve výchozím nastavení se při každém spuštění agenta vytvoří jedna relace Agent Hooks. agent_startup a agent_shutdown ohraničují běh a záznamy dostanou jedno ID relace s monotonně rostoucí sekvencí.

Pomocí record_sink budete dostávat vše z InterceptionRecord:

records = []

hooks = create_agent_hooks_middleware(
    {"secret-egress": SecretEgressGuard()},
    record_sink=records.append,
)

Záznamy o zachycení zaznamenávají rozhodnutí, důvod, souhrn interceptoru, režim, identitu a posloupnost, aniž by se zachycená datová část kopírovala do auditního záznamu. Samotný interceptor stále přijímá plný kontext.

Zahrnout více spuštění v rámci jedné relace

Použijte create_agent_hooks_middleware_from_emitter(), když aplikace udržuje déle trvající relaci Agent Hooks, například konverzaci s jednou evidencí schválení:

from agent_framework import Agent, create_agent_hooks_middleware_from_emitter
from agent_hooks import AgentContextBuilder, InterceptionEmitter


emitter = InterceptionEmitter().register(SecretEgressGuard())
builder = AgentContextBuilder(
    agent_id="support-agent",
    framework="agent-framework",
    session_id="conversation-42",
)

hooks = create_agent_hooks_middleware_from_emitter(emitter, builder)
agent = Agent(client=client, middleware=[hooks])

await emitter.emit(builder.agent_startup(tools_registered=[]))
await agent.run("First turn")
await agent.run("Second turn")
await emitter.emit(builder.agent_shutdown(reason="completed"))

V této podobě aplikace konfiguruje vysílač a sama zajišťuje spuštění, vypnutí a čištění po chybách. Middleware generuje body za každé spuštění od input do output.

Konfigurace vynucení

create_agent_hooks_middleware() přijímá následující ovládací prvky:

Parameter	Purpose
interceptors	Posloupnost interceptorů nebo mapování názvů na interceptory. Je vyžadován alespoň jeden.
resolver	Řeší zamítnutí, která lze zrušit, prostřednictvím schvalovacího procesu. Bez resolveru zůstává zamítnutí v platnosti.
mode	"enforce" uplatňuje verdikty. "evaluate_only" zaznamenává, co by se stalo, ale umožňuje každou akci.
composition	Určuje, jak se kombinují verdikty více interceptorů.
identity_provider	Vytvoří kontextové identity vázané na obsah. Výchozí hodnota je "jcs-sha256".
timeout	Časový limit průsečíku a překladače pro očekávaná volání Výchozí hodnota je pět sekund. Synchronní průsečík nebo překladač, který blokuje smyčku událostí, není možné tímto vypršením časového limitu předem zastavit.
record_sink	Přijímá každý záznam o zachycení bez datové části.

Výchozí složení je sekvenční first_deny se schválením nakonfigurovaným tak, aby zastavilo přeložení. Pořadí průsečíku je proto důležité: umístěte ovládací prvky, které musí vždy běžet před ovládacími prvky, které mohou požadovat schválení. Než vyberete jiný profil složení, podívejte se do produkčního kontrolního seznamu Agent Hooks.

Zavedení s režimem jen pro vyhodnocení

Slouží evaluate_only k měření chování zásad před vynucením:

hooks = create_agent_hooks_middleware(
    {"secret-egress": SecretEgressGuard()},
    mode="evaluate_only",
    record_sink=records.append,
)

V tomto režimu interceptory běží a záznamy obsahují jejich verdikty, ale žádná akce se neblokuje ani neupravuje. Nepopisujte nasazení evaluate_only jako vynucenou správu.

Pravidla složení

Umístěte balíček na první místo v seznamu middlewaru agenta, aby tvořil nejvnější hranici vynucování:

agent = Agent(
    client=client,
    middleware=[
        create_agent_hooks_middleware([SecretEgressGuard()]),
        application_middleware,
    ],
)

Postupujte podle těchto pravidel:

• Pro každého agenta nainstalujte přesně jeden balíček Agent Hooks. Svazky naskládané na sebe nejsou přijímány.
• Ponechte svazek nedotčený. Agenta, chat a middleware pro funkce nelze nainstalovat samostatně.
• Nainstalujte balíček do Agent, nikoli přímo do chatovacího klienta ani prostřednictvím poskytovatele kontextu.
• Middleware umístěné před balíčkem je mimo oblast vynucování. Považujte vnější pozici za externí důvěru.
• Každému vnořenému agentovi přiřaďte vlastní balíček, pokud je třeba zachytávat i jeho interní model a činnost nástrojů.

Aktuální omezení

• pouze Python: Hooky agentů se zatím neimplementují v sadách SDK .NET nebo Go.
• Experimentální rozhraní API: Podpisy a chování továrny se můžou před obecnou dostupností změnit.
• Bufrované streamování: Aktualizace se neuvolňují po jednotlivých tokenech, protože výstup musí být kompletní před vydáním rozhodnutí fail-closed.
• Hostované nástroje: Nástroje spouštěné poskytovatelem modelu neprocházejí rozhraním Agent Frameworku pro vyvolávání funkcí. Jejich volání a výstupy se zobrazují v post_model_call, ale pre_tool_call a post_tool_call nemohou blokovat spouštění na straně serveru poskytovatele.
• Meze spolupráce: Agent Hooks neizoluje interceptory v sandboxu ani nechrání před škodlivým hostitelem. Cesty kódu, které obcházejí kanál strážených agentů, nejsou pokryté.
• Dostupnost interceptoru ovlivňuje dostupnost agenta: V režimu vynucení selhání interceptoru nebo vypršení časového limitu záměrně zablokuje chráněnou akci.

Pokyny k nasazení do produkce, důvodům selhání a upozorněním najdete v provozním runbooku Agent Hooks.

Agent Hooks ještě není dostupný pro Go. Pomocí agentního middlewaru, schvalování nástrojů a bezpečnosti agentů přidejte do agentů Go řídicí mechanismy za běhu.

Další kroky

Pochopte kanál zpracování agenta

Související obsah

• Agentní middleware
• Bezpečnost agenta
• Schválení nástroje
• Zabezpečení agenta pomocí FIDES
• Pozorovatelnost
• Specifikace AGENT-HOOKS-0.1