Integrasi autonomous agents dengan backend melalui mekanisme tool calling sering kali menyebabkan kegagalan build yang tidak konsisten (flaky) di Continuous Integration (CI). Masalah utama berakar dari sifat non-deterministik LLM, skema JSON Schema yang ambigu, dan penanganan kegagalan eksekusi yang rapuh saat agen mengalami halusinasi tipe data. Artikel ini membahas penerapan uji kontrak API agentic untuk memastikan integritas antarmuka tool tanpa bergantung pada pemanggilan model live di pipeline CI.
Akar Masalah Flakiness pada Agent Tool Calling
Pengujian integrasi yang melibatkan model bahasa secara langsung di CI memiliki tiga titik kegagalan utama:
- Non-deterministik Payload: LLM dapat menghasilkan argumen yang valid secara sintaksis pada run pertama, namun mengubah format tanggal, urutan field, atau representasi data pada run berikutnya.
- Skema JSON yang Longgar: Definisi OpenAPI atau JSON Schema tanpa konfigurasi restriktif seperti
additionalProperties: falsemembuka celah halusinasi field yang diabaikan oleh backend parser. - Kegagalan Propagasi Error: Saat argumen tidak sesuai kontrak, backend sering mengembalikan HTTP 500 tanpa konteks, alih-alih format RFC 7807 problem details yang dapat dipahami agen untuk memicu self-correction.
Solusinya adalah memisahkan pengujian menjadi dua batas: validasi integritas skema tool terhadap parser backend, dan validasi respons runtime terhadap payload terisolasi menggunakan snapshot deterministik.
Strategi Uji Kontrak: Skema, Determinisme, dan Boundary Testing
Uji kontrak untuk API agentic memerlukan tiga lapisan verifikasi:
- Validasi Skema Tool: Memastikan payload definisi tool yang diekspos ke agent mematuhi spesifikasi JSON Schema Draft 7 atau Draft 2020-12 dan kompatibel dengan parser model (OpenAI, Anthropic, atau model lokal).
- Deterministic Snapshot Mocking: Menguji handler endpoint menggunakan fixture data input LLM yang telah distandardisasi. Tidak ada pemanggilan network ke penyedia LLM selama CI berlangsung.
- Boundary & Type Hallucination Testing: Menstimulasi kesalahan khas agen seperti mengirimkan
stringuntuk fieldinteger, mengirimkan array kosong, atau menyuntikkan properti acak untuk memverifikasi handling error backend.
Implementasi Runnable Test Suite Tanpa Dependency Tambahan
Berikut adalah implementasi suite pengujian berbasis Node.js standard library (node:test dan node:assert) untuk memverifikasi kontrak API agentic:
// contract.test.mjs
import test from 'node:test';
import assert from 'node:assert/strict';
// 1. Definisi Kontrak Tool Backend
const bookFlightSchema = {
name: 'book_flight',
parameters: {
type: 'object',
properties: {
origin: { type: 'string', pattern: '^[A-Z]{3}$' },
destination: { type: 'string', pattern: '^[A-Z]{3}$' },
passengers: { type: 'integer', minimum: 1, maximum: 9 }
},
required: ['origin', 'destination', 'passengers'],
additionalProperties: false
}
};
// 2. Parser & Backend Logic Simulator
function executeToolCall(rawCall) {
if (!rawCall || typeof rawCall !== 'object') {
return { status: 400, error: 'INVALID_PAYLOAD' };
}
const { origin, destination, passengers } = rawCall;
const iataRegex = /^[A-Z]{3}$/;
if (!iataRegex.test(origin) || !iataRegex.test(destination)) {
return { status: 422, error: 'INVALID_IATA_CODE', field: !iataRegex.test(origin) ? 'origin' : 'destination' };
}
if (typeof passengers !== 'number' || !Number.isInteger(passengers) || passengers < 1 || passengers > 9) {
return { status: 422, error: 'INVALID_PASSENGER_COUNT' };
}
const extraKeys = Object.keys(rawCall).filter(k => !['origin', 'destination', 'passengers'].includes(k));
if (extraKeys.length > 0) {
return { status: 422, error: 'UNRECOGNIZED_ARGUMENTS', details: extraKeys };
}
return { status: 200, result: { confirmationId: 'BK-8921', status: 'CONFIRMED' } };
}
// 3. Test Cases
test('Uji Kontrak: Skema tool harus terdefinisi ketat', () => {
assert.equal(bookFlightSchema.parameters.additionalProperties, false);
assert.ok(bookFlightSchema.parameters.required.includes('origin'));
});
test('Uji Kontrak: Eksekusi sukses dengan deterministik snapshot', () => {
const deterministicAgentCall = {
origin: 'CGK',
destination: 'DPS',
passengers: 2
};
const res = executeToolCall(deterministicAgentCall);
assert.equal(res.status, 200);
assert.equal(res.result.status, 'CONFIRMED');
});
test('Boundary Test: Tolak tipe data terhalusinasi (string sebagai integer)', () => {
const invalidTypePayload = {
origin: 'CGK',
destination: 'DPS',
passengers: 'two' // Halusinasi umum pada small parameter models
};
const res = executeToolCall(invalidTypePayload);
assert.equal(res.status, 422);
assert.equal(res.error, 'INVALID_PASSENGER_COUNT');
});
test('Boundary Test: Tolak field tambahan hasil halusinasi LLM', () => {
const hallucinatedKeysPayload = {
origin: 'CGK',
destination: 'DPS',
passengers: 1,
seatClass: 'Business' // Field tidak terdaftar pada skema
};
const res = executeToolCall(hallucinatedKeysPayload);
assert.equal(res.status, 422);
assert.equal(res.error, 'UNRECOGNIZED_ARGUMENTS');
});
Jalankan pengujian ini di CI menggunakan command bawaan tanpa installasi package:
node --test contract.test.mjsDesain API Error Response untuk Agen
Saat validasi kontrak gagal di production, API tidak boleh hanya mengembalikan respons generic. Format respons terstruktur memvalidasi kesalahan kembali ke context window agent agar ia dapat melakukan mitigasi secara otonom:
{
"type": "https://api.domain.com/errors/validation-failed
Komentar
0 komentar
Masuk ke akun kamu untuk ikut berkomentar.
Belum ada komentar
Jadilah yang pertama ikut berdiskusi!