Bagikan melalui

Menambahkan Middleware

Halaman sebelumnya menunjukkan bagaimana keahlian domain dalam paket keterampilan yang dapat digunakan kembali — instruksi, materi referensi, dan skrip — menjadi unit mandiri yang dapat dimuat oleh agen apa pun sesuai permintaan. Tetapi saat Anda menerapkan agen ke produksi, kategori masalah baru muncul: masalah yang melintasi setiap interaksi, terlepas dari apa yang dilakukan oleh agen.

Anda perlu mencatat setiap permintaan dan respons. Anda memerlukan pagar pembatas yang memblokir konten berbahaya sebelum model melihatnya. Anda perlu memberlakukan batas laju, menangkap pengecualian dengan anggun, dan menyuntikkan telemetri — semua tanpa menyentuh logika inti agen. Menyalin dan menempelkan masalah ini ke dalam setiap agen (atau setiap alat, atau setiap keterampilan) tidak praktis dan menciptakan mimpi buruk dalam pemeliharaan.

Middleware memecahkan masalah ini. Middleware memungkinkan Anda membungkus alur eksekusi agen dengan perilaku yang dapat digunakan kembali yang mencegat, memodifikasi, dan memeriksa permintaan serta respons pada titik-titik yang telah ditentukan dengan baik. Anggap middleware sebagai serangkaian lapisan konsentris di sekitar agen — setiap lapisan mendapatkan kesempatan untuk bertindak pada input sebelum mencapai agen, dan pada output sebelum mencapai pemanggil.

Kapan menggunakan ini

Tambahkan middleware ke agen Anda saat:

  • Anda memerlukan pagar pembatas untuk memblokir konten berbahaya, di luar topik, atau melanggar kebijakan sebelum atau sesudah model memprosesnya.
  • Anda ingin pengelogan atau telemetri terpusat untuk semua interaksi agen tanpa memodifikasi setiap agen satu per satu.
  • Anda perlu mengubah permintaan atau respons — memperkaya perintah, mengubah output, atau mengganti hasil sepenuhnya — tanpa mengubah logika agen.
  • Anda ingin menerapkan kebijakan seperti pembatasan tarif, pemfilteran konten, atau pemeriksaan autentikasi yang berlaku untuk setiap eksekusi.
  • Anda perlu menangani pengecualian secara konsisten — mengulang kembali pada kegagalan sementara, memberikan respons alternatif yang baik, atau mencatat kesalahan untuk diagnostik.
  • Anda ingin berbagi status di seluruh alur — misalnya, melacak waktu permintaan atau mengumpulkan metrik yang dibutuhkan beberapa komponen middleware.

Petunjuk / Saran

Kerangka Kerja Agen mencakup instrumentasi bawaan untuk pelacakan dan metrik. Lihat Pengamatan untuk detailnya.

Cara kerja alur middleware

Saat Anda memanggil metode eksekusi agen Anda, permintaan tidak langsung masuk ke model. Sebaliknya, ia mengalir melalui alur lapisan middleware, yang masing-masing dapat memeriksa atau memodifikasi permintaan, mendelegasikan ke lapisan berikutnya, dan kemudian memeriksa atau memodifikasi respons dalam perjalanan kembali.

┌─────────────────────────────────────────────────────────┐
│  Caller: agent.run("What's the weather?")               │
└──────────────┬──────────────────────────────────────────┘
               ▼
┌─────────────────────────────────────────────────────────┐
│  Middleware 1 (Logging)                                  │
│  • Logs the incoming request                            │
│  • Calls next middleware                                │
│  • Logs the outgoing response                           │
└──────────────┬──────────────────────────────────────────┘
               ▼
┌─────────────────────────────────────────────────────────┐
│  Middleware 2 (Guardrails)                               │
│  • Checks input against content policy                  │
│  • If blocked → returns early with rejection message    │
│  • If allowed → calls next middleware                   │
│  • Checks output against content policy                 │
└──────────────┬──────────────────────────────────────────┘
               ▼
┌─────────────────────────────────────────────────────────┐
│  Agent core (model invocation, tool calls, etc.)        │
└─────────────────────────────────────────────────────────┘

