Haki agentów

Agent Hooks to najwyższej klasy funkcja platformy Agent Framework do stosowania kontroli ładu i środowiska uruchomieniowego w dobrze zdefiniowanych punktach wykonywania agenta. Implementuje ona kontrakt AGENT-HOOKS-0.1 neutralny pod względem struktury, dzięki czemu aparaty zasad, bramy zatwierdzania, strażniki budżetu, filtry zawartości i ruch wychodzący mogą być przeznaczone dla jednej wspólnej powierzchni sterowania.

Ważna

Agent Hooks to płaszczyzna sterowania, a nie płaszczyzna telemetrii. Każdy przechwytujący zwraca werdykt. W enforce trybie struktura działa na tym werdykcie; w evaluate_only trybie rejestruje werdykt bez zmiany wykonania. Użyj możliwości obserwowania w przypadku śledzenia pasywnego, metryk i dzienników.

Agent Hooks nie jest jeszcze dostępny dla .NET. Użyj oprogramowania pośredniczącego agenta, zatwierdzania narzędzi i bezpieczeństwa agenta, aby dodać kontrolki środowiska uruchomieniowego do agentów .NET.

Agent Hooks jest eksperymentalny w Python. Fabryka emituje ExperimentalWarning element po pierwszym użyciu, a jego interfejs API może ulec zmianie przed ogólną dostępnością.

Kiedy używać punktów zaczepienia agenta

Użyj elementów Agent Hooks, gdy niezależnie opracowane kontrolki wymagają jednego współużytkowanego, możliwego do wymuszenia kontraktu między danymi wejściowymi agenta, wywołaniami modelu, wywołaniami narzędzi i końcowymi danymi wyjściowymi.

Zdolność	Użyj go do
Haki agentów	Ustandaryzowane decyzje dotyczące zasad, przekształcenia, zatwierdzenia, budżety i elementy kontroli ruchu wychodzącego w całym cyklu życia agenta.
Oprogramowanie pośredniczące agenta	Zachowanie krzyżowe specyficzne dla aplikacji, które nie wymaga kontraktu punktów zaczepienia agenta ani jego podstawowych gwarancji środowiska uruchomieniowego.
Zabezpieczenia dla agenta z FIDES	Deterministyczne etykiety i zasady przepływu informacji dla niezaufanej lub poufnej zawartości.
Zatwierdzanie narzędzi	Ludzkie potwierdzenie poszczególnych wywołań narzędzi funkcji.
Obserwowalność	Pasywne ślady, metryki i dzienniki, które nie kontrolują wykonywania.

Co wymusza struktura agentów

Po dodaniu punktów zaczepienia agenta do agenta platforma Agent Framework stosuje skoordynowaną granicę wymuszania między przebiegami agentów, wywołaniami modelu i wywołaniami narzędzi. Środowisko uruchomieniowe zapewnia następujące gwarancje:

• Niepowodzenie zamknięte: Odmowa blokuje chronioną akcję. Nieprawidłowe konteksty, nieprawidłowe werdykty, błędy przechwytywania i błędy wymuszania nie pomijają dyskretnie kontrolek.
• Przekształć zapis zwrotny: Przekształcenie zmienia komunikaty natywne, argumenty narzędzi, wyniki narzędzia lub ostateczną odpowiedź, która rzeczywiście używa wykonania. Jeśli nie można zastosować przekształcenia, uruchomienie zakończy się niepowodzeniem.
• Przesyłanie strumieniowe buforowane: Żadna aktualizacja odpowiedzi nie dociera do elementu wywołującego, dopóki kompletna odpowiedź modelu i końcowe dane wyjściowe przejdą punkty przechwytywania.
• Trwałość z bramą werdyktu: Trwałość czeka na werdykt, który go obejmuje. Standardowe oczekiwanie na outputtrwałość po uruchomieniu ; trwałość historii wywołań dla poszczególnych usług czeka na każdy post_model_callelement .
• Kompletna instalacja pakietu: Części agenta, czatu i funkcji są instalowane jako jedna jednostka, więc niekompletna granica wymuszania nie może zostać przypadkowo skonfigurowana.

Umowa jest spółdzielnią, a nie granicą izolacji procesów. Przechwytniki są uruchamiane w procesie hosta i odbierają zawartość wymaganą do podejmowania decyzji. Rejestruj tylko przechwytniki, którym ufasz.

Instalowanie punktów zaczepienia agenta

Zainstaluj opcjonalny agent-hooks dodatkowy pakiet podstawowy:

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

Jeśli używasz uv:

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

