Cara Menguji Agen AI yang Memanggil API Anda Tanpa Kehilangan Data

Sebuah agen pengodean AI menjalankan skrip, melihatnya berhasil, lalu tabel basis data produksi menghilang. Post-mortem Hacker News viral dengan tesis sederhana: “AI tidak menghapus basis data Anda, Andalah yang menghapusnya.” Agen hanya mengikuti definisi alat. Alat memanggil endpoint sungguhan. Endpoint tidak punya guardrail. Manusia memberikan akses tulis ke proses yang tidak berhenti untuk bertanya apakah DELETE FROM users mencurigakan. Kasus lain di r/ClaudeAI menunjukkan pola serupa: agen masuk ke billing loop dan menghabiskan ratusan dolar dalam token. Permukaannya berbeda, tetapi kelas kegagalannya sama: API tidak diuji dengan benar.

Coba Apidog hari ini

💡 Jika Anda mengirimkan agen otonom yang memanggil API, panduan ini untuk Anda. Fokusnya: memalsukan endpoint eksternal saat pengembangan, meng-sandbox operasi destruktif, menulis contract test untuk skema alat, menetapkan batas anggaran per agen, dan melatih mode kegagalan sebelum produksi. Contoh menggunakan Apidog karena mendukung OpenAPI secara native, menyediakan mock server tanpa glue code, dan memiliki scenario test yang cocok dengan urutan panggilan alat agen.

TL;DR

Agen gagal di produksi ketika API yang dipanggil tidak punya guardrail: tidak ada batas laju, tidak ada idempotency, skema alat melenceng, atau operasi destruktif langsung tersedia. Perbaikannya:

1. Jalankan contract test antara definisi alat agen dan spesifikasi OpenAPI.
2. Gunakan mock server untuk endpoint destruktif.
3. Terapkan idempotency key dan batas anggaran per agen.
4. Putar ulang skenario kegagalan di CI.

Apidog membantu menggabungkan impor OpenAPI, mock, dan scenario runner dalam satu proyek.

Pendahuluan

Dulu, “menguji agen AI” berarti memberi prompt ke Claude atau GPT lalu menilai jawabannya. Sekarang agen memanggil fungsi, fungsi memanggil API, dan API berbicara dengan basis data, pemroses pembayaran, email transaksional, atau layanan pihak ketiga.

Definisi alat yang salah bukan masalah kosmetik. Batas laju yang hilang bukan detail kecil. Keduanya bisa menjadi insiden produksi.

Kasus viral Hacker News dan kasus billing loop Reddit menunjukkan akar masalah yang sama: kepercayaan ditempatkan di lapisan yang salah. Model memang penting, tetapi lapisan API adalah tempat Anda menghentikan kerusakan.

Artikel ini menunjukkan cara menguji integrasi API agen AI secara praktis:

• memvalidasi skema alat terhadap OpenAPI,
• menjalankan mock server untuk operasi berbahaya,
• menambahkan idempotency pada operasi tulis,
• menetapkan anggaran per agen,
• dan menjalankan skenario uji di CI.

Mengapa kegagalan agen terlihat seperti kegagalan API

Banyak post-mortem agen AI berakhir pada pola yang sama: model bukan protagonis utamanya. API-lah yang menentukan apakah kegagalan menjadi aman atau mahal.

Contoh 1: prompt injection

Pengguna mengunggah PDF dengan instruksi tersembunyi. Agen membacanya, lalu panggilan alat berikutnya menuju /admin/users dengan delete_all=true.

Model mengikuti instruksi. Masalah sebenarnya: API mengekspos operasi destruktif ke token yang berasal dari sesi pengguna.

Perbaikannya bukan hanya memperketat prompt. API harus menegakkan otorisasi berdasarkan konteks pengguna asli. OWASP memasukkan pola ini dalam LLM01 di LLM Top 10: mitigasinya ada di sisi otorisasi API, bukan hanya prompt engineering.

