# Evaluasi AI Agent: Cara Menguji Tool Call dan Trajectory

> Agent bisa memberi jawaban yang benar setelah memanggil tool yang salah, dengan argumen yang salah, dalam urutan yang salah. Begini cara menilai trajectory-nya, dari production trace sampai assertion promptfoo untuk agent di NestJS.

URL: https://www.matthewswong.com/id/blog/ai-agent-evals-trajectory-testing/

- Author: Matthews Wong (https://www.matthewswong.com/id/about/)
- Published: 2026-10-01
- Updated: 2026-10-01
- Category: AI

> **Key takeaway:** Evaluasi AI agent harus menilai trajectory, bukan hanya jawaban akhir: tool apa yang dipilih agent, argumen yang dikirim, urutan pemanggilan, apakah tujuan tercapai, dan berapa langkah yang dihabiskan. Kirim span tool lewat OpenTelemetry, ubah production trace menjadi test case, lalu uji dengan assertion trajectory promptfoo di CI.

Bayangkan sebuah agent helpdesk ERP yang menangani permintaan credit note. Seorang staf customer service mengetik bahwa PT Sinar Jaya meminta credit note untuk dua unit rusak pada sebuah invoice. Agent membalas dengan ringkasan yang sopan, terlihat benar, dan lengkap dengan nomor draft. Eval yang hanya mengecek jawaban akhir menilainya lulus. Trace-nya bercerita lain: agent mencari customer dengan sebagian nama, memilih PT Sinar Jaya yang salah dari tiga kandidat, lalu membuat draft untuk invoice yang tidak pernah ia ambil. Jawabannya enak dibaca karena model memang pandai menulis; pekerjaan di baliknya salah.

Celah itulah alasan evaluasi AI agent membutuhkan unit yang berbeda dari evaluasi prompt. Ada post lain di situs ini tentang LLM eval di CI untuk prompt tunggal: golden dataset, assertion, dan pass-rate gate. Post ini turun satu tingkat, ke jalur multi-langkah yang ditempuh agent. Isinya: apa saja yang perlu dinilai dalam trajectory, cara membangun dataset dari production trace, cara membuat agent NestJS mengirim span yang bisa dibaca eval, dan cara menulis assertion trajectory promptfoo, ditutup dengan perbandingan OpenAI trace grading dan evaluasi Google ADK. Setiap nama assertion dan opsi di bawah diambil dari dokumentasi vendor yang berlaku saat ini.

## Kenapa eval yang hanya melihat output melewatkan kegagalan agent

Pengecekan jawaban akhir membandingkan satu string dengan ekspektasi. Satu run agent adalah rangkaian keputusan, dan kegagalan yang paling mahal biasanya terjadi di tengahnya, tertutup oleh pesan akhir yang lancar. Tabel berikut memetakan kegagalan agent yang umum ke apa yang bisa dilihat oleh tiap jenis pengecekan.

| Kegagalan dalam run | Yang terlihat oleh cek jawaban akhir | Yang ditangkap cek trajectory |
| --- | --- | --- |
| Tool benar, record salah: agent mencari customer yang keliru | Balasan masuk akal yang menyebut nama customer, biasanya lulus | tool-args-match gagal karena id customer atau nomor invoice berbeda |
| Menulis sebelum membaca: draft dibuat tanpa mengambil invoice | Tidak ada, balasan tetap menyebut nomor draft | tool-sequence gagal karena get_invoice tidak mendahului operasi tulis |
| Aksi terlarang: agent mem-posting dokumen alih-alih membuat draft | Sering tidak ada, atau balasan yang terdengar makin membantu | Cek tool-used yang dinegasikan langsung gagal begitu tool posting muncul |
| Looping: pencarian yang sama diulang delapan kali sebelum menjawab | Jawaban benar, hanya lebih lambat dan lebih mahal | step-count dengan max gagal, dan batas token menangkap biayanya |
| Argumen halusinasi: flag tambahan seperti force: true | Sama sekali tidak ada | tool-args-match dalam mode exact menolak key yang tidak diharapkan |

Polanya: pesan akhir adalah artefak paling tidak informatif dari sebuah run agent. Pesan itu ditulis paling akhir, oleh komponen yang paling mahir terdengar benar. Cek trajectory memindahkan assertion ke tempat keputusan dibuat, yang juga tempat perbaikannya nanti dilakukan.

## Apa yang dinilai dalam trajectory agent

Lima properti mencakup hampir semua kegagalan agent yang layak memblokir merge. Masing-masing cocok dengan jenis pengecekan yang berbeda, dan memisahkannya memberi tahu bagian agent mana yang mengalami regresi, bukan satu skor campuran.

- Pemilihan tool. Apakah agent memanggil tool yang dibutuhkan tugas, dan menghindari tool yang tidak boleh dipanggil untuk request ini? Ini cek termurah dan yang paling dulu menangkap regresi routing dan prompt.
- Argumen. Apakah agent mengirim identifier, nominal, dan filter yang benar? Partial match cukup untuk sebagian besar kasus; exact match layak dipakai untuk tool tulis, karena argumen tambahan hasil karangan adalah risiko nyata.
- Urutan. Apakah operasi baca terjadi sebelum operasi tulis yang bergantung padanya? Sebagian besar urutan cukup mensyaratkan langkah yang diharapkan muncul berurutan, dengan pemanggilan lain boleh di sela-selanya; urutan exact yang ketat untuk flow pendek yang kritis.
- Keberhasilan tujuan. Apakah run benar-benar mencapai yang diminta user? Ini satu-satunya properti yang biasanya butuh model grader, karena jalur yang benar tetap bisa berakhir dengan kesimpulan yang salah.
- Biaya per run. Berapa langkah dan token yang dihabiskan? Perubahan yang menjaga jawaban tetap benar tetapi menggandakan tool call adalah regresi yang akan terlihat di tagihan sebelum dikeluhkan user.

Nilai properti yang deterministik dengan cek deterministik, dan simpan model grader untuk keberhasilan tujuan. Model grader yang ditanya apakah tool call-nya masuk akal akan tidak konsisten, padahal perbandingan string bisa memberi hasil yang pasti dan gratis.

## Bangun dataset eval dari production trace

Test case trajectory terbaik adalah run yang sudah pernah salah. Edge case karangan menguji apa yang Anda bayangkan; trace menguji apa yang benar-benar diketik user, termasuk nama perusahaan yang ambigu dan nomor invoice yang diingat setengah, yang membuat agent salah jalan.

1. Ambil sampel trace dari production setiap minggu, utamakan run yang berakhir dengan koreksi, handover ke manusia, atau keluhan user.
2. Untuk setiap run yang gagal, tuliskan trajectory yang akan ditempuh operator yang kompeten: tool-nya, argumen kuncinya, dan urutannya.
3. Ganti data pribadi dan data customer dengan nilai fiktif yang stabil, tetapi pertahankan bentuk yang memicu kegagalan, misalnya dua customer dengan nama yang sama.
4. Bekukan kasus itu sebagai file test di repository, supaya setiap perubahan dataset muncul di diff pull request bersama kode yang memperbaikinya.
5. Simpan juga beberapa run yang lulus, supaya perbaikan untuk satu kegagalan tidak diam-diam merusak jalur yang umum.

Kasus yang diturunkan dari skenario pembuka terlihat seperti ini. Assertion-nya menggambarkan jalur, bukan kalimat, sehingga test tetap valid walaupun balasan agent ditulis ulang.

## Instrumentasi agent NestJS agar trajectory-nya terlihat

promptfoo membaca trajectory dari span OpenTelemetry. Dokumentasi tracing-nya menyebut bahwa promptfoo menyertakan header traceparent saat memanggil HTTP target, dan aplikasi di balik target bisa menambahkan child span di bawah trace tersebut. promptfoo mengenali tool call dari atribut span seperti tool.name, dan argumen dari atribut seperti tool.arguments, dengan nilai string di-parse sebagai JSON bila memungkinkan. Jadi agent yang berjalan di NestJS butuh dua hal: OpenTelemetry yang dijalankan sebelum aplikasi, dengan HTTP instrumentation untuk menangkap traceparent yang masuk, dan span di sekeliling setiap eksekusi tool.

File tracer diimpor paling awal di main.ts. Wrapper ini menjadi satu-satunya tempat tool dieksekusi, yang sekaligus memberi satu titik untuk menerapkan timeout dan audit log nantinya.

> Gunakan simple span processor saat mengekspor ke receiver eval. Batching processor menahan span di memori dan mengirimnya belakangan, sehingga HTTP response bisa sampai ke promptfoo lebih dulu daripada span tool, dan run yang sebenarnya benar gagal di semua assertion trajectory. Di production, batching processor tetap pilihan yang tepat.

Argumen tool sering berisi nama customer dan nominal. Receiver promptfoo menerima daftar redactAttributes yang mengganti nilai atribut yang cocok sebelum disimpan, serta pengaturan retentionDays untuk memangkas trace lama. Dokumentasinya memperingatkan bahwa pola yang pendek terlalu luas cakupannya, karena key token juga cocok dengan gen_ai.usage.input_tokens, jadi tulis nama key atribut yang persis ingin disembunyikan.

## Evaluasi AI agent dengan assertion trajectory promptfoo

Setelah span mengalir, config mengarahkan HTTP provider ke endpoint NestJS, mengaktifkan tracing dengan OTLP receiver bawaan di port default 4318, lalu membuat assertion atas jalurnya. Keluarga assertion-nya adalah trajectory:tool-used, trajectory:tool-args-match, trajectory:tool-sequence, trajectory:step-count, dan trajectory:goal-success yang dinilai oleh model.

Beberapa opsi mengerjakan sebagian besar tugas. tool-used menerima satu nama, daftar nama, atau pola glob dengan jumlah min dan max. tool-args-match default-nya mode partial, di mana properti yang diharapkan dicocokkan secara rekursif sebagai subset; mode exact menolak argumen tambahan apa pun, dan daftar defaults serta ignore membuat mode exact bisa menoleransi default pagination dan id yang selalu berubah seperti idempotency key. tool-sequence default-nya in_order, yang mengizinkan pemanggilan lain di antara langkah yang diharapkan, sedangkan exact mensyaratkan urutan di trace sama persis langkah demi langkah. Setiap assertion promptfoo bisa dinegasikan dengan prefix not-, dan begitulah tool terlarang diekspresikan.

> Letakkan aturan yang berlaku untuk semua request di defaultTest, jangan diulang per kasus. Tidak ada tool posting, tidak ada operasi tulis sebelum operasi baca yang sesuai, dan batas jumlah langkah adalah kebijakan, bukan test case, dan mendeklarasikannya sekali berarti kasus baru tidak mungkin lupa.

## Keberhasilan tujuan, aturan custom, dan budget biaya

trajectory:goal-success dinilai oleh model dan pada contoh di dokumentasi menerima provider secara eksplisit. Beri tujuan yang ditulis sebagai hasil yang bisa diverifikasi grader, misalnya customer dan invoice mana yang harus dirujuk draft, bukan instruksi samar untuk bersikap membantu. Karena ini penilaian model, anggap kegagalan di sini sebagai sinyal untuk membaca trace, dan biarkan cek deterministik yang memblokir merge.

Aturan yang tidak bisa diekspresikan assertion bawaan masuk ke assertion javascript, yang menerima trace sebagai context.trace.spans. Mekanisme yang sama menangani dimensi biaya: jumlahkan pemakaian token di semua span dan gagalkan run yang melewati batas. Batas di bawah hanya contoh yang perlu dikalibrasi dari baseline run Anda sendiri, bukan rekomendasi.

promptfoo juga punya assertion cost, tetapi dokumentasinya mencatat assertion itu butuh provider yang mengembalikan informasi biaya, dan HTTP target biasa umumnya tidak melakukannya. Menghitung token dari span sendiri berfungsi untuk backend apa pun, dan cek step-count memberi sinyal kedua yang tidak bergantung pada model untuk mendeteksi loop.

## Perbandingan promptfoo, OpenAI trace grading, dan evaluasi Google ADK

promptfoo bukan satu-satunya cara menilai trajectory. OpenAI dan Google sama-sama menyediakan evaluasi yang memahami trajectory, masing-masing terikat ke stack agent miliknya. Perbedaannya lebih penting daripada yang terlihat dari daftar fitur.

| Opsi | Tempat cek disimpan | Pencocokan trajectory | Paling cocok untuk |
| --- | --- | --- | --- |
| Assertion trajectory promptfoo | YAML di repository, dijalankan dari CLI di CI | tool-used, tool-args-match mode partial atau exact, tool-sequence mode in_order atau exact, step-count, goal-success yang dinilai model | Stack apa pun yang mengirim span OpenTelemetry, termasuk agent NestJS buatan sendiri |
| OpenAI trace grading | Dashboard OpenAI di Logs, Traces, lalu Grade all ke dashboard evaluasi | Grader yang diterapkan ke trace dari aplikasi Agents SDK; opsi run mencakup model, rentang tanggal, dan tool call | Tim yang sudah melakukan tracing lewat OpenAI Agents SDK dan ingin trace yang dinilai tanpa tooling baru |
| Evaluasi Google ADK | File test.json atau evalset.json, dijalankan dengan adk eval, pytest, atau UI adk web | tool_trajectory_avg_score dengan EXACT, IN_ORDER, atau ANY_ORDER; tiap invocation bernilai 1.0 atau 0.0 lalu dirata-rata per kasus, threshold default 1.0 | Agent yang dibangun dengan ADK, terutama flow multi-turn yang memakai user simulation |

Dua catatan mengubah pilihan. Dokumentasi graders OpenAI menyatakan bahwa OpenAI sedang men-deprecate graders sebagai bagian dari workflow evals dan fine-tuning yang didukungnya, dan merujuk ke halaman deprecations untuk jadwalnya, jadi suite eval yang hanya ada di dashboard adalah migrasi yang tinggal menunggu waktu. Dokumentasi ADK mencatat bahwa tool_trajectory_avg_score, response_match_score, dan final_response_match_v2 tidak didukung bersama user simulation, sehingga run multi-turn yang disimulasikan beralih ke kriteria berbasis rubrik seperti rubric_based_tool_use_quality_v1. Cek yang tinggal di repository Anda, terhadap span yang Anda kirim sendiri, adalah yang bertahan ketika vendor berubah.

> Jangan jalankan eval terhadap tool tulis yang live. Arahkan agent NestJS ke ERP staging atau lapisan tool yang di-stub, karena eval trajectory yang membuat credit note sungguhan adalah insiden production yang kebetulan disertai laporan test.

Aturan yang perlu dibawa: agent dinilai dari apa yang ia lakukan, bukan dari apa yang ia katakan. Jadikan setiap tool call sebagai span, ubah run yang pernah salah menjadi trajectory yang dibekukan, cek pemilihan tool, argumen, dan urutan secara deterministik, simpan model grader untuk keberhasilan tujuan, dan pasang batas untuk langkah dan token. Jawaban akhir tetap penting, tetapi itu hal terakhir yang dicek, bukan satu-satunya.

## Sumber

- promptfoo — Deterministic assertions, termasuk trajectory:tool-used, tool-args-match, tool-sequence, dan step-count
- promptfoo — Tracing: OTLP receiver, propagasi traceparent, dan assertion trajectory
- Dokumentasi OpenAI API — Trace grading
- Dokumentasi OpenAI API — Graders
- Dokumentasi Agent Development Kit — Evaluation criteria

## Source links

- https://www.promptfoo.dev/docs/configuration/expected-outputs/deterministic/
- https://www.promptfoo.dev/docs/tracing/
- https://developers.openai.com/api/docs/guides/trace-grading
- https://developers.openai.com/api/docs/guides/graders
- https://adk.dev/evaluate/criteria/

## FAQ

### Apa itu evaluasi trajectory untuk AI agent?

Evaluasi trajectory menilai jalur yang ditempuh agent, bukan hanya jawaban akhirnya. Yang dicek adalah tool apa yang dipanggil, argumen yang dikirim, urutan pemanggilan, apakah tujuan tercapai, dan berapa langkah yang dihabiskan. Cara ini menangkap kegagalan seperti bertindak pada record yang salah, yang biasanya tertutup oleh pesan akhir yang lancar.

### Kenapa eval jawaban akhir tidak cukup untuk AI agent?

Agent bisa memberi balasan yang terdengar benar setelah memanggil tool yang salah, memakai id customer yang keliru, atau menulis sebelum membaca record. Cek jawaban akhir hanya membandingkan pesan terakhir, sehingga run seperti itu tetap lulus. Menilai trace memindahkan pengecekan ke tempat keputusan benar-benar dibuat.

### Assertion promptfoo apa saja yang menguji tool call agent?

promptfoo menyediakan trajectory:tool-used, trajectory:tool-args-match, trajectory:tool-sequence, trajectory:step-count, dan trajectory:goal-success yang dinilai oleh model. tool-args-match mendukung mode partial dan exact, sedangkan tool-sequence mendukung mode in_order dan exact. Semuanya membaca data trace OpenTelemetry, jadi tracing harus diaktifkan untuk eval.

### Bagaimana cara mengevaluasi agent di NestJS dengan promptfoo?

Panggil endpoint NestJS dengan HTTP provider promptfoo dan aktifkan tracing dengan OTLP receiver bawaannya. promptfoo mengirim header traceparent, sehingga HTTP instrumentation OpenTelemetry di NestJS bergabung ke trace yang sama. Bungkus setiap eksekusi tool dengan span yang punya atribut tool.name dan tool.arguments agar assertion trajectory bisa membacanya.

### Bagaimana Google ADK menilai trajectory tool?

Google ADK memakai kriteria tool_trajectory_avg_score dengan tipe pencocokan EXACT, IN_ORDER, atau ANY_ORDER. Setiap invocation bernilai 1.0 jika cocok atau 0.0 jika tidak, dan skor kasus adalah rata-ratanya, dengan threshold default 1.0. Kriteria ini tidak didukung ketika eval memakai user simulation di ADK.

---

- HTML version: https://www.matthewswong.com/id/blog/ai-agent-evals-trajectory-testing/
- English: https://www.matthewswong.com/en/blog/ai-agent-evals-trajectory-testing/
- Site index for agents: https://www.matthewswong.com/llms.txt
- Sitemap: https://www.matthewswong.com/sitemap.xml
- API description (OpenAPI): https://www.matthewswong.com/openapi.json