Zależność agent-hooks-sdk jest importowana z opóźnieniem. Importowanie agent_framework nie powoduje załadowania zestawu SDK, chyba że tworzysz pakiet oprogramowania pośredniczącego Agent Hooks.

Note

Dodatek agent-hooks nie jest celowo uwzględniony w pliku agent-framework-core[all]. Zainstaluj ją jawnie, gdy chcesz włączyć tę eksperymentalną powierzchnię sterowania.

Dodawanie przechwytywania

Przechwytujący odbiera agent_hooks.AgentContext (mapowanie kontekstu specyfikacji, a nie agent_framework.AgentContext używane przez oprogramowanie pośredniczące agenta) i zwraca werdykt. Następujące dane wyjściowe przechwytywania blokują końcowe dane wyjściowe zawierające wyraz secret. W tym przykładzie przyjęto założenie, że client jest już skonfigurowanym klientem czatu platformy 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}")

Przekaż pakiet jako jeden element listy agenta middleware . Zainstaluj dokładnie jeden pakiet punktów zaczepienia agenta na każdym agencie.

Punkty przechwytywania

Struktura agenta automatycznie emituje odpowiednie punkty przechwytywania:

Punkt przechwytywania	Kiedy jest emitowany	Przekształć element docelowy
agent_startup	Przed pierwszym wejściem w sesji punktów zaczepienia agenta	Nie można przekształcić
input	Gdy żądanie zewnętrzne wprowadza agenta	Zawartość wejściowa i rola
pre_model_call	Przed każdym żądaniem modelu	Komunikaty wysyłane do modelu
post_model_call	Po każdej pełnej odpowiedzi modelu	Zawartość odpowiedzi, wywołania narzędzi wykonywane przez platformę i przyczyna zakończenia
pre_tool_call	Przed wywołaniem każdego narzędzia wykonanego przez platformę	Argumenty narzędzia
post_tool_call	Po pomyślnym wykonaniu lub niepodaniu narzędzia	Wynik narzędzia
output	Zanim ostateczna odpowiedź osiągnie obiekt wywołujący	Końcowa zawartość odpowiedzi
agent_shutdown	Gdy sesja punktów zaczepienia agenta zakończy się niepowodzeniem lub zostanie anulowana	Nie można przekształcić

Uruchomienie, które wywołuje narzędzie, zwykle emituje:

agent_startup input → → post_tool_callpre_tool_callpost_model_callpre_model_callpre_model_call → → → → → post_model_call → → outputagent_shutdown

Werdykty

Umowa ma trzy decyzje: allow, denyi transform. Zestaw SDK Python udostępnia również pomocników dla ostrzeżeń i odmowy zniesienia.

Result	Interfejs programistyczny Python	Behavior
Allow	ALLOW lub Verdict(decision=Decision.ALLOW)	Kontynuuj pracę z obiektem docelowym bez zmian.
Zezwalaj z ostrzeżeniem	Verdict.warn(...)	Kontynuuj i uwzględnij ostrzeżenie w rekordzie przechwytywania.
Deny	Verdict.deny(...)	Blokuj chronioną akcję.
Odmów oczekujące na zatwierdzenie	Verdict.escalate(...)	Blokuj, chyba że skonfigurowany program rozpoznawania zatwierdzenia zwraca werdykt zezwolenia.
Przekształć	Verdict(decision=Decision.TRANSFORM, transform=Transform(...))	Ponownie zapisz wartość w obszarze $target, a następnie kontynuuj odpisaną wartość.

Błędy InterceptionBlocked na poziomie uruchamiania i na poziomie modelu uniemożliwiają uzyskanie chronionego wyniku do obiektu wywołującego lub następnego etapu. Na szwach narzędzia odmowa zasad uniemożliwia działanie narzędzia lub odrzuca jego wynik i zwraca błąd kontroli zawierający przyczynę zasad bez odmowy ładunku docelowego do modelu. Umożliwia to kontynuowanie pętli agenta. Host lub niepowodzenie wymuszania zatrzymuje przebieg.

Stosowanie przekształcenia

Ścieżka przekształcenia musi zaczynać się od $target. Na przykład przechwytujący może zastąpić końcową zawartość odpowiedzi:

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

Przekształcenia są stosowane do wartości struktury Content agentów, zachowując obsługiwaną zawartość sformatowaną, a nie zmniejszając każdą wartość do zwykłego tekstu. Źle sformułowana ścieżka lub niezgodne zastąpienie kończy się niepowodzeniem zamiast kontynuować oryginalną wartość.

Zatwierdzanie narzędzi i przekształcenia argumentów

