Pengait agen

Agent Hooks adalah kemampuan inti dari Agent Framework untuk menerapkan kontrol tata kelola dan waktu proses pada titik-titik yang telah ditentukan secara jelas selama eksekusi agen. Ini menerapkan kontrak AGENT-HOOKS-0.1 yang netral terhadap kerangka kerja, sehingga mesin kebijakan, gateway persetujuan, pembatas anggaran, filter konten, dan kontrol lalu lintas keluar dapat menggunakan satu antarmuka kontrol umum.

Penting

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.

Capability Gunakan untuk itu
Agent Hooks Standardisasi keputusan kebijakan, transformasi, persetujuan, anggaran, dan kontrol egress di sepanjang siklus hidup agen.
Middleware agen Perilaku lintas fungsi yang spesifik untuk aplikasi dan tidak memerlukan kontrak Agent Hooks atau jaminan runtime inti.
Keamanan Agen dengan FIDES Label dan kebijakan aliran informasi deterministik untuk konten yang tidak tepercaya atau rahasia.
Persetujuan alat Konfirmasi oleh manusia atas setiap pemanggilan fungsi-alat.
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 yang terkoordinasi pada eksekusi agen, pemanggilan model, dan pemanggilan alat. Runtime memberikan jaminan berikut:

  • Gagal tertutup: Penolakan memblokir tindakan yang dilindungi. 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, proses akan gagal dalam keadaan tertutup.
  • Streaming ter-buffer: Tidak ada pembaruan respons yang diterima oleh pemanggil hingga respons model lengkap dan output akhir melewati titik intersepsi masing-masing.
  • Persistensi yang dikendalikan oleh keputusan: Persistensi menunggu keputusan yang mencakupnya. Persistensi standar setelah eksekusi menunggu output; persistensi riwayat untuk setiap 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 bersifat kooperatif, alih-alih menjadi pemisah isolasi proses. Interseptor berjalan di dalam proses host dan menerima informasi yang diperlukan untuk membuat keputusan. Hanya mendaftarkan penyadap yang Anda percayai.

Memasang Agent Hooks

Instal Agent Hooks SDK sebagai dependensi langsung:

pip install agent-hooks-sdk

Jika Anda menggunakan uv:

uv add agent-hooks-sdk

Dependensi agent-hooks-sdk diimpor hanya saat diperlukan. Mengimpor agent_framework tidak akan memuat SDK kecuali Anda membuat bundle middleware Agent Hooks.

Nota

agent-framework-core tidak menyertakan agent-hooks tambahan. Instal agent-hooks-sdk secara terpisah sebelum Anda membuat bundel middleware Agent Hooks.

Menambahkan pencegat

Sebuah interseptor menerima sebuah agent_hooks.AgentContext (pemetaan konteks spesifikasi, bukan agent_framework.AgentContext yang digunakan oleh middleware agen) dan mengembalikan keputusan. 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 dalam daftar middleware agen. Pasang tepat satu bundel Agent Hooks di setiap agen.

Titik intersepsi

Agent Framework memancarkan titik intersepsi yang berlaku secara otomatis:

Titik penyadapan Ketika dipancarkan Target transformasi
agent_startup Sebelum masukan pertama dalam sesi Agent Hooks Tidak dapat diubah
input Saat permintaan eksternal masuk ke agen Memasukkan konten dan peran
pre_model_call Sebelum setiap permintaan model Pesan yang dikirim ke model
post_model_call Setelah setiap respons lengkap dari model Isi respons, pemanggilan alat yang dijalankan oleh framework, dan alasan penyelesaian
pre_tool_call Sebelum setiap pemanggilan alat yang dijalankan oleh framework Argumen untuk alat
post_tool_call Setelah alat berhasil atau gagal Hasil dari alat
output Sebelum respons akhir mencapai pemanggil Konten respons akhir
agent_shutdown Ketika sesi Agent Hooks selesai, gagal, atau dibatalkan Tidak dapat diubah

