Cara Menguji Panggilan Alat Agen AI dengan Apidog untuk Mencegah Kegagalan Produksi

Agen AI hanya seandal API yang dipanggilnya. Model memilih alat, mengisi argumen, dan meluncurkan permintaan; jika permintaan itu gagal, mengembalikan bentuk yang salah, atau macet, agen Anda membuat keputusan yang yakin berdasarkan data yang buruk. Sebagian besar demo agen melewatkan bagian ini. Agen produksi hidup atau mati karenanya.

Panduan ini menunjukkan cara membangun agen yang memanggil alat sungguhan dan, yang lebih penting, cara menggunakan Apidog sebagai lapisan API dan alat uji di belakangnya. Anda akan merancang endpoint alat, membuat mock-nya agar Anda dapat mengembangkan secara offline, dan menulis pernyataan yang menangkap panggilan alat yang rusak sebelum mencapai pengguna. Tujuannya adalah agen yang dapat Anda percaya karena Anda telah mengujinya, bukan karena jalur yang mulus berhasil sekali.

tombol

Apa yang sebenarnya dilakukan agen pada lapisan API

Kesampingkan kerangka kerjanya dan loop agen itu sederhana:

Model menerima tujuan pengguna dan daftar alat.
Ia mengembalikan panggilan alat: nama alat ditambah argumen JSON.
Kode Anda mengeksekusi panggilan itu; biasanya permintaan HTTP ke beberapa API.
Hasilnya kembali ke model.
Model memanggil alat lain atau menjawab.

Setiap kegagalan menarik terjadi pada langkah 3 dan langkah 4. Model berhalusinasi argumen, API mengembalikan 422, skema respons bergeser, panggilan kehabisan waktu, atau batas kecepatan aktif di tengah loop. Jika Anda pernah membaca tentang agen AI sebagai konsumen API baru, ini adalah versi konkret dari ide tersebut: agen Anda adalah klien yang mengakses API Anda, dan layak mendapatkan ketelitian pengujian yang sama seperti klien lainnya.

Jadi pekerjaan terbagi dua: definisikan alat sebagai operasi API yang nyata dan dapat diuji, lalu verifikasi agen memanggilnya dengan benar dalam kondisi baik dan buruk.

Langkah 1: Rancang alat sebagai operasi API nyata

Sebelum Anda menulis satu baris kode agen, definisikan setiap alat sebagai endpoint API di Apidog. Perlakukan skema alat dan skema API sebagai hal yang sama, karena memang demikian. Alat get_weather dan endpoint GET /weather berbagi kontrak: parameter yang sama, bentuk respons yang sama.

Di Apidog, buat endpoint untuk setiap alat dengan skema OpenAPI-nya; parameter jalur, kueri, dan isi, serta respons bertipe. Ini memberi Anda tiga hal secara gratis:

Satu sumber kebenaran untuk kontrak alat yang dibaca oleh prompt agen dan pengujian Anda.
Dokumentasi yang dibuat secara otomatis yang dapat Anda berikan kepada model sebagai definisi alat.
Skema untuk divalidasi nanti, sehingga Anda dapat menangkap penyimpangan saat respons berhenti cocok.

Kebiasaan mengutamakan skema ini sama dengan yang melandasi pekerjaan desain API yang solid secara umum. Manfaatnya bagi agen bersifat spesifik: ketika definisi alat Anda dan endpoint nyata Anda berasal dari satu skema, model tidak dapat memanggil alat yang tidak didukung oleh API Anda.

Langkah 2: Mock alat agar Anda dapat membangun secara offline

Anda tidak ingin setiap proses pengembangan mengakses API langsung yang membutuhkan biaya, menerapkan batas kecepatan, atau bahkan belum dibangun. Apidog menghasilkan server mock langsung dari skema yang baru saja Anda definisikan. Setiap endpoint alat mengembalikan data sampel yang realistis dan valid secara skema tanpa backend apa pun.

Ini mengubah cara Anda membangun agen. Anda dapat:

Mengembangkan seluruh loop agen sebelum API nyata ada, terhadap mock yang cocok dengan kontrak yang disepakati.
Menjalankan pengujian integrasi di CI yang tidak pernah menyentuh endpoint berbayar.
Memaksa respons spesifik; hasil kosong, 500, bidang yang salah bentuk; untuk melihat bagaimana agen Anda bereaksi.

Arahkan eksekutor alat agen Anda ke URL dasar mock selama pengembangan. Model memanggil get_weather, kode Anda mengakses mock Apidog, dan respons yang valid segera kembali. Saat Anda siap untuk hal yang nyata, tukar URL dasar melalui variabel lingkungan. Mocking adalah yang membuat pengembangan agen cepat dan deterministik; pendekatan yang sama mendukung alur kerja pengujian agen AI yang serius.

