Pengait agen

Agent Hooks adalah kemampuan Agent Framework kelas satu untuk menerapkan kontrol tata kelola dan runtime pada titik yang ditentukan dengan baik dalam eksekusi agen. Ini mengimplementasikan kontrak AGENT-HOOKS-0.1 yang netral kerangka kerja, sehingga mesin kebijakan, gateway persetujuan, penjaga anggaran, filter konten, dan kontrol keluar dapat menargetkan satu permukaan kontrol umum.

Important

Agen Hooks adalah sarana kontrol, bukan pesawat telemetri. Setiap pencegat mengembalikan putusan. Dalam enforce mode, kerangka kerja bertindak atas putusan tersebut; dalam evaluate_only mode, ia merekam putusan tanpa mengubah eksekusi. Gunakan pengamatan untuk pelacakan pasif, metrik, dan log.

Agent Hooks belum tersedia untuk .NET. Gunakan middleware agen, persetujuan alat, dan keamanan agen untuk menambahkan kontrol runtime ke agen .NET.

Agen Hooks bersifat eksperimental dalam Python. Pabrik memancarkan ExperimentalWarning saat pertama kali digunakan, dan API-nya dapat berubah sebelum ketersediaan umum.

Kapan menggunakan Agent Hooks

Gunakan Agent Hooks saat kontrol yang dikembangkan secara independen memerlukan satu kontrak bersama yang dapat diberlakukan di seluruh input agen, panggilan model, panggilan alat, dan output akhir.

Kemampuan Gunakan untuk itu
Kait Agen Keputusan kebijakan standar, transformasi, persetujuan, anggaran, dan kontrol keluar di seluruh siklus hidup agen.
Middleware agen Perilaku lintas pemotongan khusus aplikasi yang tidak memerlukan kontrak Agent Hooks atau jaminan runtime intinya.
Keamanan Agen dengan FIDES Label dan kebijakan aliran informasi deterministik untuk konten yang tidak tepercaya atau rahasia.
Persetujuan alat Konfirmasi manusia dari panggilan alat fungsi individu.
Keterlihatan Jejak pasif, metrik, dan log yang tidak mengontrol eksekusi.

Kerangka Kerja Agen apa yang diberlakukan

Saat Anda menambahkan Agent Hooks ke agen, Agent Framework menerapkan batas penegakan terkoordinasi di seluruh eksekusi agen, panggilan model, dan panggilan alat. Runtime memberikan jaminan berikut:

  • Gagal ditutup: Tolak memblokir tindakan yang dijaga. Konteks yang tidak valid, putusan yang tidak valid, kegagalan pencegat, dan kegagalan penegakan tidak secara diam-diam melewati kontrol.
  • Ubah write-back: Transformasi mengubah pesan asli, argumen alat, hasil alat, atau respons akhir yang benar-benar digunakan eksekusi. Jika transformasi tidak dapat diterapkan, eksekusi gagal ditutup.
  • Streaming buffer: Tidak ada pembaruan respons yang mencapai pemanggil sampai respons model lengkap dan output akhir melewati titik intersepsi mereka.
  • Persistensi yang terjaga putusannya: Persistensi menunggu putusan yang mencakupnya. Persistensi setelah dijalankan standar menunggu output; persistensi riwayat per panggilan layanan menunggu setiap post_model_call.
  • Penginstalan bundel lengkap: Komponen agen, obrolan, dan fungsi diinstal sebagai satu unit, sehingga batas penegakan yang tidak lengkap tidak dapat dikonfigurasi secara tidak sengaja.

Kontrak ini kooperatif daripada batas isolasi proses. Pencegat berjalan dalam proses host dan menerima konten yang diperlukan untuk membuat keputusan. Hanya mendaftarkan penyadap yang Anda percayai.

Memasang Agent Hooks

Instal ekstra opsional agent-hooks untuk paket inti:

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

