Agen meminta catatan pelanggan. API Anda mengembalikan data pelanggan, ditambah 200 pesanan terakhir mereka, ditambah setiap item baris pada pesanan tersebut, ditambah stempel waktu dalam tiga format dan blok _links untuk setiap data. Empat puluh ribu token masuk ke jendela konteks. Agen hanya membutuhkan alamat email.
Lakukan itu empat kali dalam satu sesi dan agen telah menghabiskan sebagian besar anggarannya untuk membaca JSON yang tidak dimintanya. Kemudian kegagalan yang menarik mulai terjadi: ia melupakan instruksi awal, ia meringkas tugas alih-alih menyelesaikannya, dan biaya per sesi meningkat sementara kualitas menurun.
Ini adalah masalah desain pada lapisan API, bukan masalah prompt. Agen mengonsumsi respons melalui jendela tetap, dan setiap bidang yang Anda kembalikan bersaing dengan instruksi, percakapan, dan rencana. Panduan ini membahas dari mana "bloat" berasal, pola pemilihan bidang dan paginasi yang memperbaikinya, cara memangkas di dalam lapisan alat ketika Anda tidak mengontrol API, dan cara mengukur perbedaannya. Pilar kami tentang mengapa agen AI rusak dalam produksi memperlakukan kehabisan konteks sebagai salah satu mode kegagalan inti, dan ini adalah bagian praktisnya.
Apidog membantu dalam sisi pengukuran: Anda dapat melihat ukuran respons sebenarnya untuk setiap *endpoint* sebelum agen memanggilnya, dan membuat *mock* bentuk yang Anda inginkan sebelum tim API mengirimkannya.
Ke mana token pergi
Respons yang dirancang untuk peramban dan *dashboard* membawa banyak "beban" yang memakan biaya besar bagi agen.
Amplop *verbose*. Sebuah *wrapper* data, meta, links, included di sekitar objek lima-bidang dapat menggandakan *payload*. Tautan *Hypermedia* berguna untuk klien yang mengikutinya. Agen hampir tidak pernah melakukannya, dan setiap URL adalah token.
Kunci berulang. JSON mengulang setiap nama bidang pada setiap elemen larik. Daftar 200 item dengan 15 bidang per item membayar 3.000 string kunci. Inilah mengapa *endpoint* daftar mendominasi penggunaan konteks.
Ekspansi bersarang secara *default*. *Endpoint* yang menyisipkan sumber daya terkait nyaman sampai agen memukulnya. Satu pelanggan ditambah pesanan mereka ditambah item adalah pohon, dan pohon tumbuh dengan cepat.
Format yang berlebihan. created_at, created_at_unix, dan created_at_human pada objek yang sama adalah biaya tiga kali lipat untuk satu nilai.
Nul dan kosong. Banyak *serializer* mengeluarkan setiap bidang bahkan ketika tidak diatur. Dua puluh null per catatan adalah pemborosan murni.
Cara yang berguna untuk melihatnya: biaya token melacak ukuran teks yang diserialisasi, bukan jumlah catatan. Dua ratus catatan dengan masing-masing lima bidang bisa lebih murah daripada satu objek yang sangat bersarang.
Aturan satu: kembalikan bidang, bukan sumber daya
Perubahan dengan nilai tertinggi adalah membiarkan pemanggil meminta apa yang dibutuhkannya.
GET /v1/customers/8812?fields=id,email,plan,status
{ "id": "8812", "email": "dana@example.com", "plan": "pro", "status": "active" }
Itu adalah pengurangan 90 persen dari catatan lengkap pada sebagian besar API, dan hanya perlu waktu sehari untuk menambahkannya. Panduan desain API Google mendokumentasikan pola *field-mask* jika Anda menginginkan versi dengan preseden di baliknya, dan GraphQL memecahkan masalah yang sama dengan membuat pemilihan wajib.
Dua catatan implementasi. Validasi daftar bidang terhadap skema dan tolak nama yang tidak dikenal, sehingga bidang yang *halusinasi* menghasilkan kesalahan yang jelas alih-alih objek yang dipotong secara diam-diam. Dan pertahankan kumpulan *default* kecil untuk pemanggil yang tidak mengirim apa pun, daripada *default* ke semuanya.
Kemudian paparkan parameter ke model dalam deskripsi alat, dengan bidang yang dijabarkan:
{
"name": "getCustomer",
"description": "Ambil pelanggan berdasarkan ID. Selalu sertakan `fields` hanya dengan yang Anda butuhkan. Tersedia: id, email, name, plan, status, created_at, billing_address, order_count.",
"input_schema": {
"type": "object",
"required": ["customerId", "fields"],
"properties": {
"customerId": { "type": "string" },
"fields": {
"type": "array",
"items": { "type": "string" },
"description": "Nama bidang yang akan dikembalikan. Pertahankan daftar ini seminimal mungkin."
}
}
}
}
Deskripsi adalah satu-satunya tempat model mempelajari aturan-aturan ini, dan baik panduan pemanggilan fungsi OpenAI maupun dokumentasi penggunaan alat Anthropic memberikan bobot yang sama pada deskripsi. Membuat fields wajib adalah triknya. Parameter opsional akan dilewati; parameter wajib memaksa model untuk memikirkan apa yang sebenarnya dibutuhkan.
Aturan dua: selalu batasi daftar
*Endpoint* daftar tanpa batas adalah sumber besar kedua dari ledakan (*blowup*). Agen meminta "pesanan terbaru" dan mendapatkan semuanya sejak 2019.
Tetapkan batas maksimum di sisi server, bukan hanya *default*. Jika agen mengirim limit=5000, kembalikan 100 dan sampaikan. Panduan kami tentang paginasi API REST dan desain paginasi untuk jutaan catatan mencakup mekanisme; aturan khusus agen lebih sempit:
- Batasi halaman pada sesuatu yang dapat dibaca model, dalam kisaran 20 hingga 50 item untuk catatan tipikal.
- Kembalikan jumlah total sehingga agen dapat mengetahui apakah ia telah melihat semuanya tanpa harus melakukan paginasi.
- Gunakan paginasi kursor. *Offset* dapat bergeser ketika data berubah di tengah-jalannya, dan agen yang melakukan paginasi secara perlahan akan mengalami hal itu.
- Sertakan pernyataan sederhana dalam respons, seperti
"truncated": true, sehingga model tahu ada lebih banyak data. Model sering kali salah menilai kelengkapan hanya dari panjang larik.
Juga berikan agen cara untuk menghindari paginasi sama sekali. *Endpoint* count, pencarian yang difilter dengan jendela sempit, atau objek ringkasan seringkali dapat menjawab pertanyaan tanpa mengembalikan catatan apa pun. Respons termurah adalah yang tidak mengandung data.
Aturan tiga: pangkas di lapisan alat ketika API bukan milik Anda
API pihak ketiga tidak akan menambahkan pemilihan bidang hanya karena Anda memintanya. Tempatkan pemangkasan di eksekutor Anda, antara respons HTTP dan model.
KEEP = {
"getCustomer": ["id", "email", "plan", "status"],
"listOrders": ["id", "total", "status", "created_at"],
}
def project(tool_name, payload):
keep = KEEP.get(tool_name)
if keep is None:
return payload
if isinstance(payload, list):
return [{k: item.get(k) for k in keep if k in item} for item in payload]
return {k: payload.get(k) for k in keep if k in payload}
Tiga penyempurnaan membuat ini berlaku dalam praktik.
Simpan respons lengkap dan berikan model proyeksi. Simpan *payload* yang tidak dipangkas dalam log eksekusi Anda sehingga *debugging* masih memungkinkan. Pos kami tentang melacak panggilan alat agen AI membahas apa yang perlu direkam.
Beri tahu model apa yang Anda hapus. Baris seperti "_omitted": ["billing_address", "notes", "metadata"] memungkinkan model meminta catatan lengkap ketika benar-benar membutuhkannya, alih-alih menyimpulkan bahwa data tidak ada.
Konversikan daftar ke format ringkas. Untuk hasil tabular, CSV atau tabel *markdown* membutuhkan lebih sedikit token daripada JSON karena nama bidang muncul sekali saja alih-alih per baris. Model membaca keduanya dengan baik.
id,total,status,created_at
ord_91,4900,paid,2026-08-21
ord_92,1200,refunded,2026-08-22
Aturan empat: ringkas di server untuk kasus berat
Beberapa pertanyaan sama sekali tidak memerlukan catatan. "Apakah pelanggan ini mengalami pembayaran gagal bulan ini?" adalah pertanyaan *boolean*. Mengembalikan 40 objek pembayaran agar model dapat mengetahuinya adalah cara yang mahal untuk menjawab.
Jika sebuah pertanyaan berulang, tambahkan *endpoint* yang menjawabnya secara langsung. Ringkasan kesehatan akun, *rollup* status, agregasi kecil. Ini terlihat seperti pekerjaan desain API biasa karena memang demikian, dan ini adalah versi paling berharga dari semua hal di atas: alih-alih memangkas respons besar, Anda menghindari pembuatannya.
Dua *guardrail*. Pertahankan ringkasan agar stabil dalam bentuknya sehingga agen dapat mengandalkannya, dan versi ringkasan tersebut, karena *prompt* agen ditulis berdasarkan bentuk dan perubahan yang tidak terdeteksi akan merusaknya. Pos kami tentang apa yang terjadi ketika API berubah di bawah agen mencakup risiko tersebut, dan strategi *versioning* API terbaik mencakup mekanismenya.
Ukur sebelum dan sesudah
Semua ini tidak layak dilakukan secara buta. Tiga angka akan memberi tahu Anda di mana masalahnya.
Byte per respons, per *endpoint*. Kirim permintaan realistis ke setiap alat yang dapat dipanggil agen Anda dan catat ukuran *payload*. Apa pun yang melewati beberapa kilobyte adalah kandidat. Di Apidog Anda dapat menjalankan setiap *endpoint* sekali dan membaca ukurannya langsung dari respons, lalu menyimpan permintaan sehingga pemeriksaan berulang ketika API berubah.
Token per panggilan alat. Byte adalah *proxy*; token adalah tagihannya. Jalankan *payload* melalui *tokenizer* penyedia Anda, seperti tiktoken untuk model OpenAI, dan peringkatkan *endpoint*. Peringkat biasanya berat sebelah, dengan satu atau dua *endpoint* bertanggung jawab atas sebagian besar biaya.
Konteks yang digunakan per sesi. Catat total yang berjalan di seluruh tugas agen. Jika suatu tugas berakhir mendekati batas, pemangkasan akan menghasilkan sesi yang selesai, bukan hanya yang lebih murah.
Kemudian rancang bentuk yang Anda inginkan dan buat *mock*-nya sebelum tim API membangunnya. Server *mock* yang mengembalikan respons yang dipangkas memungkinkan Anda mengukur peningkatan dan memverifikasi agen masih berhasil dengan lebih sedikit data, yang merupakan pertanyaan yang sebenarnya penting. Pos kami tentang menjalankan agen terhadap *mock* alih-alih produksi mencakup alur kerja.
Seperti apa yang baik itu
Respons yang ramah agen kecil, datar, dan jujur tentang apa yang dihilangkannya:
{
"customer": { "id": "8812", "email": "dana@example.com", "plan": "pro" },
"recent_orders": [
{ "id": "ord_91", "total_cents": 4900, "status": "paid" },
{ "id": "ord_92", "total_cents": 1200, "status": "refunded" }
],
"recent_orders_total": 47,
"truncated": true,
"_omitted": ["billing_address", "metadata", "order_line_items"]
}
Kurang dari 200 token. Ini menjawab pertanyaan umum, ini mengatakan ada 47 pesanan daripada menyiratkan hanya ada dua, dan ini memberi tahu model apa yang bisa diminta selanjutnya.
Mulailah dengan *endpoint* Anda yang paling "berisik". Ukur, tambahkan pemilihan bidang, batasi daftar, dan jalankan agen lagi. Perbedaan antara kedua angka tersebut biasanya cukup besar untuk membenarkan sisa pekerjaan. Unduh Apidog jika Anda ingin pengukuran dan *mock* dalam proyek yang sama.
Tiga tempat hal ini muncul
Triage Dukungan. Seorang agen membaca tiket, menarik data pelanggan, dan memutuskan apakah akan melakukan eskalasi. Versi naif mengambil objek pelanggan lengkap dan 50 tiket terakhir, membakar 30.000 token sebelum membaca keluhan sebenarnya. Versi yang diperbaiki memanggil *endpoint* ringkasan yang mengembalikan paket, status, jumlah tiket terbuka, dan tanggal kontak terakhir. Sekitar 80 token, dan keputusan eskalasi menjadi lebih baik karena fakta-fakta yang relevan tidak terkubur.
Agen Operasi Internal. Agen *deploy* memeriksa kesehatan layanan di 40 layanan. Objek status lengkap membebani jendela pada layanan ke-12. Sebuah *rollup* yang mengembalikan satu baris per layanan, nama ditambah status ditambah tingkat kesalahan, memuat semua 40 dalam beberapa ratus token dan memungkinkan agen bernalar di seluruh armada daripada melupakan bagian pertama.
Entri Data dan Rekonsiliasi. Agen mencocokkan faktur dengan pembayaran. Mengembalikan dokumen faktur lengkap membuatnya gagal setelah beberapa lusin catatan. Mengembalikan id, amount_cents, date, dan reference sebagai CSV memungkinkannya menangani beberapa ratus dalam satu *pass*, karena perbandingan hanya menggunakan empat bidang.
Pola di ketiga kasus tersebut: agen membutuhkan permukaan keputusan, dan API memberinya dokumen.
Anda memerlukan riwayat eksekusi untuk melihat pola
Satu kali eksekusi menunjukkan bahwa responsnya besar. Pola, *endpoint* mana yang menghabiskan anggaran dan seberapa sering, hanya muncul di beberapa eksekusi.
Itu berarti angka-angka harus bertahan di sesi. Untuk layanan yang Anda sebarkan, itu adalah telemetri Anda sendiri. Untuk agen pengkodean yang melakukan pekerjaan yang ditugaskan, itu adalah platform apa pun yang menjalankannya: Sharkly menyimpan jejak eksekusi dan hasil setiap eksekusi pada Tugas asalnya, sehingga perbandingan eksekusi-per-eksekusi adalah masalah membaca riwayat tugas daripada merekonstruksi sesi terminal. Bagaimanapun, penegakan anggaran tanpa riwayat memberi tahu Anda bahwa ada sesuatu yang terlalu besar, tetapi bukan apa yang harus diperbaiki terlebih dahulu.
Tetapkan anggaran per alat, bukan hanya per sesi
Kebanyakan tim membatasi konteks total dan berhenti di situ. Anggaran per alat lebih berguna, karena mengubah masalah yang tidak jelas menjadi masalah yang spesifik.
Berikan setiap alat batas maksimum, misalnya 1.500 token. Ketika sebuah respons melebihi batas, eksekutor memangkas proyeksi, menambahkan penanda bidang yang dihilangkan, dan mencatat *overflow*. Sekarang Anda memiliki daftar *endpoint* yang secara teratur melebihi anggaran, diberi peringkat berdasarkan seberapa sering agen memanggilnya, yang merupakan antrean kerja Anda.
Anggaran juga melindungi Anda dari *endpoint* yang kecil dalam pengujian tetapi sangat besar untuk satu pelanggan nyata. Distribusi memiliki "ekor", dan akun dengan 4.000 pesanan adalah yang akan memecahkan eksekusi pada pukul 2 pagi. Batas keras mengubah itu menjadi respons yang dipangkas alih-alih tugas yang gagal.
Pertanyaan yang Sering Diajukan
Apakah memotong respons berisiko jika agen membutuhkan data yang hilang? Hanya jika Anda menyembunyikan pemotongan. Sertakan penanda eksplisit dan daftar bidang yang dihilangkan agar model dapat memintanya. Pemotongan senyaplah yang menyebabkan jawaban salah, bukan pemangkasan itu sendiri.
Haruskah saya menggunakan GraphQL untuk agen sebagai gantinya? GraphQL membuat pemilihan bidang wajib, yang memecahkan masalah ini dengan bersih, tetapi ia memindahkan kompleksitas ke konstruksi kueri dan model menulis kueri yang tidak valid lebih sering daripada menyalahgunakan daftar bidang. Menambahkan fields ke *endpoint* REST biasanya merupakan perubahan yang lebih kecil.
Seberapa kecil seharusnya respons alat? Usahakan di bawah 1.000 token untuk pembacaan satu catatan dan di bawah 2.000 untuk daftar. Lebih dari itu, tanyakan apakah agen membutuhkan catatan atau jawaban.
Apakah *prompt caching* memecahkan masalah ini? Ini mengurangi biaya konteks yang berulang, bukan ruang yang ditempatinya. Respons 40.000-token yang di-*cache* masih memenuhi jendela, jadi *caching* membantu biaya sambil membiarkan masalah keandalan tetap utuh.
Bagaimana dengan respons biner dan file? Jangan pernah memasukkannya ke dalam konteks. Simpan file, berikan agen referensi dan deskripsi singkat, dan berikan alat terpisah untuk mengekstrak hanya apa yang dibutuhkannya.
Di mana pemangkasan harus berada, di API atau *wrapper* alat? Di API ketika Anda memilikinya, karena setiap pemanggil mendapat manfaat dan *byte* tidak pernah melintasi jaringan. Di *wrapper* ketika Anda tidak. Melakukan keduanya tidak masalah.