Langkah 3: Hubungkan agen untuk memanggil alat

Dengan endpoint dan mock yang sudah ada, kode agen tetap tipis. Berikut adalah bentuk loop pemanggilan alat menggunakan Claude Messages API; definisi alat mencerminkan skema yang Anda bangun di Apidog.

import anthropic, requests, os

client = anthropic.Anthropic()
TOOL_BASE = os.environ["TOOL_BASE_URL"]  # Apidog mock during dev, real API in prod

tools = [{
    "name": "get_weather",
    "description": "Get current weather for a city",
    "input_schema": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"],
    },
}]

def run_tool(name, args):
    if name == "get_weather":
        r = requests.get(f"{TOOL_BASE}/weather", params={"city": args["city"]}, timeout=10)
        r.raise_for_status()
        return r.json()

messages = [{"role": "user", "content": "What should I wear in Tokyo today?"}]
while True:
    resp = client.messages.create(
        model="claude-fable-5", max_tokens=1024, tools=tools, messages=messages
    )
    if resp.stop_reason == "tool_use":
        block = next(b for b in resp.content if b.type == "tool_use")
        result = run_tool(block.name, block.input)
        messages.append({"role": "assistant", "content": resp.content})
        messages.append({"role": "user", "content": [{
            "type": "tool_result", "tool_use_id": block.id,
            "content": str(result),
        }]})
    else:
        print(resp.content[0].text)
        break

Baris timeout=10 dan raise_for_status() lebih penting daripada panggilan model. Keduanya adalah perbedaan antara agen yang gagal dengan keras dan agen yang secara diam-diam memasukkan permintaan yang macet atau error kembali ke dalam loop. Untuk pandangan yang lebih luas tentang bagaimana agen cocok dalam alur kerja API, pola dalam 5 agen AI untuk alur kerja API Anda adalah pendamping yang berguna.

Langkah 4: Uji panggilan alat, bukan hanya "vibes"

Ini adalah bagian yang dilewati sebagian besar tim. Jalankan setiap endpoint alat sebagai permintaan tersimpan di Apidog dengan pernyataan, terlepas dari modelnya. Keandalan agen dibatasi oleh keandalan alatnya, jadi uji alatnya terlebih dahulu.

Untuk setiap endpoint alat, pastikan:

Statusnya 200 untuk input yang valid.
Isi respons cocok dengan skema; Apidog secara otomatis memvalidasi respons terhadap definisi OpenAPI Anda.
Bidang wajib yang akan dibaca model hadir dan bertipe benar.
Waktu respons berada dalam batas waktu yang diterapkan agen Anda.

Kemudian uji jalur yang tidak bahagia, karena di situlah agen berperilaku salah:

Kirim argumen yang salah bentuk yang mungkin dihalusinasi model; city kosong, angka di mana seharusnya string; dan pastikan Anda mendapatkan 400/422 yang bersih, bukan 500.
Paksa respons error dari mock dan konfirmasikan run_tool agen Anda memunculkan error alih-alih mengembalikan sampah.
Uji hasil kosong dan periksa agen menangani "tidak ada data" daripada mengarang jawaban.

Ini adalah pengujian kontrak yang diterapkan pada alat agen; disiplin yang sama dibahas dalam pengujian kontrak API, diarahkan ke endpoint yang dipanggil oleh model Anda. Ketika bentuk respons alat bergeser, pernyataan gagal dalam CI dan Anda memperbaikinya sebelum agen mulai beralasan atas payload yang rusak.

Langkah 5: Tangani percobaan ulang, batas waktu, dan batas kecepatan

Agen memperkuat API yang tidak stabil. Satu percobaan ulang dalam aplikasi normal adalah satu percobaan ulang; dalam loop agen, model yang terus-menerus memanggil kembali alat yang gagal dapat menghabiskan batas kecepatan dan anggaran Anda dengan cepat. Bangun kontrol dan uji:

Batas waktu. Tetapkan batas waktu eksplisit pada setiap permintaan alat, seperti contoh di atas. Kemudian gunakan Apidog untuk mensimulasikan endpoint yang lambat dan konfirmasikan klien Anda berhenti dengan bersih alih-alih menggantung seluruh loop.
Coba lagi dengan backoff. Coba lagi kegagalan sementara, tetapi batasi jumlahnya dan lakukan backoff. Uji ini terhadap mock yang gagal dua kali lalu berhasil, dan pastikan agen Anda pulih alih-alih berulang selamanya.
Batas kecepatan. Harapkan 429 di bawah beban. Buat mock respons yang dibatasi kecepatannya dan verifikasi agen Anda menunggu dan mencoba lagi alih-alih membombardir. Jika Anda telah menangani ini pada API model mentah; lihat batas kecepatan API GPT untuk jenis masalah yang sama; versi agen lebih ketat karena loop melipatgandakan setiap panggilan.
Pemutus sirkuit. Setelah N kegagalan pada suatu alat, berhenti memanggilnya dan biarkan agen melaporkan kegagalan alih-alih berputar-putar. Uji pemutus sirkuit tersebut.