Jika Anda menggunakan uv:

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

Dependensi agent-hooks-sdk diimpor malas. agent_framework Mengimpor tidak memuat SDK kecuali Anda membuat bundel middleware Agent Hooks.

Note

Ekstra agent-hooks sengaja tidak disertakan dalam agent-framework-core[all]. Instal secara eksplisit saat Anda ingin mengaktifkan permukaan kontrol eksperimental ini.

Menambahkan pencegat

Pencegat menerima agent_hooks.AgentContext (pemetaan konteks spesifikasi, bukan yang agent_framework.AgentContext digunakan oleh middleware agen) dan mengembalikan putusan. Pencegat berikut memblokir output akhir yang berisi kata secret. Contoh mengasumsikan client adalah klien obrolan Agent Framework yang sudah dikonfigurasi.

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

Teruskan bundel sebagai salah satu elemen daftar agen middleware . Instal persis satu bundel Agent Hooks pada setiap agen.

Titik intersepsi

Agent Framework memancarkan titik intersepsi yang berlaku secara otomatis:

Titik intersepsi Ketika dipancarkan Target transformasi
agent_startup Sebelum input pertama dalam sesi Agent Hooks Tidak dapat diubah
input Saat permintaan eksternal memasuki agen Memasukkan konten dan peran
pre_model_call Sebelum setiap permintaan model Pesan yang dikirim ke model
post_model_call Setelah setiap respons model lengkap Konten respons, panggilan alat yang dijalankan kerangka kerja, dan alasan selesai
pre_tool_call Sebelum setiap pemanggilan alat yang dijalankan kerangka kerja Argumen alat
post_tool_call Setelah alat berhasil atau gagal Hasil alat
output Sebelum respons akhir mencapai pemanggil Konten respons akhir
agent_shutdown Ketika sesi Agent Hooks selesai, gagal, atau dibatalkan Tidak dapat diubah

Eksekusi yang memanggil alat biasanya memancarkan:

agent_startup input → → pre_model_call → pre_tool_callpost_tool_callpost_model_call → → → → pre_model_call → → → → → outputpost_model_callagent_shutdown

Putusan

Kontrak memiliki tiga keputusan: allow, , denydan transform. SDK Python juga menyediakan pembantu untuk peringatan dan penolakan yang dapat diangkat.

Result API Python Behavior
Allow ALLOW atau Verdict(decision=Decision.ALLOW) Lanjutkan dengan target yang tidak berubah.
Izinkan dengan peringatan Verdict.warn(...) Lanjutkan dan sertakan peringatan dalam catatan intersepsi.
Deny Verdict.deny(...) Blokir tindakan yang dijaga.
Tolak persetujuan tertunda Verdict.escalate(...) Blokir kecuali penyelesai persetujuan yang dikonfigurasi mengembalikan putusan izin.
Transform Verdict(decision=Decision.TRANSFORM, transform=Transform(...)) Tulis ulang nilai di bawah $target, lalu lanjutkan dengan nilai yang ditulis ulang.

Tingkat eksekusi dan tingkat model menolak kenaikan InterceptionBlocked dan mencegah hasil yang dijaga mencapai pemanggil atau tahap berikutnya. Pada jahitan alat, kebijakan menolak tindakan alat atau membuang hasilnya dan mengembalikan kesalahan kontrol yang berisi alasan kebijakan, tanpa payload target yang ditolak, ke model. Ini memungkinkan perulangan agen untuk melanjutkan. Kegagalan host atau penegakan menghentikan eksekusi.

Menerapkan transformasi

Jalur transformasi harus dimulai dari $target. Misalnya, pencegat dapat menggantikan konten respons akhir:

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

Transformasi diterapkan ke nilai Kerangka Kerja Content Agen, mempertahankan konten kaya yang didukung daripada mengurangi setiap nilai menjadi teks biasa. Jalur yang salah bentuk atau penggantian yang tidak kompatibel gagal ditutup alih-alih melanjutkan dengan nilai asli.

