Agentanslutningar

Agent Hooks är en förstklassig Agent Framework-funktion för att tillämpa styrnings- och körningskontroller på väldefinierade punkter i en agentkörning. Det implementerar det ramverksneutrala AGENT-HOOKS-0.1-kontraktet, så principmotorer, godkännandegatewayer, budgetskydd, innehållsfilter och utgående kontroller kan rikta in sig på en gemensam kontrollyta.

Important

Agent Hooks är ett kontrollplan, inte ett telemetriplan. Varje interceptor returnerar en dom. I enforce läge agerar ramverket på den domen. I evaluate_only läge registrerar det domen utan att ändra körningen. Använd observerbarhet för passiv spårning, mått och loggar.

Agentkrokar är ännu inte tillgängliga för .NET. Använd agentmellanprogram, verktygsgodkännande och agentsäkerhet för att lägga till körningskontroller till .NET agenter.

Agent Hooks är experimentell i Python. Fabriken genererar en ExperimentalWarning när den först används och dess API kan ändras före allmän tillgänglighet.

När du ska använda Agent Hooks

Använd Agent Hooks när oberoende utvecklade kontroller behöver ett delat, verkställbart kontrakt mellan agentindata, modellanrop, verktygsanrop och slutliga utdata.

Förmåga	Använd den för
Agentkrokar	Standardiserade principbeslut, transformeringar, godkännanden, budgetar och utgående kontroller i agentens livscykel.
Mellanprogram för agent	Programspecifikt övergripande beteende som inte behöver Agent Hooks-kontraktet eller dess grundläggande körningsgarantier.
Agentsäkerhet med FIDES	Deterministiska informationsflödesetiketter och principer för obetrott eller konfidentiellt innehåll.
Godkännande av verktyg	Mänsklig bekräftelse av enskilda funktionsverktygsanrop.
Observerbarhet	Passiva spårningar, mått och loggar som inte styr körningen.

Vad Agent Framework framtvingar

När du lägger till Agent Hooks i en agent tillämpar Agent Framework en samordnad tillämpningsgräns mellan agentkörningar, modellanrop och verktygsanrop. Körningen ger följande garantier:

Misslyckades stängt: En neka blockerar den skyddade åtgärden. Ogiltiga kontexter, ogiltiga domar, skärningspunktsfel och tvingande fel kringgår inte kontroller tyst.
Transformera tillbakaskrivning: En transformering ändrar de inbyggda meddelandena, verktygsargumenten, verktygsresultaten eller det slutliga svar som körningen faktiskt använder. Om en transformering inte kan tillämpas avslutas körningen.
Buffrad direktuppspelning: Ingen svarsuppdatering når anroparen förrän det fullständiga modellsvaret och de slutliga utdata har passerat sina avlyssningspunkter.
Bedömningsgrindad beständighet: Beständighet väntar på domen som täcker det. Standardefterkörningspersistence outputväntar på ; per tjänst-anropshistorik väntar på varje post_model_call.
Fullständig paketinstallation: Agent-, chatt- och funktionsdelarna installeras som en enhet, så en ofullständig tillämpningsgräns kan inte konfigureras av misstag.

Kontraktet är kooperativt snarare än en processisoleringsgräns. Interceptorer körs i värdprocessen och tar emot det innehåll som behövs för att fatta beslut. Registrera bara interceptorer som du litar på.

Installera agentkrokar

Installera det valfria agent-hooks extra för kärnpaketet:

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

Om du använder uv:

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

Beroendet agent-hooks-sdk är latimporterat. agent_framework Importen läser inte in SDK:n om du inte skapar ett Agent Hooks-mellanprogrampaket.

Note

Tillägget agent-hooks ingår avsiktligt inte i agent-framework-core[all]. Installera det explicit när du vill aktivera den här experimentella kontrollytan.

Lägga till en interceptor

En interceptor tar emot en agent_hooks.AgentContext (specifikationens kontextmappning, inte den agent_framework.AgentContext som används av agentmellanprogram) och returnerar en dom. Följande interceptor blockerar slutliga utdata som innehåller ordet secret. Exemplet förutsätter client att är en redan konfigurerad Agent Framework-chattklient.

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

Skicka paketet som ett element i agentens middleware lista. Installera exakt ett Agent Hooks-paket på varje agent.

Avlyssningspunkter

Agent Framework genererar tillämpliga avlyssningspunkter automatiskt:

Avlyssningspunkt	När den genereras	Transformera mål
`agent_startup`	Före den första inmatningen i en Agent Hooks-session	Kan inte transformeras
`input`	När en extern begäran anger agenten	Indatainnehåll och roll
`pre_model_call`	Före varje modellbegäran	Meddelanden som skickas till modellen
`post_model_call`	Efter varje fullständigt modellsvar	Svarsinnehåll, ramverksdrivna verktygsanrop och slutorsak
`pre_tool_call`	Före varje ramverkskörning av verktygsanrop	Verktygsargument
`post_tool_call`	När ett verktyg har lyckats eller misslyckas	Verktygsresultat
`output`	Innan det slutliga svaret når anroparen	Slutligt svarsinnehåll
`agent_shutdown`	När Agent Hooks-sessionen är klar, misslyckas eller avbryts	Kan inte transformeras

En körning som anropar ett verktyg genererar vanligtvis:

agent_startup input → → pre_model_call → post_model_call → pre_tool_call → post_tool_call → pre_model_call → post_model_call → output →agent_shutdown

Domar

Kontraktet har tre beslut: allow, denyoch transform. den Python SDK ger också hjälp för varningar och liftable nekar.

Result	Python API	Behavior
Allow	`ALLOW` eller `Verdict(decision=Decision.ALLOW)`	Fortsätt med målet oförändrat.
Tillåt med varning	`Verdict.warn(...)`	Fortsätt och inkludera varningen i avlyssningsposten.
Deny	`Verdict.deny(...)`	Blockera den skyddade åtgärden.
Neka väntande godkännande	`Verdict.escalate(...)`	Blockera om inte den konfigurerade godkännandelösaren returnerar en tillståndsutlåtande.
Omvandla	`Verdict(decision=Decision.TRANSFORM, transform=Transform(...))`	Skriv om ett värde under `$target`och fortsätt sedan med det omskrivna värdet.

Körningsnivå och modellnivå nekar höjning InterceptionBlocked och förhindrar att det skyddade resultatet når anroparen eller nästa steg. I en verktygssöm förhindrar en princip den verktygsåtgärden eller tar bort resultatet och returnerar ett kontrollfel som innehåller principorsaken, utan den nekade målnyttolasten, till modellen. Detta gör att agentloopen kan fortsätta. Ett värd- eller tvingande fel stoppar körningen.

Tillämpa en transformering

En transformeringssökväg måste starta vid $target. En interceptor kan till exempel ersätta det slutliga svarsinnehållet:

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

Transformeringar tillämpas på Agent Framework-värden Content , vilket bevarar innehåll som stöds i stället för att minska varje värde till oformaterad text. En felaktig sökväg eller inkompatibel ersättning avslutas inte i stället för att fortsätta med det ursprungliga värdet.

Verktygsgodkännande och argumenttransformering

Agent Framework-verktygsgodkännande och Agent Hooks-godkännandesömmen är separata mekanismer. För ett funktionsverktyg med approval_mode="always_require"skapar Agent Framework begäran om mänskligt godkännande innan funktionens mellanprogram körs. En pre_tool_call transformering kan därför ändra argument efter att användaren godkänt de ursprungliga värdena.

Warning

Transformera inte argument för pre_tool_call verktyg som använder approval_mode="always_require". Transformera verktygsanropet så post_model_call att begäran om ramverksgodkännande innehåller transformerade värden eller returnerar Verdict.escalate(...) vid pre_tool_call och löser godkännande via Agent Hooks resolver.

Strömning och beständighet

Agent Hooks behåller api:et för direktuppspelning men använder buffrad utdatasemantik. Agent Framework sammanställer det fullständiga modellsvaret, genererar post_model_call, sammanställer det slutliga agentsvaret och genererar output innan uppdateringar släpps. Om någon av dessa punkter nekar svaret får anroparen inga partiella uppdateringar.

Det här beteendet handlar token-by-token-svarstid för utdata som inte har stängts. En utdatatransformering återspeglas också i uppdateringarna som slutligen släpps till anroparen.

Beständighet är gated av avlyssningspunkten som täcker beständighetsåtgärden:

Som standard väntar historik och annan efterkörningsprovider på output domen. En nekad utdata sparas inte och en utdatatransformering sparas efter omvandlingen.
När du ställer in require_per_service_call_history_persistence=True på Agent konstruktorn eller client.as_agent(...)sparas varje modellutbyte efter att dess post_model_call utlåtande tillåter det. Ett senare output nekande återställer inte den redan tillåtna historiken.
För standardpersistence efter körning ligger återförsöken kvar bakom det slutliga output beslutet. Samtalsläget per tjänst bevarar i stället varje modellsvar som skickar post_model_call.

Important

Om modellinnehållet inte får bli beständigt framtvingar du principen när post_model_callrequire_per_service_call_history_persistence=True. En utgående utgående princip för endast utdata skyddar det som når anroparen, men den tar inte retroaktivt bort modellutbyten som redan är tillåtna och beständiga på post_model_call.

