Kontrol gateway agen AI adalah aturan operasional yang menentukan apa yang boleh dipanggil agen, berapa banyak yang boleh dibelanjakan, bukti apa yang harus dicatat, dan kapan eksekusi harus dijeda, dialihkan, atau dihentikan. Tanpa kontrol tersebut, gateway agen menjadi cara yang lebih cepat untuk menyembunyikan sprawl alat, pemborosan token yang tak terkendali, dan kegagalan produksi yang tidak jelas.
Tujuannya bukan untuk membungkus setiap agen dengan proses. Tujuannya adalah membuat perilaku agen dapat diperiksa sebelum mencapai pengguna produksi. Agen dukungan yang dapat mencari pesanan, agen coding yang dapat mengedit file, dan agen keuangan yang dapat membandingkan faktur tidak seharusnya berbagi akses alat, anggaran, logging, atau kebijakan berhenti yang sama.
Gunakan panduan ini untuk mengubah aturan gateway agen AI Anda menjadi sesuatu yang benar-benar bisa diperiksa tim Anda: kebijakan yang jelas, field bukti yang diwajibkan, dan pengujian penerimaan. Sebelum peluncuran, bandingkan aturan tersebut dengan setup Flatkey Anda saat ini, termasuk akses model, routing, pelacakan penggunaan, dan detail penagihan di harga Flatkey.
Kontrol gateway agen AI dimulai dengan batas kebijakan
Gateway agen berada di antara runtime agen, API model, alat internal, dan tinjauan keuangan. Itu menjadikannya tempat yang baik untuk menstandardisasi empat keputusan:
| Area kontrol | Pertanyaan gateway | Bukti produksi |
|---|---|---|
| Penggunaan alat | Alat mana yang boleh dipanggil oleh alur kerja ini, dengan argumen apa, dan atas persetujuan siapa? | Nama alat, versi skema, argumen, status persetujuan, status hasil |
| Anggaran | Berapa banyak input, output, penalaran, alat, retry, dan fallback yang diizinkan? | Jumlah token, biaya permintaan, kunci pemilik, hasil anggaran, biaya fallback |
| Log | Apa yang terjadi, rute mana yang melayaninya, dan apa yang bisa ditinjau nanti? | ID permintaan, alur kerja, model, rute, panggilan alat, alasan berhenti, kode error |
| Kondisi berhenti | Kapan eksekusi harus selesai, dicoba ulang, meminta persetujuan, dialihkan, atau gagal tertutup? | Kondisi berhenti, alasan fallback, keputusan peninjau, status akhir |
Kontrol gateway agen AI ini harus ditinjau seperti kebijakan infrastruktur, bukan salinan prompt. Prompt dapat menjelaskan maksud, tetapi kebijakan gateway harus menegakkan apa yang terjadi saat model meminta alat sensitif, melebihi anggaran, menerima hasil alat yang tidak terduga, atau masuk ke loop.
Kontrol penggunaan alat: izinkan lebih sedikit alat daripada yang diketahui agen
Pemanggilan alat sangat kuat karena menghubungkan model ke sistem nyata. Ini juga titik ketika agen berpindah dari saran menjadi tindakan. Dokumentasi function-calling OpenAI menjelaskan panggilan alat sebagai alur multi-langkah: model meminta alat, aplikasi Anda mengeksekusinya, lalu output alat dikembalikan ke model. Dokumentasi tool-use Anthropic juga membuat Claude mengembalikan blok tool_use, dengan kode aplikasi bertanggung jawab atas eksekusi. Function calling Google Gemini juga bergantung pada fungsi yang dideklarasikan dan panggilan fungsi yang dihasilkan model.
Pola umum itu penting untuk kontrol gateway agen AI: model tidak boleh mengeksekusi alat secara langsung. Gateway atau runtime Anda harus memutuskan apakah alat yang diminta diizinkan, apakah argumennya sesuai kebijakan, apakah persetujuan diperlukan, dan apakah hasil alat aman untuk dikirim kembali.
Gunakan kebijakan alat tiga lapis:
- Katalog alat: seluruh set alat yang ada di organisasi.
- Allowlist alur kerja: set alat yang lebih kecil yang boleh dipanggil oleh rute agen tertentu.
- Pembatasan tingkat turn: alat yang tersedia untuk permintaan ini setelah pemeriksaan peran, tenant, lingkungan, anggaran, dan risiko.
Misalnya, agen dukungan pelanggan mungkin memiliki akses ke lookup_order, search_policy, dan open_ticket dalam mode normal. Agen tersebut tidak boleh menerima issue_refund, cancel_contract, atau delete_account sampai alur kerja mencapai jalur eskalasi yang disetujui.
Kontrolnya harus eksplisit:
workflow: support_resolution_agent
tool_policy:
default_mode: deny
allowed_tools:
- lookup_order
- search_policy
- open_ticket
approval_required:
- issue_refund
- cancel_subscription
blocked_tools:
- export_customer_database
schema_rules:
require_strict_arguments: true
reject_unknown_fields: true
log_redacted_arguments: true
on_violation:
action: stop
user_message: ask_for_human_review
Panduan function-calling OpenAI merekomendasikan deskripsi fungsi yang jelas, skema JSON, strict mode bila didukung, dan menjaga fungsi yang tersedia pada awalnya tetap kecil. Itu bukan hanya saran performa model. Itu juga merupakan kontrol gateway agen: semakin sedikit alat yang terekspos, semakin sedikit state tidak valid yang perlu ditinjau setelah insiden.
Kontrol anggaran: batasi seluruh eksekusi, bukan hanya satu panggilan model
Biaya agen jarang berasal dari satu permintaan yang bersih. Biaya datang dari skema alat, histori percakapan, konteks retrieval, token penalaran, hasil alat, retry, model fallback, dan upaya berulang setelah kegagalan sebagian.
Kontrol gateway agen AI berbasis anggaran harus mencakup seluruh eksekusi:
| Permukaan anggaran | Apa yang dibatasi | Mengapa ini penting |
|---|---|---|
| Anggaran permintaan | token input, token output, token penalaran, maksimum panggilan model | Mencegah satu giliran menjadi kejadian pengeluaran tak terduga |
| Anggaran alat | jumlah panggilan alat, ukuran hasil alat, pengeluaran API eksternal | Mencegah loop alat dan pengambilan data yang mahal |
| Anggaran retry | jumlah retry, kode status yang dapat di-retry, jendela backoff | Memisahkan ketahanan dari pengulangan yang tak terkendali |
| Anggaran fallback | jumlah model fallback, plafon biaya fallback, alasan fallback | Menjaga keandalan agar tidak menutupi rute utama yang rusak |
| Anggaran pemilik | batas proyek, tim, pelanggan, lingkungan, kunci, atau alur kerja | Membuat pengeluaran dapat ditinjau oleh keuangan dan engineering |
Gateway harus gagal tertutup ketika batas keras terlampaui. Ia dapat meringkas, meminta pengurangan cakupan, mengantrekan peninjauan manusia, atau mengembalikan error yang terkontrol. Ia tidak boleh diam-diam mengirim prompt yang lebih besar, beralih ke rute yang lebih mahal, atau terus melakukan retry.
Gunakan bentuk anggaran ini:
budget_policy:
workflow: invoice_reconciliation_agent
owner_key: finance_ops
per_request:
max_input_tokens: 32000
max_output_tokens: 4000
max_model_calls: 4
max_tool_calls: 5
per_session:
max_total_tokens: 90000
max_total_cost_usd: reviewed_threshold
retry:
max_attempts: 2
retryable_statuses: [408, 409, 429, 500, 502, 503, 504]
fallback:
max_fallbacks: 1
require_reason: true
on_over_budget:
action: stop_or_request_scope_reduction
Log: catat bukti, bukan hanya prompt mentah
Log agen perlu menjawab dua pertanyaan: apa yang terjadi saat runtime, dan siapa yang bisa membuktikan kebijakan berjalan?
Dokumentasi observability AI Gateway milik Vercel menjelaskan log gateway untuk pengeluaran, penggunaan model, metrik observability, ringkasan request, API key, dan log request. Dokumentasi observability OpenAI's Agents SDK menjelaskan trace yang dapat mencakup panggilan model, panggilan alat, handoff, guardrail, dan span kustom. Contoh-contoh itu menunjukkan kebutuhan operasional yang sama: gateway agen memerlukan log yang menghubungkan perilaku model ke keputusan rute, alat, anggaran, dan penghentian.
Untuk kontrol AI agent gateway, catat field berikut setidaknya:
| Field | Contoh | Mengapa ini penting |
|---|---|---|
request_id |
UUID yang dihasilkan gateway | Menghubungkan catatan model, alat, penagihan, dan dukungan |
workflow_class |
support_agent, code_agent, finance_agent | Mengelompokkan kebijakan dan pengujian penerimaan |
owner_key |
tim, app, pelanggan, lingkungan | Mendukung alokasi pengeluaran dan peninjauan penyalahgunaan |
requested_model |
alias model atau nama rute | Menunjukkan apa yang diminta aplikasi |
served_model |
provider/model aktual | Menunjukkan apa yang disajikan gateway |
tool_calls |
nama, versi skema, argumen yang disensor, status | Membuktikan perilaku kebijakan alat |
usage |
input, output, penalaran, cache, total token | Menghubungkan perilaku ke biaya |
budget_result |
diizinkan, diperingatkan, diblokir | Membuktikan gate biaya berjalan |
stop_condition |
selesai, max_steps, over_budget, approval_required | Menjelaskan bagaimana eksekusi berakhir |
fallback_reason |
timeout, 429, provider_error, quality_gate | Memisahkan pemulihan dari penyimpangan |
Jangan log semuanya selamanya hanya karena itu mudah. Data pelanggan, prompt, hasil alat, dan file dapat membawa informasi sensitif. Desain log yang tahan lama harus mendefinisikan redaksi, retensi, tinjauan akses, kebutuhan ekspor, dan prosedur insiden. Gateway harus menyimpan cukup bukti untuk men-debug dan merekonsiliasi penggunaan tanpa menjadikan setiap request sebagai arsip data yang tak terkendali.
Kondisi berhenti: definisikan akhir eksekusi sebelum model mulai
Kondisi berhenti bukan hanya urutan stop model. Mereka adalah aturan yang mengakhiri eksekusi agen dengan aman.
API provider mengekspos permukaan respons dan stop yang berbeda-beda. Messages API milik Anthropic mengekspos field stop_reason seperti tool use, end turn, max tokens, dan stop sequences dalam dokumentasinya. Dokumentasi guardrails OpenAI's Agents SDK memposisikan guardrails dan peninjauan manusia sebagai kontrol yang menentukan kapan eksekusi dilanjutkan, dijeda, atau dihentikan. Dalam produksi, gateway Anda harus menormalkan status spesifik provider tersebut menjadi state alur kerja yang dipahami tim Anda.
Gunakan matriks berhenti:
| Kondisi berhenti | Aksi gateway | Perilaku yang terlihat oleh pengguna | Bukti yang diperlukan |
|---|---|---|---|
| Selesai | Kembalikan jawaban akhir | Respons normal | model akhir, penggunaan, tidak ada alat yang belum terselesaikan |
| Persetujuan alat diperlukan | Jeda | "Aksi ini perlu ditinjau" | panggilan alat, argumen, penyetuju, keputusan |
| Melampaui anggaran | Berhenti atau minta pengurangan cakupan | "Persempit permintaannya" | bidang anggaran, ambang batas, kunci pemilik |
| Langkah maksimum tercapai | Berhenti | "Tidak dapat diselesaikan dalam run ini" | jumlah langkah, aksi terakhir, sinyal loop |
| Kesalahan alat | Coba lagi, fallback, atau berhenti | Jalur kegagalan yang jelas | status alat, kelas kesalahan, jumlah percobaan ulang |
| Timeout penyedia | Coba lagi atau fallback | Respons menurun tetapi tetap terkendali | rute, timeout, alasan fallback |
| Pelanggaran kebijakan | Berhenti | Tolak atau alihkan ke manusia | kebijakan yang terpicu, sampel yang disamarkan |
| Keyakinan rendah atau bukti hilang | Minta tindak lanjut atau eskalasi | "Perlu informasi lebih lanjut" | bidang yang hilang, hasil evaluasi |
Hal pentingnya adalah setiap state terminal memiliki nama. Jika satu-satunya state adalah "sukses" dan "error," tim tidak dapat mengetahui apakah agen mematuhi kebijakan atau sekadar berhenti secara tidak sengaja.
Templat kontrol gateway agen AI yang praktis
Gunakan file kebijakan yang dapat ditinjau bersama oleh engineering, security, finance, dan product:
policy_name: ai_agent_gateway_controls_v1
owner:
team: ai_platform
reviewers:
- engineering
- finance
- security
workflow_classes:
support_agent:
route: balanced_text_tool_route
allowed_tools: [lookup_order, search_policy, open_ticket]
approval_tools: [issue_refund, cancel_subscription]
max_tool_calls: 5
max_model_calls: 4
code_agent:
route: code_review_route
allowed_tools: [read_repo, search_repo, propose_patch]
approval_tools: [apply_patch, run_shell_command]
max_tool_calls: 12
max_model_calls: 8
budget_rules:
require_owner_key: true
block_when_owner_budget_exceeded: true
require_fallback_reason: true
log_rules:
capture_request_id: true
capture_requested_and_served_model: true
capture_tool_call_status: true
redact_sensitive_arguments: true
stop_rules:
max_steps: 12
max_retries_per_tool: 1
on_policy_violation: stop
on_approval_required: pause
acceptance_tests:
- blocked_tool_is_not_executed
- over_budget_request_fails_closed
- approval_tool_pauses_run
- fallback_records_reason
- request_log_contains_usage_and_stop_condition
File ini tidak menggantikan kode aplikasi. File ini memberi kontrak yang harus ditegakkan oleh kode dan memberi reviewer artefak konkret untuk diperiksa.
Uji penerimaan sebelum produksi
Jalankan uji penerimaan terhadap setiap kelas workflow sebelum traffic live:
- Kirim permintaan normal dan konfirmasi hanya alat yang diizinkan yang diekspos.
- Minta alat yang diblokir dan konfirmasi alat tersebut tidak dieksekusi.
- Minta alat yang memerlukan persetujuan dan konfirmasi run dijeda dengan state yang dapat dilanjutkan.
- Kirim prompt yang terlalu besar dan konfirmasi gateway berhenti atau meminta pengurangan cakupan.
- Picu kesalahan alat dan konfirmasi jumlah percobaan ulang, alasan fallback, dan state akhir dicatat.
- Paksa timeout penyedia dan konfirmasi fallback tetap berada di dalam anggaran fallback.
- Picu langkah maksimum dan konfirmasi run tidak berputar tanpa henti.
- Konfirmasi log permintaan menampilkan kunci pemilik, model yang diminta, model yang disajikan, usage, status alat, hasil anggaran, dan kondisi berhenti.
- Ambil sampel rekonsiliasi finance dari log permintaan ke invoice atau pergerakan saldo prabayar.
- Jalankan ulang pengujian yang sama setelah mengubah model, alat, prompt, atau kebijakan rute.
Pasangkan artikel ini dengan panduan Flatkey tentang arsitektur gateway AI API, arsitektur gateway LLM API, load balancing dan failover AI API, dan desain kebijakan routing model. Arsitektur gateway menentukan di mana kontrol berada; uji penerimaan membuktikan bahwa kontrol tersebut bekerja.
Di mana Flatkey berperan
Flatkey seharusnya bukan satu-satunya tempat kebijakan agen Anda berada. Simpan kebijakan di dalam kode, konfigurasi, atau repositori kontrol internal. Gunakan Flatkey sebagai permukaan gateway tempat tim dapat memusatkan akses model, peninjauan routing, visibilitas penggunaan, log permintaan, kontrol biaya, saldo prabayar, dan peninjauan penagihan.
Implementasi Flatkey yang praktis terlihat seperti ini:
- Pilih satu alur kerja agen dengan alat dan pemilik yang sudah diketahui.
- Tentukan alat yang diizinkan, alat persetujuan, batas anggaran, field log, dan kondisi berhenti.
- Periksa model dan opsi harga saat ini di harga Flatkey.
- Jalankan pengujian penerimaan dengan kunci non-produksi.
- Tinjau log untuk model yang diminta, model yang dilayani, penggunaan, keputusan routing, alasan fallback, dan kondisi berhenti.
- Pindahkan hanya alur kerja yang telah diuji ke produksi.
- Tambahkan alat baru dan rute fallback satu baris kebijakan pada satu waktu.
Ketika pembuktian lolos, dapatkan kunci dan pertahankan rollout awal tetap sempit. Kontrol gateway AI agent yang paling kuat itu membosankan di produksi: setiap panggilan alat memiliki alasan, setiap keputusan anggaran memiliki jejak, setiap kegagalan memiliki kondisi berhenti yang dinamai, dan setiap peninjau dapat melihat apa yang terjadi.
Pertanyaan yang sering diajukan
Apa itu kontrol gateway AI agent?
Kontrol gateway AI agent adalah kebijakan yang mengatur akses alat, anggaran, log, perilaku fallback, dan kondisi berhenti untuk alur kerja agen yang memanggil model dan alat melalui gateway.
Apakah kontrol gateway AI agent sama dengan routing model?
Tidak. Routing model menentukan model atau penyedia mana yang harus melayani permintaan. Kontrol gateway AI agent menentukan apakah agen boleh memanggil alat, membelanjakan anggaran lebih banyak, mencoba ulang, fallback, menjeda untuk persetujuan, atau berhenti.
Apa yang harus dicatat untuk penggunaan alat agen?
Catat ID permintaan, kelas alur kerja, kunci pemilik, model yang diminta, model yang dilayani, nama alat, versi skema, argumen yang disamarkan, status hasil, penggunaan, hasil anggaran, alasan fallback, dan kondisi berhenti.
Haruskah alat sensitif selalu tersedia untuk model?
Tidak. Pisahkan katalog alat lengkap dari allowlist alur kerja. Alat sensitif harus memerlukan persetujuan, cakupan yang lebih sempit, atau rute eskalasi terpisah.
Bagaimana kelebihan anggaran harus ditangani?
Kelebihan anggaran yang keras harus gagal tertutup. Gateway dapat meminta pengurangan cakupan, melakukan ringkasan, mengantrikan tinjauan, atau mengembalikan error terkontrol, tetapi tidak boleh diam-diam beralih ke rute yang lebih mahal.
Bagaimana Flatkey membantu dengan kontrol gateway AI agent?
Flatkey memberi tim satu permukaan gateway untuk akses model, peninjauan routing, visibilitas penggunaan, log permintaan, kontrol biaya, saldo prabayar, dan peninjauan penagihan. Gunakan permukaan itu bersama policy-as-code dan pengujian penerimaan untuk alur kerja agen produksi.