Persetujuan alat dan transformasi argumen

Persetujuan alat Agent Framework dan jahitan persetujuan Agent Hooks adalah mekanisme terpisah. Untuk alat fungsi dengan approval_mode="always_require", Agent Framework membuat permintaan persetujuan manusia sebelum middleware fungsi berjalan. pre_tool_call Oleh karena itu, transformasi dapat mengubah argumen setelah pengguna menyetujui nilai asli.

Warning

Jangan ubah argumen di pre_tool_call untuk alat yang menggunakan approval_mode="always_require". Ubah panggilan post_model_call alat sehingga permintaan persetujuan kerangka kerja berisi nilai yang diubah, atau kembali Verdict.escalate(...) di pre_tool_call dan selesaikan persetujuan melalui Agent Hooks resolver.

Streaming dan persistensi

Agent Hooks menyimpan API streaming tetapi menggunakan semantik buffered-output. Agent Framework mengumpulkan respons model lengkap, memancarkan post_model_call, menyusun respons agen akhir, dan memancarkan sebelum merilis output pembaruan apa pun. Jika salah satu titik menolak respons, pemanggil tidak menerima pembaruan parsial.

Perilaku ini memperdagangkan latensi token-by-token untuk penegakan output yang gagal ditutup. Transformasi output juga tercermin dalam pembaruan yang akhirnya dirilis ke pemanggil.

Persistensi dijaga oleh titik intersepsi yang mencakup operasi persistensi:

  • Secara default, riwayat dan pekerjaan penyedia setelah dijalankan lainnya menunggu putusan output . Output yang ditolak tidak bertahan, dan transformasi output dipertahankan setelah transformasi.
  • Ketika Anda mengatur require_per_service_call_history_persistence=True pada Agent konstruktor atau client.as_agent(...), setiap pertukaran model dipertahankan setelah putusannya post_model_call mengizinkannya. Penolakan kemudian output tidak mengembalikan riwayat yang sudah diizinkan.
  • Untuk persistensi setelah dijalankan default, upaya coba lagi tetap berada di belakang keputusan akhir output . Mode panggilan per layanan sebagai gantinya mempertahankan setiap respons model yang melewati post_model_call.

Important

Jika konten model tidak boleh menjadi tahan lama, berlakukan kebijakan tersebut pada post_model_call saat require_per_service_call_history_persistence=True. Kebijakan keluar khusus output melindungi apa yang mencapai pemanggil, tetapi tidak secara retroaktif menghapus pertukaran model yang sudah diizinkan dan bertahan di post_model_call.

Sesi dan catatan audit

Secara default, setiap agen yang dijalankan membuat satu sesi Agent Hooks. agent_startup dan agent_shutdown kurung jalankan, dan rekaman menerima satu ID sesi dengan urutan yang meningkat secara monoton.

Gunakan record_sink untuk menerima masing-masing InterceptionRecord:

records = []

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

Catatan intersepsi menangkap keputusan, alasan, ringkasan pencegat, mode, identitas, dan urutan tanpa menyalin payload yang disadap ke dalam catatan audit. Pencegat itu sendiri masih menerima konteks lengkap.

Rentang beberapa eksekusi dengan satu sesi

Gunakan create_agent_hooks_middleware_from_emitter() saat aplikasi memiliki sesi Agent Hooks yang berumur lebih lama, seperti percakapan dengan satu ledger persetujuan:

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

Dalam formulir ini, aplikasi mengonfigurasi pemancar dan memiliki startup, shutdown, dan pembersihan kesalahan. Middleware memancarkan titik per-eksekusi dari input melalui output.

Mengonfigurasi penerapan

create_agent_hooks_middleware() menerima kontrol berikut:

Parameter Kegunaan
interceptors Urutan pencegat atau pemetaan nama-ke-pencegat. Setidaknya satu diperlukan.
resolver Menyelesaikan penolakan yang dapat diangkat melalui saluran persetujuan. Tanpa resolver, tolak tetap berlaku.
mode "enforce" menerapkan putusan. "evaluate_only" mencatat apa yang akan terjadi tetapi memungkinkan setiap tindakan.
composition Memilih bagaimana beberapa putusan pencegat digabungkan.
identity_provider Menghasilkan identitas konteks terikat konten. Defaultnya adalah "jcs-sha256".
timeout Per-pencegat dan batas waktu resolver untuk panggilan yang dapat ditunggu. Defaultnya adalah lima detik. Pencegat atau pemecah masalah sinkron yang memblokir perulangan peristiwa tidak dapat didahului oleh batas waktu ini.
record_sink Menerima setiap catatan intersepsi bebas payload.

Komposisi default berurutan first_deny dengan persetujuan yang dikonfigurasi untuk menghentikan lipatan. Oleh karena itu, urutan pencegat penting: menempatkan kontrol yang harus selalu berjalan sebelum kontrol yang dapat meminta persetujuan. Lihat daftar periksa produksi Agent Hooks sebelum memilih profil komposisi lain.

Peluncuran dengan mode evaluasi-saja

Gunakan evaluate_only untuk mengukur perilaku kebijakan sebelum penerapan:

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

Dalam mode ini, pencegat menjalankan dan merekam menyertakan putusan mereka, tetapi tidak ada tindakan yang diblokir atau diubah. Jangan jelaskan evaluate_only penyebaran sebagai tata kelola yang diberlakukan.

Aturan komposisi

Tempatkan bundel terlebih dahulu dalam daftar middleware agen sehingga membentuk batas penegakan terluar:

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

Ikuti aturan berikut:

  • Instal persis satu bundel Agent Hooks per agen. Bundel bertumpuk ditolak.
  • Jaga bundel tetap utuh. Agen, obrolan, dan middleware fungsinya tidak dapat diinstal secara terpisah.
  • Instal bundel pada Agent, tidak langsung pada klien obrolan atau melalui penyedia konteks.
  • Middleware ditempatkan sebelum bundel berada di luar batas penegakan. Perlakukan posisi luar sebagai kepercayaan luar.
  • Berikan setiap agen berlapis bundelnya sendiri ketika model internal dan aktivitas alatnya juga membutuhkan intersepsi.

Keterbatasan saat ini

  • Python saja: Agent Hooks belum diimplementasikan di .NET atau Go SDK.
  • API Eksperimental: Tanda tangan dan perilaku pabrik dapat berubah sebelum ketersediaan umum.
  • Streaming buffer: Pembaruan tidak dirilis token oleh token karena output harus selesai sebelum putusan gagal ditutup.
  • Alat yang dihosting: Alat yang dijalankan oleh penyedia model tidak melewati jahitan pemanggilan fungsi Agent Framework. Panggilan dan output mereka muncul di post_model_call, tetapi pre_tool_call dan post_tool_call tidak dapat memblokir eksekusi sisi server penyedia.
  • Batas kooperatif: Agent Hooks tidak mencegat kotak pasir atau melindungi dari host yang bermusuhan. Jalur kode yang melewati alur agen yang dijaga tidak tercakup.
  • Ketersediaan pencegat memengaruhi ketersediaan agen: Dalam mode terapkan, kegagalan pencegat atau batas waktu memblokir tindakan yang dijaga berdasarkan desain.

Untuk peluncuran produksi, alasan kegagalan, dan panduan pemberitahuan, lihat runbook operasi Agent Hooks.

Agent Hooks belum tersedia untuk Go. Gunakan middleware agen, persetujuan alat, dan keamanan agen untuk menambahkan kontrol runtime ke agen Go.

Langkah berikutnya

Memahami alur agen

Konten terkait

  • Last updated on