Jalankan ini sebagai skenario yang dapat diulang di Apidog sehingga regresi dalam penanganan error Anda muncul sebagai pengujian yang gagal, bukan insiden produksi.

Langkah 6: Jalankan dari awal hingga akhir terhadap mock di CI

Satukan semuanya. Di CI, mulai agen Anda diarahkan ke server mock Apidog, berikan serangkaian tujuan pengguna yang tetap, dan pastikan hasil akhir serta urutan panggilan alat. Karena mock bersifat deterministik, input yang sama menghasilkan panggilan alat yang sama setiap kali dijalankan, sehingga pengujian agen Anda berhenti menjadi tidak stabil. Ketika Anda yakin, alihkan URL dasar ke API nyata untuk pengujian asap langsung yang lebih kecil. Pemisahan ini; mock deterministik untuk sebagian besar pengujian, pemeriksaan langsung yang tipis untuk realitas; adalah yang membuat pengujian AI agensi praktis alih-alih aspiratif.

Daftar periksa untuk agen yang dapat dipercaya

[ ] Setiap alat didefinisikan sebagai operasi API nyata dengan skema OpenAPI.
[ ] Mock ada untuk setiap alat sehingga Anda dapat membangun dan menguji secara offline.
[ ] Setiap endpoint alat memiliki pernyataan tentang status, skema, dan waktu.
[ ] Jalur yang tidak bahagia; argumen yang buruk, error, hasil kosong; diuji secara eksplisit.
[ ] Batas waktu, percobaan ulang dengan backoff, dan penanganan batas kecepatan ada dalam kode dan diuji.
[ ] Jalankan CI end-to-end melatih seluruh loop terhadap mock deterministik.

Capai keenamnya dan Anda memiliki agen yang keandalannya dapat Anda jelaskan dengan bukti, bukan harapan.

FAQ

Mengapa menggunakan klien API untuk menguji agen alih-alih hanya menjalankan agen? Menjalankan agen menguji model dan alat secara bersamaan, sehingga kegagalan menjadi ambigu. Menguji setiap endpoint alat di Apidog mengisolasi lapisan API, sehingga Anda tahu apakah masalahnya adalah penalaran model atau alat yang rusak.

Apakah saya harus membangun API nyata sebelum membangun agen? Tidak. Definisikan kontrak alat sebagai skema di Apidog, hasilkan mock, dan bangun seluruh loop agen terhadap mock tersebut. Tukar dengan endpoint nyata nanti melalui variabel lingkungan.

Bagaimana cara menghentikan agen saya agar tidak berulang selamanya pada alat yang gagal? Batasi percobaan ulang, tambahkan backoff, dan picu pemutus sirkuit setelah kegagalan berulang agar agen melaporkan masalah alih-alih berputar-putar. Uji setiap kontrol terhadap mock yang mengembalikan error.

Dapatkah saya menguji agen tanpa mengeluarkan uang untuk panggilan model dan API? Sebagian besar, ya. Mock API alat di Apidog untuk pengujian integrasi yang deterministik dan gratis, dan pertahankan panggilan model langsung untuk rangkaian pengujian asap kecil.

Apakah ini berfungsi dengan kerangka kerja seperti LangChain atau Claude Agent SDK? Ya. Lapisan alat hanyalah HTTP. Kerangka kerja apa pun yang menggerakkan loop, arahkan panggilan alatnya ke mock Apidog untuk pengujian dan ke endpoint nyata untuk produksi. Lihat panduan Claude Code SDK untuk salah satu loop tersebut.

Ringkasan

Agen yang andal bukanlah prompt yang lebih cerdas; melainkan lapisan alat yang teruji. Definisikan alat Anda sebagai operasi API nyata, mock-nya agar pengembangan cepat dan deterministik, pastikan setiap bentuk respons, dan uji kegagalan dengan sengaja. Apidog memberi Anda satu tempat untuk merancang endpoint tersebut, membuat mock-nya, dan menjalankannya sebagai alat uji, sehingga perilaku agen Anda adalah sesuatu yang dapat Anda buktikan. Unduh Apidog dan bangun agen yang benar-benar dapat Anda percaya dalam produksi.

tombol