Agenthooks

Agent Hooks is een eersteklas Agent Framework-mogelijkheid voor het toepassen van governance- en runtime-besturingselementen op goed gedefinieerde punten in de uitvoering van een agent. Het implementeert het framework-onafhankelijke AGENT-HOOKS-0.1-contract, zodat beleidsengines, goedkeuringsgateways, budgetbewaking, inhoudsfilters en egresscontroles zich op één gemeenschappelijk controlevlak kunnen richten.

Belangrijk

Agent Hooks is een besturingsvlak, geen telemetrievlak. Elke interceptor geeft een uitkomst terug. In enforce de modus handelt het framework op dat oordeel; in evaluate_only de modus wordt het oordeel vastgelegd zonder de uitvoering te wijzigen. Gebruik waarneembaarheid voor passieve tracering, metrische gegevens en logboeken.

Agent Hooks is nog niet beschikbaar voor .NET. Gebruik agent-middleware, goedkeuring van hulpprogramma's en agentveiligheid om runtime-besturingselementen toe te voegen aan .NET agents.

Agent Hooks is experimenteel voor Python. De factory geeft bij het eerste gebruik een ExperimentalWarning af en de API kan vóór algemene beschikbaarheid nog veranderen.

Wanneer gebruikt u Agent Hooks

Gebruik Agent Hooks wanneer onafhankelijk ontwikkelde besturingselementen één gedeeld, afdwingbaar contract nodig hebben tussen agentinvoer, modeloproepen, hulpprogramma-aanroepen en uiteindelijke uitvoer.

Capability	Gebruik het voor
Agent Hooks	Gestandaardiseerde beleidsbeslissingen, transformaties, goedkeuringen, budgetten en uitgaande controles gedurende de levenscyclus van de agent.
Agent-middleware	Toepassingsspecifiek cross-cutting gedrag waarvoor het Agent Hooks-contract of de kernruntimegaranties niet nodig zijn.
Agentbeveiliging met FIDES	Deterministische informatiestroomlabels en -beleid voor niet-vertrouwde of vertrouwelijke inhoud.
Goedkeuring van hulpprogramma's	Menselijke bevestiging van afzonderlijke functiehulpmiddelaanroepen.
Observatievermogen	Passieve traceringen, metrische gegevens en logboeken die geen controle hebben over de uitvoering.

Wat het agentframework afdwingt

Wanneer u Agent Hooks toevoegt aan een agent, past Agent Framework een gecoördineerde afdwingingsgrens toe over agentuitvoeringen, modelaanroepen en toolaanroepen. De runtime biedt de volgende garanties:

Mislukt gesloten: Een weigering blokkeert de bewaakte actie. Ongeldige contexten, ongeldige beoordelingen, fouten in interceptors en afdwingingsfouten omzeilen controles niet ongemerkt.
Transformatie voor terugschrijven: Een transformatie wijzigt de oorspronkelijke berichten, toolargumenten, toolresultaten of het uiteindelijke antwoord die daadwerkelijk door de uitvoering worden gebruikt. Als een transformatie niet kan worden toegepast, mislukt de uitvoering.
Gebufferde streaming: Geen update van het antwoord bereikt de aanroepende partij totdat het volledige modelantwoord en de uiteindelijke uitvoer hun onderscheppingspunten hebben gepasseerd.
Uitspraakgestuurde persistentie: Persistentie wacht op de uitspraak die erop van toepassing is. Standaardpersistentie na afloop wacht op output; geschiedenispersistentie per serviceaanroep wacht op elke post_model_call.
Installatie van bundel voltooien: De agent-, chat- en functieonderdelen worden als één eenheid geïnstalleerd, zodat een onvolledige afdwingingsgrens niet per ongeluk kan worden geconfigureerd.

Het contract is coöperatief in plaats van een procesisolatiegrens. Interceptors worden uitgevoerd in het hostproces en ontvangen de benodigde inhoud om beslissingen te nemen. Registreer alleen interceptors die u vertrouwt.

Agenthook installeren

Installeer de optionele agent-hooks extra voor het kernpakket:

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