agent_startup.tools_registered merupakan cuplikan alat run-start. Setiap pre_model_call payload mencakup alat efektif untuk panggilan model tersebut di bidang opsionalnya tools . Ini termasuk alat yang ditambahkan selama dijalankan oleh penyedia konteks, server MCP yang terhubung, atau pengungkapan progresif. Bidang dihilangkan ketika pemanggilan tidak memiliki tool atau kumpulan tool tidak dapat diproyeksikan.

Eksekusi yang memanggil alat biasanya menghasilkan:

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

Putusan

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

Hasil 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 diproteksi.
Tolak persetujuan yang 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 loop agen untuk terus berlanjut. Kegagalan pada host atau penegakan menghentikan proses eksekusi.

Batalkan proses eksekusi dari middleware fungsi

Impor MiddlewareFailure dari agent_framework. Middleware fungsi biasanya mengonversi pengecualian umum menjadi hasil kesalahan alat, lalu membiarkan loop agen berlanjut. Jika fungsi middleware tidak dapat melanjutkan dengan aman, munculkan MiddlewareFailure dari pengecualian yang mendasarinya. Runtime membatalkan proses eksekusi dan meneruskan kegagalan ke pemanggil alih-alih mengubahnya menjadi hasil alat.

Jangan menangkap MiddlewareFailure di middleware. Menangani hal tersebut memungkinkan perulangan untuk terus berjalan dan mengubah perilaku fail-closed menjadi perilaku fail-open. Agent Hooks menggunakan sinyal ini secara internal ketika lapisan penegakan function-middleware gagal. Berikan middleware fail-closed kustom secara berurutan, misalnya, middleware=[policy_middleware].

Untuk panggilan alat bersamaan, runtime membatalkan panggilan saudara dalam penerbangan sebelum menyebarkan kegagalan. Pembatalan bersifat kooperatif, jadi alat sinkron yang sudah berjalan pada utas pekerja mungkin tetap dapat menuntaskan efek sampingnya, tetapi hasilnya dibuang.

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 pada nilai Agent Framework Content, dengan mempertahankan konten berformat kaya yang didukung alih-alih mereduksi 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 mekanisme persetujuan pada Agent Hooks adalah dua mekanisme yang 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 alat pada post_model_call sehingga permintaan persetujuan kerangka kerja berisi nilai yang telah ditransformasikan, atau kembalikan Verdict.escalate(...) pada pre_tool_call dan proses persetujuan melalui hook Agen resolver.

Streaming dan persistensi

Agent Hooks tetap menggunakan API streaming, tetapi dengan semantik keluaran ter-buffer. Agent Framework menyusun respons model lengkap, menghasilkan post_model_call, menyusun respons agen akhir, dan menghasilkan output sebelum merilis pembaruan apa pun. Jika salah satu titik menolak respons, pemanggil tidak menerima pembaruan parsial.

Perilaku ini menukar latensi per token dengan penegakan output fail-closed. Transformasi output juga akan tercermin pada pembaruan yang pada akhirnya diberikan kepada pemanggil.

Persistensi dikendalikan oleh titik intersepsi yang mencakup operasi persistensi:

  • Secara bawaan, riwayat dan pekerjaan penyedia lainnya setelah proses berjalan menunggu hasil output. Output yang ditolak tidak bertahan, dan transformasi output dipertahankan setelah transformasi.
  • Ketika Anda menetapkan require_per_service_call_history_persistence=True pada konstruktor Agent atau client.as_agent(...), setiap pertukaran model disimpan setelah putusan post_model_call mengizinkannya. Penolakan yang terjadi kemudian output tidak membatalkan riwayat yang telah diizinkan sebelumnya.
  • Untuk persistensi pasca-eksekusi bawaan, percobaan ulang tetap berada setelah keputusan akhir output. Mode panggilan per layanan sebagai gantinya mempertahankan setiap respons model yang melewati post_model_call.

Penting

