Ügynökhookok

Az Agent Hooks az Agent Framework egyik kiemelt képessége, amely jól meghatározott pontokon teszi lehetővé az irányítási és futásidejű vezérlők alkalmazását egy ügynök végrehajtása során. Implementálja a keretrendszersemleges AGENT-HOOKS-0.1 szerződést, így a szabályzatmotorok, a jóváhagyási átjárók, a költségvetés-védők, a tartalomszűrők és a kimenő forgalom vezérlői egyetlen közös vezérlőfelületet célozhatnak meg.

Important

Az Agent Hooks egy vezérlősík, nem telemetriai sík. Minden elfogó egy ítéletet ad vissza. Módban enforce a keretrendszer az ítéletre hat; evaluate_only módban a végrehajtás módosítása nélkül rögzíti az ítéletet. Használjon megfigyelhetőséget passzív nyomkövetéshez, metrikákhoz és naplókhoz.

Az Agent Hooks még nem érhető el a .NET-hez. Az ügynökközvetítő, az eszközjóváhagyás és az ügynökbiztonság használatával futtatókörnyezeti vezérlőket adhat hozzá .NET ügynökökhöz.

Az Agent Hooks Pythonban kísérleti. A gyár az első használatkor bocsát ki egy ExperimentalWarning hibát, és az API-ja az általános rendelkezésre állás előtt változhat.

Mikor érdemes használni az Agent Hooksot?

Az Ügynökhookokat akkor használja, ha a független fejlesztésű vezérlőknek egyetlen megosztott, végrehajtható szerződésre van szükségük az ügynök bemenete, a modellhívások, az eszközhívások és a végső kimenet között.

Képesség Használja a következőhöz:
Ügynök-beavatkozási pontok Szabványosított házirendi döntések, átalakítások, jóváhagyások, költségvetések és kimenőforgalom-szabályozás az ügynök életciklusa során.
Ügynök köztes szoftvere Alkalmazásspecifikus, keresztmetszeti működés, amely nem igényli az Agent Hooks kontraktust vagy annak alapvető futásidejű garanciáit.
Ügynökbiztonság a FIDES használatával Determinisztikus információáramlási címkék és szabályzatok nem megbízható vagy bizalmas tartalmakhoz.
Eszköz jóváhagyása Az egyes függvény- és eszközhívások emberi megerősítése.
Megfigyelhetőség Passzív nyomkövetések, metrikák és naplók, amelyek nem szabályozzák a végrehajtást.

Amit az Ügynök-keretrendszer kényszerít

Amikor Agent Hookokat ad egy ügynökhöz, az Agent Framework összehangolt érvényesítési korlátot alkalmaz az ügynökfuttatásokra, a modellhívásokra és az eszközhívásokra. A futtatókörnyezet a következő garanciákat biztosítja:

  • Sikertelen lezárás: A megtagadás blokkolja a védett műveletet. Az érvénytelen kontextusok, a hibás döntések, az elfogók hibái és az érvényesítési hibák nem kerülik meg csendben a vezérléseket.
  • Visszaírás átalakítása: Az átalakítás megváltoztatja a végrehajtás által ténylegesen használt natív üzeneteket, eszközargumentumokat, eszközeredményeket vagy végső választ. Ha az átalakítás nem alkalmazható, a futtatás sikertelen lesz.
  • Pufferelt adatfolyam-továbbítás: Semmilyen válaszfrissítés nem jut el a hívóhoz, amíg a teljes modellválasz és a végső kimenet át nem halad az interceptálási pontjain.
  • Ítélethez kötött perzisztencia: A perzisztencia megvárja a rá vonatkozó ítéletet. A szokásos futás utáni perzisztencia a(z) output elemre vár; a szolgáltatáshívásonkénti előzmény-perzisztencia minden egyes post_model_call elemre vár.
  • A teljes csomag telepítése: Az ügynök-, a csevegő- és a funkciómodul egyetlen egységként települ, így nem lehet véletlenül hiányos érvényesítési határt konfigurálni.

A szerződés nem folyamatelkülönítési határ, hanem együttműködés. Az interceptorok a gazdafolyamatban futnak, és megkapják a döntések meghozatalához szükséges tartalmat. Csak megbízható interceptorokat regisztráljon.

Ügynökhookok telepítése

Telepítse az alapcsomag opcionális agent-hooks extra verzióját:

pip install "agent-framework-core[agent-hooks]"