Sessioner och granskningsposter

Som standard skapar varje agentkörning en Agent Hooks-session. agent_startup och agent_shutdown hakparenteser körningen, och poster tar emot ett sessions-ID med en monotont ökande sekvens.

Använd record_sink för att ta emot varje InterceptionRecord:

records = []

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

Avlyssningsposter samlar in beslut, orsak, sammanfattning av interceptor, läge, identitet och sekvens utan att kopiera den avlyssnade nyttolasten till granskningsposten. Själva interceptorn tar fortfarande emot hela kontexten.

Sträcka sig över flera körningar med en session

Använd create_agent_hooks_middleware_from_emitter() när programmet äger en längre Agent Hooks-session, till exempel en konversation med ett godkännanderegister:

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

I det här formuläret konfigurerar programmet emittern och äger start, avstängning och felrensning. Mellanprogrammet genererar punkterna per körning från till och med inputoutput.

Konfigurera tvingande

create_agent_hooks_middleware() accepterar följande kontroller:

Parameter	Purpose
`interceptors`	En sekvens med interceptorer eller en namn-till-interceptor-mappning. Minst en krävs.
`resolver`	Löser liftable-nekanden via en godkännandekanal. Utan en lösen förblir nekandet i kraft.
`mode`	`"enforce"` tillämpar domar. `"evaluate_only"` registrerar vad som skulle hända men tillåter varje åtgärd.
`composition`	Väljer hur flera avlyssningsutslag kombineras.
`identity_provider`	Skapar innehållsbundna kontextidentiteter. Standardvärdet är `"jcs-sha256"`.
`timeout`	Tidsgränsen per interceptor och matchare för väntande anrop. Standardvärdet är fem sekunder. En synkron interceptor eller matchare som blockerar händelseloopen kan inte föregripas av den här tidsgränsen.
`record_sink`	Tar emot varje nyttolastfri avlyssningspost.

Standardsammansättningen är sekventiell first_deny med godkännande konfigurerat för att stoppa vikningen. Interceptor-ordningen är därför viktig: placera kontroller som alltid måste köras före kontroller som kan begära godkännande. Se checklistan för Agent Hooks-produktion innan du väljer en annan sammansättningsprofil.

Distribuera med endast utvärderingsläge

Använd evaluate_only för att mäta principbeteende före tillämpning:

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

I det här läget innehåller interceptor-körning och poster deras domar, men ingen åtgärd blockeras eller transformeras. Beskriv inte en evaluate_only distribution som framtvingad styrning.

Sammansättningsregler

Placera paketet först i agentens mellanprogramslista så att det utgör den yttersta tvingande gränsen:

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

Följ dessa regler:

Installera exakt ett Agent Hooks-paket per agent. Staplade paket avvisas.
Håll paketet intakt. Dess mellanprogram för agent, chatt och funktion kan inte installeras separat.
Installera paketet på Agent, inte direkt på en chattklient eller via en kontextprovider.
Mellanprogram som placeras innan paketet ligger utanför tillämpningsgränsen. Behandla yttre position som yttre förtroende.
Ge varje kapslad agent ett eget paket när den interna modellen och verktygsaktiviteten också behöver avlyssning.

Aktuella begränsningar

endast Python: Agentkrokar har ännu inte implementerats i .NET- eller Go-SDK:erna.
Experimentellt API: Fabrikssignaturer och beteende kan ändras före allmän tillgänglighet.
Buffrad direktuppspelning: Uppdateringar släpps inte token per token eftersom utdata måste vara slutförda innan en sluten dom misslyckas.
Värdbaserade verktyg: Verktyg som körs av en modellprovider passerar inte Agent Frameworks funktionsanropssöm. Deras anrop och utdata visas i post_model_call, men pre_tool_callpost_tool_call kan inte blockera providerns körning på serversidan.
Samarbetsgräns: Agent hooks inte sandbox-skärningspunkter eller skyddar mot en fientlig värd. Kodsökvägar som kringgår den skyddade agentpipelinen omfattas inte.
Tillgängligheten för interceptor påverkar agenttillgängligheten: I framtvingat läge blockerar ett skärningspunktsfel eller tidsgräns den skyddade åtgärden avsiktligt.

Information om produktionsdistribution, felorsaker och aviseringsvägledning finns i Runbook för Agent Hooks-åtgärder.

Agent hooks är ännu inte tillgänglig för Go. Använd agentmellanprogram, verktygsgodkännande och agentsäkerhet för att lägga till körningskontroller i Go-agenter.

Nästa steg

Förstå agentpipelinen

Feedback

Var den här sidan till hjälp?

Last updated on 2026-08-14