Contoh 2: skema alat melenceng

Spesifikasi OpenAPI menyatakan amount adalah integer dalam sen. Definisi alat agen menyatakan amount adalah float dalam dolar.

Tiga bulan kemudian, refund 19 sen berubah menjadi 19 dolar.

Model tidak salah. Model mengikuti skema yang Anda berikan. Kontrak antara alat dan API-lah yang rusak.

Contoh 3: batas laju hilang

Agen masuk ke retry loop dan memanggil endpoint email transaksional seribu kali dalam dua menit. Setiap retry menghabiskan biaya dan mengantrekan email sungguhan.

Solusinya: batas permintaan, anggaran per agen, dan respons 429 yang jelas.

Contoh 4: idempotency hilang

Agen memanggil POST /payments, terjadi timeout, lalu agen mencoba lagi. Tanpa idempotency key, pelanggan bisa ditagih dua kali.

API harus menyediakan cara untuk mengenali bahwa dua request adalah operasi logis yang sama.

Kesimpulannya: ketika agen gagal, audit kontrak API terlebih dahulu, lalu harness agen, baru model. Anda tidak selalu membutuhkan model yang lebih pintar. Anda membutuhkan API yang dapat diuji dan dibatasi.

Empat guardrail untuk integrasi agen-API

1. Jalankan contract test skema alat

Spesifikasi OpenAPI harus menjadi sumber kebenaran. Definisi alat agen sering ditulis terpisah, disalin dari dokumentasi, atau dibuat manual. Karena itu, keduanya mudah melenceng.

Tambahkan pemeriksaan di CI untuk membandingkan skema alat dengan OpenAPI.

Contoh validasi Python sederhana:

import json
from jsonschema import Draft202012Validator

def validate_tool_against_openapi(tool_def: dict, openapi_spec: dict) -> list[str]:
    """Return a list of mismatch errors, empty list = pass."""
    errors = []

    op = openapi_spec["paths"][tool_def["path"]][tool_def["method"].lower()]
    api_schema = op["requestBody"]["content"]["application/json"]["schema"]
    tool_schema = tool_def["input_schema"]

    api_props = set(api_schema.get("properties", {}).keys())
    tool_props = set(tool_schema.get("properties", {}).keys())

    for missing in api_props - tool_props:
        if missing in api_schema.get("required", []):
            errors.append(f"Tool missing required field: {missing}")

    for extra in tool_props - api_props:
        errors.append(f"Tool defines field not in API: {extra}")

    for prop, api_def in api_schema.get("properties", {}).items():
        if prop in tool_schema.get("properties", {}):
            tool_def_prop = tool_schema["properties"][prop]
            if api_def.get("type") != tool_def_prop.get("type"):
                errors.append(
                    f"Type mismatch on {prop}: API={api_def.get('type')} "
                    f"tool={tool_def_prop.get('type')}"
                )

    return errors

Jalankan pemeriksaan ini pada setiap PR yang mengubah:

• spesifikasi OpenAPI,
• definisi alat agen,
• skema request,
• atau DTO yang digunakan oleh API.

Jika errors tidak kosong, gagalkan build.

2. Gunakan sandbox dan mock untuk endpoint destruktif

Agen perlu tempat latihan. Jangan jadikan produksi sebagai tempat latihan.

Pola yang aman:

• Dev loop agen memakai mock server.
• Staging test memakai basis data sandbox.
• Produksi hanya dipakai setelah validasi dan persetujuan.

Untuk setiap endpoint yang mengubah state (POST, PUT, PATCH, DELETE), buat mock response dengan bentuk respons yang sama, tetapi tanpa efek samping.

Apidog dapat menghasilkan mock dari spesifikasi OpenAPI. Anda dapat mengarahkan base URL agen ke mock server, menjalankan ratusan iterasi, lalu melihat apakah agen memanggil endpoint yang tidak seharusnya.

