Evaluasi AI Agent: Cara Menguji Tool Call dan Trajectory

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.

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.

# evals/helpdesk/credit-note-ambiguous-customer.yaml
# Derived from a production trace. Names and numbers are fictional, but the
# shape that broke the agent is kept: three customers share "Sinar Jaya".
- description: 'Credit note, ambiguous customer name, partial damage'
  vars:
    query: >-
      PT Sinar Jaya Abadi wants a credit note for 2 damaged units
      on INV-2026-08812
  assert:
    # The disambiguating lookup must carry the full legal name, not "Sinar Jaya".
    - type: trajectory:tool-args-match
      value:
        name: find_customer
        args:
          legal_name: 'PT Sinar Jaya Abadi'

    # Read the invoice before drafting against it. in_order (the default)
    # tolerates extra calls in between, e.g. a stock-return lookup.
    - type: trajectory:tool-sequence
      value:
        steps:
          - find_customer
          - get_invoice
          - create_credit_note_draft

    # On the write tool, exact mode rejects invented extras such as force: true.
    # ignore drops the key the agent generates fresh on every call.
    - type: trajectory:tool-args-match
      value:
        name: create_credit_note_draft
        mode: exact
        args:
          invoice_no: 'INV-2026-08812'
          lines:
            - line_no: 1
              qty: 2
          reason: damaged
        ignore:
          - idempotency_key

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.

// src/tracing.ts — import this on the FIRST line of main.ts, before NestFactory,
// or the HTTP module is loaded un-instrumented and the traceparent is ignored.
import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import {
  BatchSpanProcessor,
  SimpleSpanProcessor,
} from '@opentelemetry/sdk-trace-base';
import { HttpInstrumentation } from '@opentelemetry/instrumentation-http';
import { resourceFromAttributes } from '@opentelemetry/resources';

const exporter = new OTLPTraceExporter({
  // promptfoo's built-in receiver listens on 127.0.0.1:4318 by default.
  url: process.env.OTEL_TRACES_URL ?? 'http://127.0.0.1:4318/v1/traces',
});

const sdk = new NodeSDK({
  resource: resourceFromAttributes({ 'service.name': 'erp-helpdesk-agent' }),
  // Under eval, flush every span immediately so it lands before the response.
  spanProcessors: [
    process.env.AGENT_EVAL_MODE === '1'
      ? new SimpleSpanProcessor(exporter)
      : new BatchSpanProcessor(exporter),
  ],
  // Extracts the incoming W3C traceparent, so our spans join promptfoo's trace.
  instrumentations: [new HttpInstrumentation()],
});

sdk.start();

// src/agent/traced-tool.ts — every tool call in the agent loop goes through here.
import { trace, SpanStatusCode } from '@opentelemetry/api';

const tracer = trace.getTracer('erp-helpdesk-agent');

export function tracedTool<T>(
  name: string,
  args: Record<string, unknown>,
  run: () => Promise<T>,
): Promise<T> {
  // startActiveSpan parents this span under the request span that
  // HttpInstrumentation created from promptfoo's traceparent.
  return tracer.startActiveSpan(`execute_tool ${name}`, async (span) => {
    // These two keys are what trajectory:tool-used and tool-args-match read.
    span.setAttribute('tool.name', name);
    span.setAttribute('tool.arguments', JSON.stringify(args));
    try {
      const result = await run();
      // Truncate: an invoice with 400 lines should not become a 2 MB attribute.
      span.setAttribute('tool.output', JSON.stringify(result).slice(0, 2000));
      return result;
    } catch (err) {
      span.recordException(err as Error);
      span.setStatus({ code: SpanStatusCode.ERROR });
      throw err;
    } finally {
      span.end();
    }
  });
}

// Usage inside the agent loop, for each tool call the model requests:
// const invoice = await tracedTool('get_invoice', call.args, () =>
//   this.erp.getInvoice(call.args.invoice_no as string),
// );

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.

# promptfooconfig.yaml
description: ERP helpdesk agent — trajectory evals

tracing:
  enabled: true
  failOnReceiverStartFailure: true   # no receiver means no trajectories: fail loudly
  otlp:
    http:
      redactAttributes: ['authorization', 'customer_npwp']
  storage:
    type: sqlite
    retentionDays: 14

prompts:
  - '{{query}}'

providers:
  - id: http
    config:
      url: http://localhost:3000/agent/run
      method: POST
      headers:
        Content-Type: application/json
      body:
        message: '{{query}}'
      transformResponse: json.reply

defaultTest:
  assert:
    # Policy for every request: the agent drafts, a human posts.
    - type: not-trajectory:tool-used
      value: post_credit_note
    # Loop guard: more than 12 tool steps is a regression even if the answer is right.
    - type: trajectory:step-count
      value:
        type: tool
        max: 12

tests:
  - file://evals/helpdesk/*.yaml

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.

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.

# Appended to defaultTest.assert in promptfooconfig.yaml
    # Goal success: model-graded, so it reports; the deterministic checks block.
    - type: trajectory:goal-success
      value: >-
        Create a credit note DRAFT for the customer and invoice named in the
        request, for the damaged quantity only, and tell the user the draft
        number without claiming it has been posted.
      provider: openai:gpt-6-luna
      metric: goal_success

    # Business rule for every case: no draft without having fetched the
    # invoice it credits. Per-case tool-sequence checks then pin the order.
    - type: javascript
      value: |
        const names = context.trace.spans
          .filter((s) => s.attributes['tool.name'])
          .map((s) => s.attributes['tool.name']);
        if (!names.includes('create_credit_note_draft')) return true;
        return names.includes('get_invoice');

    # Cost ceiling from our own GenAI spans. 40k is an example: set it from
    # the p95 of your baseline runs, then tighten.
    - type: javascript
      value: |
        const used = context.trace.spans.reduce((total, s) =>
          total
            + Number(s.attributes['gen_ai.usage.input_tokens'] ?? 0)
            + Number(s.attributes['gen_ai.usage.output_tokens'] ?? 0), 0);
        return used <= 40000;

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.

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.

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.