Als u het volgende gebruikt uv:

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

De agent-hooks-sdk afhankelijkheid wordt lui geïmporteerd. Door agent_framework te importeren wordt de SDK niet geladen, tenzij u een middlewarebundel voor Agent Hooks maakt.

Opmerking

Het agent-hooks extra is bewust niet opgenomen in agent-framework-core[all]. Installeer deze expliciet wanneer u dit experimentele besturingsoppervlak wilt inschakelen.

Een interceptor toevoegen

Een interceptor ontvangt een agent_hooks.AgentContext (de contexttoewijzing van de specificatie, niet de agent_framework.AgentContext die door agent-middleware wordt gebruikt) en geeft een oordeel terug. De volgende interceptor blokkeert uiteindelijke uitvoer die het woord secret bevat. In het voorbeeld wordt ervan uitgegaan dat client het een al geconfigureerde Agent Framework-chatclient is.

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

Geef de bundel door als een element van de middleware-lijst van de agent. Installeer precies één Agent Hooks-bundel op elke agent.

Interceptiepunten

Agent Framework verzendt automatisch de toepasselijke interceptiepunten:

Snijpunt	Wanneer deze wordt verzonden	Doel transformeren
`agent_startup`	Vóór de eerste invoer in een Agent Hooks-sessie	Niet te transformeren
`input`	Wanneer een externe aanvraag de agent binnenkomt	Invoerinhoud en -rol
`pre_model_call`	Vóór elke modelaanvraag	Berichten die naar het model worden verzonden
`post_model_call`	Na elk volledig modelantwoord	Inhoud van het antwoord, door het framework uitgevoerde toolaanroepen en reden van voltooiing
`pre_tool_call`	Voordat elk door het framework uitgevoerde hulpprogramma wordt aangeroepen	Toolargumenten
`post_tool_call`	Nadat een hulpprogramma is geslaagd of mislukt	Resultaat van hulpprogramma
`output`	Voordat het laatste antwoord de beller bereikt	Uiteindelijke antwoordinhoud
`agent_shutdown`	Wanneer de Agent Hooks-sessie is voltooid, mislukt of wordt geannuleerd	Niet te transformeren

Een uitvoering die een hulpprogramma aanroept, verzendt doorgaans:

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

Uitspraken

Het contract heeft drie beslissingen: allow, denyen transform. De Python SDK biedt ook hulpfuncties voor waarschuwingen en ophefbare weigeringen.

Result	PYTHON-API	Gedrag
Toestaan	`ALLOW` of `Verdict(decision=Decision.ALLOW)`	Ga door met het doel ongewijzigd.
Toestaan met waarschuwing	`Verdict.warn(...)`	Ga door en neem de waarschuwing op in de interceptierecord.
Weigeren	`Verdict.deny(...)`	Blokkeer de beveiligde actie.
Lopende goedkeuring weigeren	`Verdict.escalate(...)`	Blokkeren tenzij de geconfigureerde goedkeurings resolver een goedkeuringsbeoordeling retourneert.
Transform	`Verdict(decision=Decision.TRANSFORM, transform=Transform(...))`	Herschrijf een waarde onder `$target`en ga vervolgens verder met de herschreven waarde.

Weigeringen op runniveau en modelniveau roepen InterceptionBlocked op en voorkomen dat het beveiligde resultaat de aanroeper of de volgende fase bereikt. Op de grens met een tool voorkomt een beleidsweigering de toolactie of verwerpt zij het resultaat ervan, en retourneert zij naar het model een controlefout met de beleidsreden, zonder de payload van het geweigerde doel. Hierdoor kan de agentlus doorgaan. Een hostfout of een fout bij de afdwinging onderbreekt de uitvoering.

Een transformatie toepassen

Een transformatiepad moet beginnen bij $target. Een interceptor kan bijvoorbeeld de inhoud van het uiteindelijke antwoord vervangen:

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

Transformaties worden toegepast op Agent Framework-waarden Content, waarbij ondersteunde opgemaakte inhoud behouden blijft in plaats van elke waarde terug te brengen tot platte tekst. Een onjuist pad of incompatibele vervanging mislukt in plaats van door te gaan met de oorspronkelijke waarde.