Ha a következőt használja uv:

uv add "agent-framework-core[agent-hooks]"

A agent-hooks-sdk függőség lustán van importálva. A(z) agent_framework importálása nem tölti be az SDK-t, hacsak nem hoz létre egy Agent Hooks middleware-csomagot.

Note

Az agent-hooks extra szándékosan nem szerepel a agent-framework-core[all]. Telepítse explicit módon, ha engedélyezni szeretné ezt a kísérleti vezérlőfelületet.

Elfogó hozzáadása

Egy interceptor megkap egy agent_hooks.AgentContext elemet (a specifikáció kontextusleképezését, nem pedig az ügynök-köztesréteg által használt agent_framework.AgentContext elemet), és döntést ad vissza. Az alábbi interceptor blokkolja a szót secrettartalmazó végső kimenetet. A példa feltételezi, hogy a client egy már konfigurált Agent Framework csevegési ügyfél.

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}")

Adja át a csomagot az ügynök middleware listájának egyik elemeként. Minden ügynökre pontosan egy Agent Hooks-csomagot telepítsen.

Beavatkozási pontok

Az Agent Framework automatikusan bocsátja ki a vonatkozó elfogási pontokat:

Beavatkozási pont Amikor kibocsátják Cél átalakítása
agent_startup Egy Agent Hooks-munkamenet első bevitele előtt Nem alakítható át
input Amikor egy külső kérés az ügynökhöz érkezik Bemeneti tartalom és szerepkör
pre_model_call Minden modellkérés előtt A modellnek küldött üzenetek
post_model_call Minden egyes teljes modellválasz után Választartalom, keretrendszer által végrehajtott eszközhívások és befejezési ok
pre_tool_call Minden keretrendszer által végrehajtott eszközhívás előtt Eszközargumentumok
post_tool_call Miután egy eszköz sikeresen vagy sikertelenül lefutott Eszköz eredménye
output Mielőtt a végső válasz elérené a hívót Végső válasz tartalma
agent_shutdown Amikor az Agent Hooks-munkamenet befejeződik, meghiúsul vagy megszakad Nem alakítható át

Az eszköz meghívására szolgáló futtatás általában a következőt bocsátja ki:

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

Ítéletek

A szerződés három határozattal rendelkezik: allow, denyés transform. A Python SDK emellett segítséget nyújt a figyelmeztetésekhez és a felemelhető tagadásokhoz.

Result Python API Viselkedés
Lehetővé teszi ALLOW vagy Verdict(decision=Decision.ALLOW) Folytassa a célszöveg módosítása nélkül.
Engedélyezés figyelmeztetéssel Verdict.warn(...) Folytassa, és foglalja bele a figyelmeztetést az elfogási jegyzőkönyvbe.
Deny Verdict.deny(...) Tiltsa le a védett műveletet.
Függőben lévő jóváhagyás megtagadása Verdict.escalate(...) Tiltsa le, kivéve ha a konfigurált jóváhagyáskiértékelő engedélyező döntést ad vissza.
Átalakítás Verdict(decision=Decision.TRANSFORM, transform=Transform(...)) Írja át az értéket az alatt $target, majd folytassa az újraírt értékkel.

A futtatási szintű és a modellszintű tiltások InterceptionBlocked-t váltanak ki, és megakadályozzák, hogy a védett eredmény eljusson a hívóhoz vagy a következő szakaszhoz. Egy eszközillesztésnél egy szabályzati tiltás megakadályozza az eszközművelet végrehajtását, vagy elveti annak eredményét, és egy, a szabályzati okot tartalmazó vezérlési hibát ad vissza a modellnek, az elutasított cél hasznos adatai nélkül. Ez lehetővé teszi az ügynökhurok folytatását. A gazdagép vagy a kényszerítési hiba leállítja a futtatást.

Átalakítás alkalmazása

Az átalakítási útvonalnak a kezdő időponttól $targetkell kezdődnie. Egy elfogó például lecserélheti a végső válasz tartalmát:

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]",
            ),
        )

Az átalakítások az Agent Framework Content értékeire vonatkoznak, így a támogatott tartalom megmarad ahelyett, hogy az összes értéket egyszerű szöveggé csökkentené. A hibásan formázott elérési út vagy az inkompatibilis csere zárt állapotban hibázik ahelyett, hogy az eredeti értékkel folytatódna.

Eszközjóváhagyás és argumentumátalakítások