Jika agen salah memahami dokumentasi dan mencoba PUT /users/{id}/delete, mock akan menangkap perilaku itu tanpa menyentuh tabel produksi.

Baca juga pola pengembangan contract-first.

3. Terapkan idempotency key dan soft delete

Setiap operasi tulis yang dapat dipanggil agen harus menerima idempotency key. Setiap penghapusan sebaiknya berupa soft delete secara default, dengan hard delete dipisahkan dan memerlukan persetujuan manusia.

Contoh middleware Express:

const idempotencyCache = new Map();

function idempotency(req, res, next) {
  const key = req.headers['idempotency-key'];

  if (!key) {
    return res.status(400).json({ error: 'Missing Idempotency-Key header' });
  }

  if (idempotencyCache.has(key)) {
    const cached = idempotencyCache.get(key);
    return res.status(cached.status).json(cached.body);
  }

  const originalJson = res.json.bind(res);

  res.json = function (body) {
    idempotencyCache.set(key, { status: res.statusCode, body });

    setTimeout(() => idempotencyCache.delete(key), 24 * 60 * 60 * 1000);

    return originalJson(body);
  };

  next();
}

app.post('/payments', idempotency, createPayment);

Agen harus membuat UUID untuk setiap operasi logis dan memakai UUID yang sama saat retry.

Contoh:

POST /payments
Idempotency-Key: refund-6f7c1c7e-4e3b-4b31-9c1d-91c9c7f7e4ab
Content-Type: application/json

{
  "customer_id": "cus_123",
  "amount": 1900,
  "currency": "usd"
}

Jika request pertama berhasil tetapi responsnya timeout, request kedua mengembalikan respons cache, bukan membuat pembayaran baru.

4. Tetapkan batas anggaran per agen

Setiap agen harus punya batas:

• anggaran token,
• jumlah request,
• biaya maksimum,
• durasi eksekusi,
• dan kedalaman panggilan alat.

Contoh batas awal:

• 50.000 token per sesi,
• 30 panggilan API per menit,
• 500 sen biaya kumulatif,
• maksimal 10 panggilan alat bersarang.

Ketika batas tercapai, API atau gateway mengembalikan 429:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-Budget-Exceeded: api_calls_per_minute
Content-Type: application/json

{
  "error": "Agent budget exceeded",
  "limit": "api_calls_per_minute",
  "retry_after_seconds": 60
}

Perencana agen dapat melaporkan status ini ke manusia atau menghentikan tugas.

Keempat kontrol ini saling menutup celah:

• Contract test menangkap skema rusak.
• Mock menangkap operasi destruktif.
• Idempotency menangkap retry berbahaya.
• Anggaran menangkap runaway loop.

Uji panggilan API agen dengan Apidog

Berikut alur kerja implementasi menggunakan Apidog. Anda membutuhkan:

• spesifikasi OpenAPI,
• definisi alat agen,
• daftar endpoint yang dapat dipanggil agen,
• dan skenario panggilan alat yang ingin diuji.

Langkah 1: Impor spesifikasi OpenAPI

Buat proyek baru di Apidog, lalu impor OpenAPI 3.x.

Apidog akan membaca:

• path,
• method,
• request body,
• response schema,
• contoh payload,
• dan definisi parameter.

Jika API Anda belum memiliki OpenAPI, buat dulu. Agen yang aman membutuhkan satu sumber kebenaran yang dibaca manusia, CI, dan definisi alat.

Jika Anda memulai dari awal, baca panduan alur kerja API design-first.

Langkah 2: Buat mock response untuk endpoint destruktif

Identifikasi semua endpoint yang mengubah data:

• POST
• PUT
• PATCH
• DELETE

Untuk setiap endpoint, tambahkan mock response.

Gunakan data yang jelas palsu agar mudah dikenali di log:

{
  "id": "mock_user_1970_001",
  "email": "mock_user_1970@example.test",
  "deleted": true,
  "deleted_at": "1970-01-01T00:00:00Z"
}

Mulai mock server. Apidog memberi URL stabil seperti:

https://mock.apidog.com/m1/your-project-id/

Lalu ubah base URL agen lewat variabel lingkungan:

AGENT_API_BASE_URL=https://mock.apidog.com/m1/your-project-id/

Jangan hardcode URL mock di prompt agen.

Langkah 3: Tulis skenario urutan panggilan agen

Gunakan skenario Apidog untuk memodelkan urutan panggilan alat.

Contoh agen penyeleksi tiket dukungan:

1. POST /auth/token dengan kredensial pengujian.
2. Simpan bearer token.
3. GET /tickets?status=open.
4. Simpan ID tiket pertama.
5. POST /tickets/{id}/triage.
6. Assert status 200.
7. Simpan nilai assigned_to.
8. POST /notifications.
9. Assert isi pesan cocok dengan regex.

Contoh assertion yang ingin Anda validasi:

status == 200
response.assigned_to != null
response.category in ["billing", "technical", "account"]
notification.message matches /Ticket #[0-9]+ has been assigned/

Dengan ini, Anda melatih perilaku agen terhadap mock server sebelum agen melihat produksi.

Untuk pola skenario yang lebih lengkap, lihat pengujian API untuk insinyur QA.

Langkah 4: Jalankan skenario dari CI

Jalankan skenario pada setiap PR yang menyentuh API atau definisi alat.

Contoh perintah:

apidog run -t scenario-id --env test

Contoh GitHub Actions:

name: Agent API Scenario Tests

on:
  pull_request:
    paths:
      - "openapi/**"
      - "agents/**"
      - "tools/**"

jobs:
  test-agent-api:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Run Apidog scenario
        run: apidog run -t ${{ secrets.APIDOG_SCENARIO_ID }} --env test
        env:
          APIDOG_TOKEN: ${{ secrets.APIDOG_TOKEN }}

Tujuannya sederhana: perubahan skema atau alat tidak boleh masuk tanpa memutar ulang skenario panggilan agen.

Langkah 5: Bandingkan dua versi model

Saat mengganti model, jangan hanya menguji kualitas jawaban. Uji juga perilaku panggilan alat.

Alurnya:

1. Jalankan agen dengan model A terhadap skenario yang sama.
2. Simpan tool-call trace.
3. Jalankan agen dengan model B.
4. Simpan trace baru.
5. Bandingkan request body, urutan panggilan, dan field yang dikirim.

Contoh perbedaan yang perlu ditangkap:

{
  "ticket_id": "T-123",
- "priority": "medium",
+ "priority": "high",
  "category": "billing"
}

Atau:

{
  "amount": 1900,
- "currency": "usd"
}

Perubahan kecil seperti ini bisa berdampak besar ketika agen memanggil API pembayaran, CRM, atau sistem internal.

Pola ini juga relevan saat mengevaluasi model baru, seperti dibahas dalam artikel integrasi API GPT-5.5.

Teknik lanjutan

Sematkan temperature ke nol saat pengujian

Saat menguji perilaku panggilan alat, gunakan konfigurasi deterministik:

{
  "temperature": 0,
  "seed": 12345
}

Anda sedang menguji lapisan alat, bukan kreativitas model.

Simpan snapshot tool-call trace

Catat urutan panggilan alat dan argumennya:

[
  {
    "tool": "get_open_tickets",
    "arguments": {
      "status": "open"
    }
  },
  {
    "tool": "triage_ticket",
    "arguments": {
      "ticket_id": "T-123",
      "category": "billing"
    }
  }
]

Bandingkan dengan baseline sebelumnya. Jika agen tiba-tiba memanggil /users dua kali atau melewatkan field wajib, gagalkan pengujian.

Jangan beri kredensial produksi langsung ke agen

Gunakan scoped service account.

Hindari pola ini:

PROD_DATABASE_URL=postgres://...
STRIPE_SECRET_KEY=sk_live_...

Gunakan pola ini:

• kredensial produksi disimpan di vault,
• agen memakai token terbatas,
• request produksi melewati proxy,
• proxy menandatangani request dengan token berumur pendek.

Pisahkan kunci baca dan tulis

Sebagian besar tugas agen hanya butuh akses baca.

Gunakan dua kelas kredensial:

• read-only key untuk analisis dan pencarian,
• write key hanya untuk operasi yang memiliki persetujuan manusia.

Ini mengurangi radius kerusakan jika agen terkena prompt injection.

Gunakan HTTP 423 untuk persetujuan manusia

Jika agen mencoba operasi yang perlu konfirmasi manusia, kembalikan 423 Locked:

HTTP/1.1 423 Locked
Content-Type: application/json

{
  "error": "Human approval required",
  "confirmation_url": "https://internal.example.com/approvals/abc123"
}

403 berarti “tidak boleh”. 423 lebih cocok untuk “belum boleh sampai dikonfirmasi”.

Gagal tertutup pada schema drift

Jika definisi alat tidak cocok dengan OpenAPI, gagalkan build. Jangan hanya mengirim peringatan.

Biaya beberapa build gagal lebih murah daripada satu insiden produksi.

Kesalahan umum yang perlu dihindari

• Meng-hardcode URL mock ke dalam prompt agen.
• Tidak menambahkan idempotency pada endpoint “kecil” seperti pengiriman email.
• Mencatat full request body di produksi tanpa menyamarkan PII.
• Memberi agen akses langsung ke basis data.
• Menganggap skor kepercayaan model sama dengan keamanan API.
• Mengizinkan satu token agen mengakses operasi baca dan tulis sekaligus.
• Tidak menjalankan skenario uji di CI.

Jika agen Anda memanggil banyak layanan internal, baca juga pola pengujian untuk arsitektur microservices.

Alternatif dan perkakas

Jika Anda sudah memakai LangSmith, tetap gunakan untuk evaluasi tingkat prompt dan tambahkan lapisan pengujian API terpisah.

Jika Anda mencari alternatif Postman, lihat Apidog sebagai pengganti yang kuat.

Banyak tim menggunakan kombinasi:

• LangSmith untuk evaluasi agen,
• Apidog untuk contract test, mock, dan skenario API.

Keduanya menguji lapisan yang berbeda.

Kasus penggunaan dunia nyata

Agen memperbarui data produksi

Tim customer success membangun agen yang memperbarui field akun dari tiket dukungan.

Sebelum peluncuran, mereka:

• mewajibkan idempotency key untuk semua endpoint tulis,
• menjalankan 200 skenario di Apidog terhadap basis data sandbox,
• dan memvalidasi enum di request body.

Pengujian menangkap dua kasus ketika agen mencoba mengatur subscription_status ke string yang tidak valid. Mereka menambahkan validasi skema sebelum rilis.

Agen memanggil API pembayaran

Tim fintech membangun agen refund otomatis.

Batas yang mereka tetapkan:

• maksimal 5 refund per sesi,
• maksimal 50 dolar per refund,
• idempotency wajib pada setiap panggilan.

Mereka menjalankan contract test suite terhadap OpenAPI Stripe pada setiap PR. Hasilnya, refund dapat diproses tanpa biaya ganda.

Agen menyeleksi issue GitHub

Tim platform membangun agen triage issue yang terinspirasi oleh Clawsweeper.

Mereka:

• membuat mock API GitHub di Apidog,
• menjalankan 50 scenario test,
• mencakup issue yang dihapus, label hilang, dan input pengguna salah format,
• menemukan beberapa crash sebelum peluncuran.

Checklist implementasi

Gunakan checklist ini sebelum agen Anda memanggil API produksi:

• [ ] Semua definisi alat punya pasangan endpoint di OpenAPI.
• [ ] CI menjalankan schema diff antara alat agen dan OpenAPI.
• [ ] Semua operasi tulis menerima Idempotency-Key.
• [ ] Semua operasi destruktif memakai soft delete secara default.
• [ ] Agen tidak punya kredensial produksi langsung.
• [ ] Kunci baca dan tulis dipisahkan.
• [ ] Mock server tersedia untuk semua endpoint destruktif.
• [ ] Skenario panggilan agen dijalankan di CI.
• [ ] Ada batas token, request, biaya, dan durasi.
• [ ] Respons 429 dan 423 ditangani oleh perencana agen.
• [ ] Tool-call trace disimpan dan dibandingkan dengan baseline.
• [ ] Log produksi menyamarkan token, email, dan identifier sensitif.

Kesimpulan

Agen bukan selalu masalahnya. API bisa menjadi masalah atau solusi, tergantung apakah Anda mengujinya.

Lima hal yang perlu Anda terapkan:

1. Perlakukan skema alat sebagai kontrak.
2. Jalankan contract test di CI.
3. Gunakan mock untuk endpoint destruktif.
4. Wajibkan idempotency key pada operasi tulis.
5. Tetapkan anggaran per agen dan putar ulang skenario pada setiap PR.

Insiden agen AI tidak akan berhenti. Tim yang pulih cepat adalah tim yang sudah memasang guardrail sebelum produksi.

Mulai dari langkah paling sederhana: unduh Apidog, impor OpenAPI Anda, lalu buat mock server untuk endpoint destruktif. Untuk perspektif QA, baca alat pengujian API untuk insinyur QA. Untuk konteks tambahan tentang definisi alat agen, lihat cara menulis berkas AGENTS.md.

FAQ

Bagaimana cara menguji panggilan API agen AI tanpa menghabiskan uang untuk token?

Jalankan agen terhadap mock server selama pengembangan. URL mock Apidog mengembalikan respons realistis tanpa menyentuh layanan produksi. Gunakan temperature 0 dan set prompt kecil yang tetap. Lihat juga daftar periksa pengujian insinyur QA.

Apa perbedaan antara menguji agen dan menguji API?

Pengujian agen memeriksa apakah model memilih alat yang tepat dan mengisi argumen dengan benar.

Pengujian API memeriksa apakah endpoint berperilaku benar saat dipanggil.

Keduanya perlu diuji terpisah. Agen yang bagus tetap bisa gagal jika API rusak. API yang bagus tetap bisa disalahgunakan oleh agen yang salah memilih alat.

Apakah saya memerlukan idempotency key pada setiap endpoint?

Untuk operasi tulis, ya.

Operasi baca sudah idempotent secara definisi. Operasi tulis tidak. Agen akan melakukan retry, dan retry tanpa idempotency bisa membuat pembayaran ganda, email ganda, atau baris duplikat.

Bagaimana cara mencegah prompt injection memicu panggilan API berbahaya?

Jangan hanya bergantung pada prompt. API harus menegakkan otorisasi berdasarkan konteks pengguna asli.

Jika pengguna tidak boleh mengakses /admin/delete-all-users, agen yang bertindak atas nama pengguna itu juga tidak boleh mengaksesnya, apa pun isi prompt.

Bisakah saya menggunakan Apidog dengan Claude atau GPT?

Ya. Arahkan definisi alat agen ke URL mock Apidog selama pengujian. Saat ingin menguji terhadap staging atau produksi, ubah base URL lewat variabel lingkungan.

Berapa batas anggaran yang tepat untuk agen?

Mulai ketat, lalu longgarkan berdasarkan data.

Contoh awal:

• 50.000 token per sesi,
• 30 panggilan API per menit,
• 5 dolar per tugas.

Pantau selama dua minggu. Naikkan batas yang sering tercapai secara sah. Turunkan batas yang tidak pernah digunakan.

Bagaimana mendeteksi schema drift antara alat agen dan API?

Jalankan schema diff di CI pada setiap PR. Bandingkan skema JSON definisi alat agen dengan skema request body OpenAPI untuk endpoint yang sama. Jika berbeda, gagalkan build.