Jika konten model tidak boleh disimpan secara permanen, terapkan kebijakan tersebut di post_model_call saat require_per_service_call_history_persistence=True. Kebijakan egress khusus output melindungi output yang sampai ke pemanggil, tetapi tidak menghapus secara retroaktif interaksi model yang sudah diizinkan dan disimpan di post_model_call.

Sesi dan catatan audit

Secara default, setiap agen yang dijalankan membuat satu sesi Agent Hooks. agent_startup dan agent_shutdown menandai awal dan akhir proses, dan setiap rekaman menerima satu ID sesi dengan nomor urut 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 mencatat keputusan, alasan, ringkasan interseptor, mode, identitas, dan urutan tanpa menyalin payload yang diintersepsi ke dalam catatan audit. Interceptor itu sendiri masih menerima konteks lengkap.

Gunakan satu sesi untuk beberapa proses

Gunakan create_agent_hooks_middleware_from_emitter() saat aplikasi mengelola sesi Agent Hooks yang berlangsung lebih lama, seperti percakapan dengan satu catatan 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 bentuk ini, aplikasi mengonfigurasi emiter dan bertanggung jawab atas proses mulai, penghentian, dan pembersihan ketika terjadi kesalahan. Middleware menghasilkan poin tiap eksekusi dari input melalui output.

Konfigurasikan penegakan

create_agent_hooks_middleware() menerima kontrol berikut:

Parameter Kegunaan
interceptors Urutan pencegat atau pemetaan nama-ke-pencegat. Setidaknya satu diperlukan.
resolver Menangani penolakan yang dapat dicabut melalui alur persetujuan. Tanpa resolver, penolakan tetap berlaku.
mode "enforce" menerapkan putusan. "evaluate_only" mencatat apa yang akan terjadi tetapi memungkinkan setiap tindakan.
composition Menentukan bagaimana beberapa putusan interseptor digabungkan.
identity_provider Menghasilkan identitas konteks berdasarkan konten. Defaultnya adalah "jcs-sha256".
timeout Waktu tunggu untuk setiap interceptor dan resolver pada panggilan awaitable. 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 tanpa payload.

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

Luncurkan 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, interceptor berjalan dan rekaman mencakup hasil penilaiannya, tetapi tidak ada tindakan yang diblokir atau diubah. Jangan jelaskan evaluate_only penyebaran sebagai tata kelola yang diberlakukan.

Aturan komposisi

Tempatkan paket di urutan pertama dalam daftar middleware agen sehingga menjadi lapisan 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, chat, dan middleware fungsinya tidak dapat diinstal secara terpisah.
  • Instal bundel pada Agent, tidak langsung pada klien obrolan atau melalui penyedia konteks.
  • Middleware yang ditempatkan sebelum bundel berada di luar batas penegakan. Anggap posisi luar sebagai tingkat kepercayaan luar.
  • Berikan setiap agen bertingkat bundle tersendiri jika model internal dan aktivitas alatnya juga perlu diintersepsi.

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 berbasis buffer: Pembaruan tidak dikirimkan per token karena keluaran harus lengkap sebelum keputusan fail-closed dibuat.
  • Alat yang dihosting: Alat yang dijalankan oleh penyedia model tidak melewati jahitan pemanggilan fungsi Agent Framework. Panggilan dan output mereka ditampilkan di post_model_call, tetapi pre_tool_call dan post_tool_call tidak dapat memblokir eksekusi di sisi server penyedia.
  • Batas kooperatif: Agent Hooks tidak mengisolasi interceptor dalam sandbox maupun melindungi dari host berbahaya. Jalur kode yang melewati alur agen yang dijaga tidak tercakup.
  • Ketersediaan interceptor memengaruhi ketersediaan agen: Dalam mode enforcement, kegagalan interceptor atau timeout akan memblokir tindakan yang dilindungi, sesuai desain.

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

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

Langkah berikutnya

Memahami alur agen

Konten terkait

  • Last updated on