Zatwierdzanie narzędzia Agent Framework i szew zatwierdzania zapinania agentów są oddzielnymi mechanizmami. W przypadku narzędzia funkcji z approval_mode="always_require"programem , program Agent Framework tworzy żądanie zatwierdzenia przez człowieka przed uruchomieniem oprogramowania pośredniczącego funkcji. W pre_tool_call związku z tym przekształcenie może zmieniać argumenty po zatwierdzeniu przez użytkownika oryginalnych wartości.

Warning

Nie przekształcaj argumentów dla pre_tool_call narzędzi korzystających z polecenia approval_mode="always_require". Przekształć wywołanie narzędzia, post_model_call aby żądanie zatwierdzenia platformy zawiera przekształcone wartości lub zwróciło Verdict.escalate(...) się do pre_tool_call i rozwiązało zatwierdzenie za pośrednictwem punktów zaczepienia agenta resolver.

Przesyłanie strumieniowe i trwałość

Punkty zaczepienia agenta utrzymują interfejs API przesyłania strumieniowego, ale używają semantyki buforowanych danych wyjściowych. Struktura agenta tworzy kompletną odpowiedź modelu, emituje post_model_call, tworzy ostateczną odpowiedź agenta i emituje output przed wydaniem aktualizacji. Jeśli którykolwiek z punktów odmówi odpowiedzi, obiekt wywołujący nie otrzyma żadnych częściowych aktualizacji.

To zachowanie powoduje wymianę opóźnienia tokenu po tokenie w przypadku wymuszania danych wyjściowych zamkniętych w trybie fail-closed. Przekształcenie danych wyjściowych zostanie również odzwierciedlone w aktualizacjach ostatecznie wydanych do obiektu wywołującego.

Trwałość jest bramowana przez punkt przechwytywania, który obejmuje operację trwałości:

• Domyślnie historia i inne działania dostawcy po uruchomieniu czekają na werdykt output . Odrzucone dane wyjściowe nie są utrwalane, a transformacja wyjściowa jest utrwalana po przekształceniu.
• Po ustawieniu require_per_service_call_history_persistence=True konstruktora Agent lub client.as_agent(...)każda wymiana modelu jest utrwalana po post_model_call jego werdykcie zezwala. Późniejsza output odmowa nie cofa, że już dozwolona historia.
• W przypadku domyślnej trwałości po uruchomieniu próby ponawiania próby pozostają za ostateczną output decyzją. Zamiast tego tryb wywołania poszczególnych usług utrwala każdą odpowiedź modelu, która przekazuje post_model_callwartość .

Ważna

Jeśli zawartość modelu nie może stać się trwała, wymuś te zasady w momencie post_model_call , gdy require_per_service_call_history_persistence=True. Zasady ruchu wychodzącego tylko do danych wyjściowych chronią, co dociera do obiektu wywołującego, ale nie powoduje retroaktywnego usuwania wymiany modeli, które są już dozwolone i utrwalane w obiekcie post_model_call.

Sesje i rekordy inspekcji

Domyślnie każdy przebieg agenta tworzy jedną sesję punktów zaczepienia agenta. agent_startup i agent_shutdown nawiasy przebiegu, a rekordy otrzymują jeden identyfikator sesji z monotonicznie rosnącą sekwencją.

Użyj record_sink polecenia , aby odebrać każdy InterceptionRecordz nich:

records = []

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

Przechwycenie rekordów przechwytuje decyzję, przyczynę, podsumowanie przechwytywania, tryb, tożsamość i sekwencję bez kopiowania przechwyconego ładunku do rekordu inspekcji. Sam przechwytywanie nadal otrzymuje pełny kontekst.

Obejmuje wiele uruchomień z jedną sesją

Użyj create_agent_hooks_middleware_from_emitter() , gdy aplikacja jest właścicielem dłuższej sesji Agent Hooks, takiej jak konwersacja z jednym rejestrem zatwierdzania:

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

W tym formularzu aplikacja konfiguruje emiter i jest właścicielem uruchamiania, zamykania i oczyszczania błędów. Oprogramowanie pośredniczące emituje punkty na przebieg od input do .output

Konfigurowanie wymuszania

create_agent_hooks_middleware() akceptuje następujące kontrolki:

Parametr	Purpose
interceptors	Sekwencja przechwytywania lub mapowania przechwytywania nazw na przechwyt. Wymagany jest co najmniej jeden.
resolver	Rozwiązuje problemy z odmową zniesienia za pośrednictwem kanału zatwierdzania. Bez rozwiązania odmowa pozostaje w mocy.
mode	"enforce" stosuje werdykty. "evaluate_only" rejestruje, co się stanie, ale zezwala na każdą akcję.
composition	Wybiera sposób łączenia wielu werdyktów przechwytywania.
identity_provider	Tworzy tożsamości kontekstowe powiązane z zawartością. Wartość domyślna to "jcs-sha256".
timeout	Limit czasu per-interceptor i resolver dla oczekujących wywołań. Wartość domyślna to pięć sekund. Synchroniczny przechwytywanie lub rozpoznawanie, które blokuje pętlę zdarzeń, nie może zostać wywłaszczone przez ten limit czasu.
record_sink	Odbiera każdy rekord przechwytywania bez ładunku.

Domyślna kompozycja jest sekwencyjny first_deny z zatwierdzeniem skonfigurowanym do zatrzymania składania. W związku z tym kolejność przechwytywania ma znaczenie: należy umieścić kontrolki, które muszą być zawsze uruchamiane przed kontrolkami, które mogą żądać zatwierdzenia. Przed wybraniem innego profilu kompozycji zobacz listę kontrolną produkcji Agent Hooks.

Wdrażanie w trybie tylko do oceny

Użyj evaluate_only polecenia , aby zmierzyć zachowanie zasad przed wymuszaniem:

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

W tym trybie przechwytywanie uruchamiane i rekordy obejmują ich werdykty, ale żadna akcja nie jest blokowana ani przekształcana. Nie opisywaj wdrożenia jako wymuszonego evaluate_only ładu.

Reguły kompozycji

Umieść pakiet najpierw na liście oprogramowania pośredniczącego agenta, aby stanowił najbardziej zewnętrzną granicę wymuszania:

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

Postępuj zgodnie z następującymi regułami:

• Zainstaluj dokładnie jeden pakiet punktów zaczepienia agenta na agenta. Skumulowane pakiety są odrzucane.
• Zachowaj nienaruszony pakiet. Nie można zainstalować oddzielnie agenta, czatu i oprogramowania pośredniczącego funkcji.
• Zainstaluj pakiet w programie Agent, a nie bezpośrednio na kliencie czatu lub za pośrednictwem dostawcy kontekstu.
• Oprogramowanie pośredniczące umieszczone przed pakietem znajduje się poza granicą wymuszania. Traktuj pozycję zewnętrzną jako zaufanie zewnętrzne.
• Nadaj każdemu zagnieżdżonemu agentowi własny pakiet, gdy jego wewnętrzny model i działanie narzędzia również wymaga przechwycenia.

Bieżące ograniczenia

• Python tylko: w .NET lub zestawach SDK języka Go nie zaimplementowano jeszcze punktów zaczepienia agenta.
• Eksperymentalny interfejs API: Podpisy i zachowanie fabryki mogą ulec zmianie przed ogólną dostępnością.
• Przesyłanie strumieniowe buforowane: Aktualizacje nie są zwalniane tokenem przez token, ponieważ dane wyjściowe muszą zostać ukończone przed zamknięciem werdyktu zakończonego niepowodzeniem.
• Narzędzia hostowane: Narzędzia wykonywane przez dostawcę modelu nie przechodzą przez szew wywołania funkcji programu Agent Framework. Ich wywołania i dane wyjściowe są udostępniane w systemie post_model_call, post_tool_call ale pre_tool_call nie mogą blokować wykonywania po stronie serwera dostawcy.
• Granica współpracy: Agent Hooks nie przechwytuje piaskownicy ani nie chroni przed wrogim hostem. Ścieżki kodu pomijające chroniony potok agenta nie są omówione.
• Dostępność przechwytywania wpływa na dostępność agenta: W trybie wymuszania awaria przechwytywania lub przekroczenie limitu czasu blokuje chronioną akcję zgodnie z projektem.

Aby uzyskać informacje o wdrożeniu produkcyjnym, przyczynach awarii i wskazówkach dotyczących alertów, zobacz element Runbook operacji punktów zaczepienia agenta.

Agent Hooks nie jest jeszcze dostępny dla języka Go. Użyj oprogramowania pośredniczącego agenta, zatwierdzania narzędzi i bezpieczeństwa agenta , aby dodać kontrolki środowiska uruchomieniowego do agentów języka Go.

Następne kroki

Omówienie potoku agenta

Treści powiązane

• Oprogramowanie pośredniczące agenta
• Bezpieczeństwo agenta
• Zatwierdzanie narzędzi
• Zabezpieczenia dla agenta z FIDES
• Obserwowalność
• Specyfikacja AGENT-HOOKS-0.1