Poin-poin penting:

  1. Setiap middleware memutuskan apakah akan melanjutkan. Middleware dapat memanggil lapisan berikutnya dalam rantai untuk dilanjutkan secara normal, atau dapat memutus alur dengan mengembalikan respons secara langsung — misalnya, ketika pengaman memblokir permintaan.
  2. Middleware melihat kedua arah. Middleware menjalankan kode sebelum mendelegasikan (untuk memeriksa atau memodifikasi input) dan setelah respons kembali (untuk memeriksa atau memodifikasi output). Ini adalah pola "bawang" klasik.
  3. Beberapa rantai middleware bersama-sama. Ketika Anda mendaftarkan beberapa komponen middleware, mereka bersarang: middleware terdaftar pertama adalah lapisan terluar, dan yang didaftarkan terakhir adalah lapisan terdalam yang paling dekat dengan agen.

Petunjuk / Saran

Untuk tampilan terperinci tentang bagaimana middleware cocok dengan alur eksekusi agen lengkap — termasuk penyedia konteks dan lapisan klien obrolan — lihat Arsitektur Alur Agen.

Apa yang dapat dilakukan middleware

Agent Framework mendukung middleware pada tiga lapisan alur — eksekusi agen, pemanggilan fungsi, dan klien obrolan — memberi Anda kontrol yang sangat detail pada titik di mana Anda memotong eksekusi. Pola umum meliputi:

Pola Example Referensi
Pagar pembatas & terminasi Memblokir konten berbahaya, membatasi panjang percakapan Penghentian & Batasan
Penanganan situasi pengecualian Coba lagi kegagalan sementara, kembalikan respons fallback Penanganan Pengecualian
Penimpaan hasil Meredaksi data sensitif, memperkaya, atau mengganti output agen Penggantian Hasil
Kondisi bersama Kirim ID permintaan atau data waktu di antara middleware Status Bersama
Konteks waktu jalan Ubah perilaku berdasarkan konfigurasi sesi, pengguna, atau setiap kali dijalankan Konteks Waktu Jalan
Cakupan Menerapkan middleware ke semua eksekusi atau hanya satu eksekusi Agen vs Lingkup Pelaksanaan

Untuk panduan lengkap menentukan dan mendaftarkan middleware, lihat Menentukan Middleware. Untuk gambaran umum arsitektur lengkap, lihat Gambaran Umum Middleware.

Pertimbangan

Pertimbangan Rincian
Pemisahan kekhawatiran Middleware memisahkan aspek lintas fungsional dari kode agen Anda, alat Anda, dan keterampilan Anda. Setiap komponen middleware memiliki satu tanggung jawab — pengelogan, pagar pembatas, penanganan kesalahan — yang dapat Anda tambahkan, hapus, atau urus ulang secara independen.
Ketergantungan pesanan Middleware membentuk rantai. Urutan Anda mendaftarkan middleware penting: middleware pengelogan yang berjalan terlebih dahulu akan melihat input mentah, sementara yang berjalan terakhir akan melihat input yang sudah dimodifikasi oleh middleware sebelumnya. Rencanakan pesanan alur Anda dengan sengaja.
Kompleksitas pemecahan masalah Saat middleware memodifikasi input atau output, penelusuran kesalahan memerlukan pemahaman alur lengkap. Respons mungkin terlihat salah bukan karena agen tetapi karena middleware mengubahnya. Middleware pencatatan log yang baik (ditempatkan di awal rantai) membantu mendiagnosis kasus-kasus ini.
Beban kinerja Setiap lapisan middleware menambahkan waktu pemrosesan ke setiap permintaan. Untuk operasi ringan seperti pencatatan, hal ini dapat diabaikan. Untuk operasi mahal seperti memanggil API moderasi konten eksternal, latensi bertambah — terutama ketika beberapa middleware tersebut dirantai.

Langkah berikutnya

Sekarang setelah agen Anda memiliki alat, keterampilan, dan middleware, langkah selanjutnya adalah penyedia konteks - komponen yang menyuntikkan memori, profil pengguna, dan pengetahuan dinamis ke jendela konteks agen sebelum setiap eksekusi.

Penyedia Konteks

Masuk lebih dalam:

  • Last updated on