Az Ügynök-keretrendszer eszközjóváhagyása és az Agent Hooks jóváhagyási varrata külön mechanizmus. A approval_mode="always_require" függvényeszköz esetében az Agent Framework a függvényköztes réteg futása előtt hozza létre az emberi jóváhagyási kérelmet. Az pre_tool_call átalakítás ezért módosíthatja az argumentumokat, miután a felhasználó jóváhagyta az eredeti értékeket.

Warning

Ne alakítsa át a(z) pre_tool_call argumentumait azoknál az eszközöknél, amelyek approval_mode="always_require" használnak. Alakítsa át a(z) post_model_call helyen lévő eszközhívást úgy, hogy a keretrendszer jóváhagyási kérelme tartalmazza az átalakított értékeket, vagy térjen vissza a(z) Verdict.escalate(...) értékkel a(z) pre_tool_call helyen, és kezelje a jóváhagyást a(z) Agent Hooks resolver segítségével.

Streamelés és adatmegőrzés

Az Agent Hooks megtartja a streamelési API-t, de pufferelt kimeneti szemantikát használ. Az Agent Framework összeállítja a modell teljes válaszát, elküldi a post_model_call elemet, összeállítja az ügynök végső válaszát, és elküldi a output elemet, mielőtt bármilyen frissítést kiadna. Ha bármelyik pont tagadja a választ, a hívó nem kap részleges frissítéseket.

Ez a működés feláldozza a tokenenkénti késleltetést a zárt hibakezelésű kimenet kikényszerítése érdekében. A kimeneti átalakítás a hívónak végül kiadott frissítésekben is tükröződik.

A perzisztencia az azt lefedő perzisztenciaművelet interceptálási pontjától függ:

  • Alapértelmezés szerint a naplózás és a többi futtatás utáni szolgáltatómodul megvárja a output eredményét. A megtagadott kimenet nem marad meg, és a kimeneti átalakítás az átalakítás után is megmarad.
  • Amikor a Agent konstruktoron vagy a client.as_agent(...) elemen beállítja a require_per_service_call_history_persistence=True értéket, minden egyes modellváltás mentésre kerül, miután azt a post_model_call döntése engedélyezi. Egy későbbi output tiltás nem vonja vissza a már engedélyezett előzményeket.
  • A futtatás utáni alapértelmezett adatmegőrzés esetében az újrapróbálkozási kísérletek a végső output döntés mögött maradnak. A szolgáltatáshívásonkénti mód ezzel szemben minden olyan modellválaszt tárol, amely áthalad a post_model_call elemen.

Important

Ha a modell tartalma nem válhat tartóssá, érvényesítse ezt a szabályzatot a(z) require_per_service_call_history_persistence=True helyen, amikor post_model_call. A csak kimenő forgalomra vonatkozó szabályzat védi azt, ami eljut a hívóhoz, de nem távolítja el visszamenőlegesen a már engedélyezett és a(z) post_model_call helyen tárolt modellcseréket.

Munkamenetek és auditnapló-bejegyzések

Alapértelmezés szerint minden ügynökfuttatás létrehoz egy Agent Hooks-munkamenetet. agent_startup és agent_shutdown közrefogja a futást, és a rekordok egy munkamenet-azonosítót, valamint egy monoton növekvő sorszámot kapnak.

Az egyes record_sink fogadásához használja a(z) InterceptionRecord:

records = []

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

Az elfogási rekordok rögzítik a döntést, az okot, az interceptor összegzését, a módot, az azonosságot és a sorrendet, anélkül hogy az elfogott hasznos adatokat átmásolnák az auditnapló-rekordba. Maga az interceptor továbbra is megkapja a teljes kontextust.

Egy munkamenet több futtatásra terjed ki

Használja a(z) create_agent_hooks_middleware_from_emitter() elemet, amikor az alkalmazás egy hosszabb ideig fennálló Agent Hooks-munkamenetet tart fenn, például egy jóváhagyási főkönyvvel folytatott beszélgetés esetén:

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

Ebben az űrlapban az alkalmazás konfigurálja az emittert, és rendelkezik indítási, leállítási és hibatisztítási funkcióval. A köztesréteg a futtatásonkénti pontokat input és output között küldi.

Kényszerítés konfigurálása

create_agent_hooks_middleware() A következő vezérlőket fogadja el:

Paraméter Alkalmazás célja
interceptors Elfogók sorozata vagy név–elfogó leképezés. Legalább egy szükséges.
resolver Feloldja a feloldható tagadásokat egy jóváhagyási csatornán keresztül. Feloldó nélkül a megtagadás érvényben marad.
mode "enforce" ítéleteket alkalmaz. "evaluate_only" rögzíti, hogy mi történne, de minden műveletet engedélyez.
composition Azt határozza meg, hogy a rendszer hogyan kombinálja a több elfogópontot.
identity_provider Tartalomhoz kötött környezeti identitásokat hoz létre. Az alapértelmezett érték a "jcs-sha256".
timeout Elfogó- és feloldónkénti időtúllépés a várt hívásokhoz. Az alapértelmezett érték öt másodperc. Ez az időtúllépés nem előzheti meg az eseményhurkot blokkoló szinkron elfogót vagy feloldót.
record_sink Minden adatterhet nem tartalmazó elfogási bejegyzést megkap.

Az alapértelmezett összeállítás szekvenciális first_deny, és a jóváhagyás úgy van beállítva, hogy leállítsa a foldot. Ezért fontos az elfogó sorrend: olyan vezérlőket helyezzen el, amelyeknek mindig a jóváhagyást kérő vezérlők előtt kell futniuk. Egy másik összeállítási profil kiválasztása előtt tekintse meg az Agent Hooks éles ellenőrzőlistát .

Bevezetés csak kiértékelő móddal

A szabályzat viselkedésének mérésére használható evaluate_only a kényszerítés előtt:

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

Ebben a módban az interceptorok futnak, és a rekordok tartalmazzák a döntéseiket, de semmi sem kerül blokkolásra vagy átalakításra. Ne írja le a(z) evaluate_only üzembe helyezést kikényszerített irányításként.

Összeállítási szabályok

Helyezze a csomagot először az ügynök köztes szoftverlistájába, hogy az a legkülső kényszerítési határt képezhesse:

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

Kövesse az alábbi szabályokat:

  • Ügynökönként pontosan egy Agent Hooks-csomagot telepítsen. A halmozott kötegeket a rendszer elutasítja.
  • Tartsa érintetlenül a csomagot. Az ügynök, a chat és a függvényköztes réteg nem telepíthetők külön-külön.
  • Telepítse a csomagot a(z) Agent elemre, ne közvetlenül chatkliensre, és ne kontextusszolgáltatón keresztül.
  • A csomag elé helyezett köztes réteg a kikényszerítési határon kívül esik. Tekintse a külső pozíciót külső bizalomnak.
  • Minden beágyazott ügynöknek saját csomagot adjon, ha belső modellje és eszköztevékenysége is elfogást igényel.

Jelenlegi korlátozások

  • csak Python: Az ügynökhookok még nem implementálhatók a .NET vagy a Go SDK-kban.
  • Kísérleti API: A gyári aláírások és a viselkedés az általános rendelkezésre állás előtt változhat.
  • Pufferelt adatfolyam: A frissítések nem tokenenként kerülnek kiadásra, mert a kimenetnek teljesnek kell lennie az elutasító döntés előtt.
  • Üzemeltetett eszközök: A modellszolgáltató által végrehajtott eszközök nem haladnak át az Agent Framework függvényhívási varratán. A hívásaik és kimeneteik a(z) post_model_call felületen jelennek meg, de a(z) pre_tool_call és post_tool_call nem tudják megakadályozni a szolgáltató kiszolgálóoldali végrehajtását.
  • Együttműködési határ: Az Agent Hooks nem futtatja az elfogókat elkülönített környezetben, és nem nyújt védelmet a rosszindulatú gazdagéppel szemben. A védett ügynökfolyamatot megkerülő kódelérési útvonalak nincsenek lefedve.
  • Az elfogó rendelkezésre állása befolyásolja az ügynök rendelkezésre állását: Kényszerített módban az elfogó meghibásodása vagy időtúllépése szándékosan blokkolja a védett műveletet.

Az éles üzembe helyezésről, a hibák okairól és a riasztásokról az Agent Hooks műveleti runbookja nyújt útmutatást.

Az Agent Hooks még nem érhető el a Go számára. Az ügynökközvetítő, az eszközjóváhagyás és az ügynökbiztonság használatával futtatókörnyezeti vezérlőket adhat hozzá a Go-ügynökökhöz.

Következő lépések

Az ügynökfolyamat ismertetése

Kapcsolódó tartalom

  • Last updated on