Toolgoedkeuring en argumenttransformaties

De goedkeuring van hulpprogramma’s in Agent Framework en het goedkeuringskoppelvlak van Agent Hooks zijn twee afzonderlijke mechanismen. Voor een functietool met approval_mode="always_require" maakt Agent Framework het verzoek om menselijke goedkeuring aan voordat de functiemiddleware wordt uitgevoerd. Een pre_tool_call transformatie kan daarom argumenten wijzigen nadat de gebruiker de oorspronkelijke waarden heeft goedgekeurd.

Warning

Transformeer geen argumenten bij pre_tool_call voor hulpprogramma's die gebruikmaken van approval_mode="always_require". Transformeer de toolaanroep bij post_model_call zodat de goedkeuringsaanvraag van het framework de getransformeerde waarden bevat, of retourneer Verdict.escalate(...) bij pre_tool_call en handel de goedkeuring af via de Agent Hooks resolver.

Streaming en duurzame opslag

Agent Hooks houdt de streaming-API bij, maar maakt gebruik van semantiek met bufferuitvoer. Agent Framework stelt het volledige modelantwoord samen, verzendt post_model_call, stelt het uiteindelijke agentantwoord samen en verzendt output voordat er updates worden uitgebracht. Als een van beide punten het antwoord weigert, ontvangt de beller geen gedeeltelijke updates.

Dit gedrag ruilt token-voor-token-latentie in voor de afdwinging van fail-closed-uitvoer. Een uitvoertransformatie wordt ook weerspiegeld in de updates die uiteindelijk zijn uitgebracht voor de aanroeper.

Persistentie wordt bepaald door het interceptiepunt dat de persistentiebewerking dekt:

Standaard wachten de geschiedenis en andere nabewerkingsproviders op het output oordeel. Een geweigerde uitvoer wordt niet opgeslagen en een uitvoertransformatie wordt opgeslagen nadat de transformatie is toegepast.
Wanneer u require_per_service_call_history_persistence=True instelt in de constructor van Agent of op client.as_agent(...), wordt elke uitwisseling met het model opgeslagen nadat het oordeel van post_model_call dit toestaat. Een latere output weigering maakt die al toegestane geschiedenis niet ongedaan.
Voor standaardpersistentie na afloop blijven herhalingspogingen afhankelijk van de uiteindelijke output beslissing. De modus per serviceaanroep slaat daarentegen elk modelantwoord op dat voldoet aan post_model_call.

Belangrijk

Als modelinhoud niet persistent mag worden, handhaaft u dat beleid bij post_model_call wanneer require_per_service_call_history_persistence=True. Een alleen-uitgaand egressbeleid beschermt wat de aanroeper bereikt, maar verwijdert niet met terugwerkende kracht uitwisselingen met het model die al waren toegestaan en opgeslagen bij post_model_call.

Sessies en auditlogs

Elke agentuitvoering maakt standaard één Agent Hooks-sessie. agent_startup en agent_shutdown markeren het begin en einde van de uitvoering, en records krijgen één sessie-ID met een monotonisch oplopend volgnummer.

Gebruik record_sink om elk InterceptionRecord te ontvangen:

records = []

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

Onderscheppingsrecords leggen de beslissing, reden, interceptorsamenvatting, modus, identiteit en volgorde vast zonder de onderschepte nettolading naar de auditrecord te kopiëren. De interceptor zelf ontvangt nog steeds de volledige context.

Meerdere runs beslaan met één sessie

Gebruik create_agent_hooks_middleware_from_emitter() wanneer de toepassing een langdurigere Agent Hooks-sessie beheert, zoals een gesprek met één goedkeuringslogboek:

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

In deze vorm configureert de toepassing de zender en is zij verantwoordelijk voor het opstarten, afsluiten en het afhandelen van fouten. De middleware verstuurt de punten per uitvoering van input tot en met output.

Handhaving configureren

create_agent_hooks_middleware() accepteert de volgende besturingselementen:

Parameter	Purpose
`interceptors`	Een reeks interceptors of een naam-naar-interceptortoewijzing. Er is er minstens één vereist.
`resolver`	Lost ophefbare weigeringen op via een goedkeuringskanaal. Zonder een resolver blijft de weigering van kracht.
`mode`	`"enforce"` past oordelen toe. `"evaluate_only"` registreert wat er zou gebeuren, maar staat elke actie toe.
`composition`	Hiermee selecteert u hoe meerdere interceptor-oordelen worden gecombineerd.
`identity_provider`	Produceert inhoudsgebonden contextidentiteiten. De standaardwaarde is `"jcs-sha256"`.
`timeout`	Time-out per interceptor en resolver voor wachtende oproepen. De standaardwaarde is vijf seconden. Een synchrone interceptor of resolver die de event loop blokkeert, kan niet door deze time-out worden onderbroken.
`record_sink`	Ontvangt elk interceptierecord zonder payload.

De standaardsamenstelling is sequentieel first_deny met goedkeuring die is geconfigureerd om de vouw te stoppen. De volgorde van interceptors is daarom belangrijk: plaats controles die altijd moeten worden toegepast vóór controles die om goedkeuring kunnen vragen. Zie de checklist voor productie van Agent Hooks voordat u een ander compositieprofiel selecteert.

Uitrollen in de modus Alleen evalueren

Gebruik evaluate_only dit om het gedrag van beleid te meten vóór afdwinging:

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

In deze modus draaien interceptors en bevatten records hun beoordelingen, maar er wordt geen actie geblokkeerd of getransformeerd. Beschrijf een implementatie van evaluate_only niet als afgedwongen governance.

Samenstellingsregels

Plaats de bundel eerst in de middlewarelijst van de agent, zodat deze de buitenste grens voor handhaving vormt:

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

Volg deze regels:

Installeer precies één Agent Hooks-bundel per agent. Gestapelde bundels worden afgewezen.
Houd de bundel intact. De middleware voor de agent, chat en functie kan niet afzonderlijk worden geïnstalleerd.
Installeer de bundel op Agent, niet rechtstreeks op een chatclient of via een contextprovider.
Middleware dat vóór de bundel is geplaatst, valt buiten de afdwingingsgrens. Behandel de buitenste positie als buitenste vertrouwensrelatie.
Geef elke geneste agent een eigen bundel wanneer het interne model en de activiteit van het hulpprogramma ook onderschepping nodig heeft.

Huidige beperkingen

Python alleen: Agent Hooks is nog niet geïmplementeerd in de .NET- of Go-SDK's.
Experimentele API: Fabriekshandtekeningen en -gedrag kunnen vóór algemene beschikbaarheid worden gewijzigd.
Gebufferde streaming: Updates worden niet token voor token vrijgegeven, omdat de uitvoer volledig moet zijn voordat een fail-closed-oordeel kan worden geveld.
Gehoste hulpprogramma's: Hulpprogramma's die door een modelprovider worden uitgevoerd, passeren niet de functie-aanroepnaad van Agent Framework. Hun aanroepen en uitvoer worden weergegeven in post_model_call, maar pre_tool_call en post_tool_call kunnen de uitvoering van de provider aan de serverzijde niet blokkeren.
Coöperatieve grens: Agent Hooks plaatst interceptors niet in een sandbox en beschermt niet tegen een vijandige host. Codepaden die de afgeschermde agentpijplijn omzeilen, worden niet afgedekt.
De beschikbaarheid van de interceptor beïnvloedt de beschikbaarheid van agenten: In de afdwingingsmodus blokkeert een storing in de interceptor of een time-out de afgeschermde actie opzettelijk.

Zie het operations-runbook voor Agent Hooks voor uitrol naar productie, foutoorzaken en richtlijnen voor alarmering.

Agent Hooks is nog niet beschikbaar voor Go. Gebruik agent-middleware, goedkeuring van hulpprogramma's en agentveiligheid om runtime-besturingselementen toe te voegen aan Go-agents.

Volgende stappen

Inzicht in de agentpijplijn

Feedback

Is deze pagina nuttig?

Last updated on 2026-08-25