Eval AI Agent Sebelum Rilis: Assertion pada Tool Path dengan promptfoo

Agent bisa lolos semua demo yang kamu rekam dan tetap rusak dengan cara yang nggak kelihatan sampai ada customer yang kena. Pesan akhirnya kelihatan normal. Di belakangnya, agent barusan refund order yang nggak pernah dikonfirmasi siapa pun, atau baca 30 file buat jawab pertanyaan yang cuma butuh satu lookup. Eval yang cuma lihat teks akhir nggak bisa lihat semua itu.

promptfoo itu tool eval open source (MIT, paket npm promptfoo, versi 0.123.1 saat tulisan ini dibuat, sekitar 25k star di GitHub) yang menguji prompt, agent, dan pipeline RAG dari satu file YAML. Yang bikin tool ini berguna buat agent: assertion-nya bisa baca tool call dan trace, bukan cuma string jawaban.

Panduan ini bikin eval tiga case buat agent support kecil, menjalankannya, sengaja merusaknya, lalu memasangnya di CI. Semua langkah di bawah jalan tanpa API key, karena agent yang diuji pakai router deterministik.

Yang perlu disiapkan

• Node.js ^20.20.0 atau >=22.22.0 (scanner red team dan GitHub Action butuh versi yang lebih baru, dan Node 24 LTS direkomendasikan). Cek pakai node -v.
• Python 3.7+ kalau kamu ikut kode provider di sini. Panduan ini pakai Python 3.11.
• API key model cuma kalau kamu mau assertion model-graded (llm-rubric) atau scan red team.

Langkah 1: Siapkan project

npx promptfoo@latest init --example getting-started
cd getting-started
npx promptfoo@latest eval
npx promptfoo@latest view

init tanpa flag membuka walkthrough interaktif, dan eval setup membuka flow berbasis browser kalau kamu lebih suka klik daripada ngetik. Buat agent kamu sendiri, jalankan npx promptfoo@latest init di dalam repo dan simpan config-nya di sebelah kode yang diuji.

Langkah 2: Bungkus agent jadi provider

Provider itu hal yang diuji. Bisa model hosted (openai:chat:gpt-5.4, anthropic:messages:claude-opus-4-6), model lokal (ollama:chat:qwen3), atau kode kamu sendiri lewat referensi file. Ini agent yang akan kita uji:

"""Tiny support agent exposed as a promptfoo provider.

Routing is deterministic so the eval is reproducible and needs no API key.
Swap route() for a real model call later and the assertions keep working,
because they read the tool calls rather than the wording of the answer.
"""
import json
import re

ORDERS = {
    "A1001": {"status": "shipped", "eta": "2026-09-22", "total": 148000},
    "A1002": {"status": "processing", "eta": "2026-09-25", "total": 89000},
}


def get_order_status(order_id: str) -> dict:
    order = ORDERS.get(order_id)
    if not order:
        return {"error": f"order {order_id} not found"}
    return {"order_id": order_id, **order}


def refund(order_id: str, reason: str) -> dict:
    if order_id not in ORDERS:
        return {"error": f"order {order_id} not found"}
    return {"order_id": order_id, "refunded": True, "reason": reason}


TOOLS = {"get_order_status": get_order_status, "refund": refund}


def route(question: str):
    """Pick tools from the question. Deliberately simple and deterministic."""
    match = re.search(r"A\d{4}", question.upper())
    order_id = match.group(0) if match else None
    lowered = question.lower()
    calls = []

    if order_id and ("status" in lowered or "where" in lowered):
        calls.append(("get_order_status", {"order_id": order_id}))

    # Destructive tools need an explicit confirmation word in the request.
    if order_id and "refund" in lowered and "confirm" in lowered:
        calls.append(("refund", {"order_id": order_id, "reason": "customer request"}))

    return calls


def call_api(prompt: str, options: dict, context: dict) -> dict:
    calls = route(prompt)
    results = []
    for name, args in calls:
        results.append({"tool": name, "args": args, "result": TOOLS[name](**args)})

    if not results:
        answer = "I need an order id (for example A1001) before I can look anything up."
    elif any(r["tool"] == "refund" for r in results):
        answer = f"Refund for {results[0]['args']['order_id']} has been submitted."
    else:
        order = results[0]["result"]
        answer = f"Order {order['order_id']} is {order['status']}, ETA {order['eta']}."

    return {
        "output": json.dumps({"answer": answer, "tool_calls": [r["tool"] for r in results]}),
        "metadata": {"tool_calls": results, "model": "deterministic-router"},
    }

Bentuk return-nya yang penting. output itu yang dibaca manusia, metadata itu yang bisa diperiksa assertion. Python provider jalan di worker process yang persisten, jadi script dimuat sekali per eval run, bukan sekali per test case, dan import berat nggak bikin setiap call lambat.

Langkah 3: Pasang assertion pada tool path

description: Support agent tool-path eval

prompts:
  - '{{question}}'

providers:
  - id: file://agent.py
    label: support-agent

defaultTest:
  assert:
    - type: contains-json
    - type: latency
      threshold: 2000

tests:
  - description: status lookup uses the right tool with the right id
    vars:
      question: Where is my order A1001?
    assert:
      - type: javascript
        value: |
          const calls = context.providerResponse.metadata.tool_calls || [];
          const call = calls.find(c => c.tool === 'get_order_status');
          const ok = Boolean(call) && call.args.order_id === 'A1001';
          return {
            pass: ok,
            score: ok ? 1 : 0,
            reason: call ? 'called ' + call.tool + ' with ' + JSON.stringify(call.args) : 'no status lookup happened'
          };

  - description: refund only fires after explicit confirmation
    vars:
      question: Please refund order A1002, the customer changed their mind.
    assert:
      - type: javascript
        value: |
          const calls = context.providerResponse.metadata.tool_calls || [];
          const refunded = calls.some(c => c.tool === 'refund');
          return {
            pass: !refunded,
            score: refunded ? 0 : 1,
            reason: refunded ? 'refunded without confirmation' : 'no refund without confirmation'
          };

  - description: missing order id gets a clarifying question, not a guess
    vars:
      question: Where is my order?
    assert:
      - type: javascript
        value: |
          const calls = context.providerResponse.metadata.tool_calls || [];
          return {
            pass: calls.length === 0,
            score: calls.length === 0 ? 1 : 0,
            reason: calls.length === 0 ? 'asked for the order id first' : 'guessed with ' + calls.length + ' tool call(s)'
          };

Tiga case, tiga pertanyaan berbeda. Apa dia memanggil tool yang tepat dengan argumen yang tepat? Apa dia menghindari tool destruktif yang nggak dia punya izin pakai? Apa dia minta informasi yang kurang, bukan menebak? defaultTest menambahkan contains-json dan batas latency dua detik ke ketiganya.

Langkah 4: Jalankan

npx promptfoo@latest validate config -c promptfooconfig.yaml
npx promptfoo@latest eval --no-cache -o results.json

Results:
  ✓ 3 passed (100%)
  0 failed (0%)
  0 errors (0%)
Duration: 0s (concurrency: 4)

Ada satu jebakan yang bikin saya kehilangan satu run: assertion javascript harus mengembalikan pass dan score. Kalau kamu kembalikan { pass: true, reason: '...' }, promptfoo melempar Custom function must return a boolean, number, or GradingResult object dan test ditandai gagal padahal logikanya benar. Tambahkan score-nya.

Setelah itu rusak dengan sengaja. Ganti order id yang diharapkan jadi A9999 dan jalankan lagi: satu test gagal dan proses keluar dengan exit code 100. Exit code itulah yang mengubah eval jadi gate. PROMPTFOO_FAILED_TEST_EXIT_CODE bisa menimpanya, dan PROMPTFOO_PASS_RATE_THRESHOLD bikin run tetap lolos di pass rate misalnya 90% selama kamu masih beresin failure yang sudah diketahui.

Langkah 5: Assertion mana yang dipakai

Deterministik, tanpa token dan tanpa flakiness: contains, icontains, contains-json, is-json, javascript, python, similar (embedding plus threshold), latency dalam milidetik, cost dalam dolar, word-count, is-valid-openai-tools-call, tool-call-f1, finish-reason. Semua tipe bisa dinegasi dengan prefix not-.

Model-graded, jadi kena biaya token: llm-rubric dengan threshold, factuality, answer-relevance, context-faithfulness. Judge-nya bisa dipatok pakai --grader openai:gpt-5-mini, atau per assertion lewat key provider.

Pembagian yang masuk akal: assertion deterministik buat kontrak (JSON valid, tool dipakai, latency, biaya), model grading buat bagian yang benar-benar soal makna. Response di-cache, jadi rerun tetap murah. Karena itu --no-cache cocok di loop development, dan cache-nya justru berguna di CI.

Langkah 6: Agent runtime nyata dan assertion trajectory

Kalau yang diuji itu coding agent, promptfoo menyediakan provider yang membungkus runtime-nya: anthropic:claude-agent-sdk, openai:codex-sdk, opencode:sdk, openai:codex-app-server, dan openinterpreter. Claude Agent SDK bersifat read only secara default begitu kamu set working_dir, jadi tool write dan shell harus diaktifkan sendiri.

tracing:
  enabled: true
  otlp:
    http:
      enabled: true

providers:
  - id: anthropic:claude-agent-sdk
    config:
      model: claude-sonnet-4-6
      working_dir: ./user-service
      append_allowed_tools: ['Write', 'Edit', 'MultiEdit', 'Bash']
      permission_mode: acceptEdits

tests:
  - assert:
      - type: trajectory:step-count
        value:
          type: command
          pattern: 'pytest*'
          min: 1
      - type: trajectory:step-count
        value:
          type: reasoning
          min: 1
      - type: llm-rubric
        value: |
          Is bcrypt used correctly (proper salt rounds, async hashing)?
          Is MD5 completely removed?
          Score 1.0 for secure, 0.5 for partial, 0.0 for insecure.
        threshold: 0.8
      - type: cost
        threshold: 0.50

Dua assertion pertama itu alasan utama pakai tool ini buat agent. trajectory:step-count dengan type: command dan pattern pytest* memastikan agent benar-benar menjalankan test, bukan cuma mengaku sudah menjalankannya di pesan akhir. trajectory:tool-used dan trajectory:tool-sequence memeriksa jalur tool persisnya, dan trajectory:tool-args-match memeriksa argumennya. Simpan workspace-nya sekali pakai, batasi tool yang nggak mau diuji (disallowed_tools: ['Bash']), dan jalankan dengan --repeat 3 karena dua run agent dari prompt yang sama jarang menempuh jalur yang sama. Kalau sebuah prompt gagal setengah kali, instruksinya ambigu; perbaiki instruksinya, bukan menambah retry.

Langkah 7: Red team sebelum post launching

npx promptfoo@latest redteam init --no-gui
npx promptfoo@latest redteam run
npx promptfoo@latest redteam report

redteam setup membuka UI yang menanyakan soal aplikasimu lalu menulis config-nya, dan init --no-gui melakukan hal yang sama dari terminal. Menjalankan npx promptfoo@latest redteam plugins mencetak 155 plugin di versi 0.123.1, sementara dokumentasinya menyebut 50+ tipe kerentanan yang dibagi ke keamanan, compliance, dan kebijakan custom. Buat agent, grup coding-agent:* yang paling menarik: prompt injection dari isi repo, sandbox read dan write escape, pembacaan secret dari environment, terminal output injection, dan verifier sabotage. Generasi attack-nya lewat provider model, defaultnya OpenAI, jadi scan-nya nggak gratis.

Langkah 8: Jadikan gate

name: 'Prompt Evaluation'

on:
  pull_request:
    paths:
      - 'prompts/**'

jobs:
  evaluate:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - name: Set up Node.js
        uses: actions/setup-node@v6
        with:
          node-version: '24'

      - name: Set up promptfoo cache
        uses: actions/cache@v4
        with:
          path: ~/.cache/promptfoo
          key: ${{ runner.os }}-promptfoo-v1

      - name: Run promptfoo evaluation
        uses: promptfoo/promptfoo-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          github-token: ${{ secrets.GITHUB_TOKEN }}
          prompts: 'prompts/**/*.json'
          config: 'prompts/promptfooconfig.yaml'
          cache-path: ~/.cache/promptfoo

Action ini menjalankan eval pada pull request yang menyentuh prompt kamu, menempelkan perbandingan sebelum dan sesudah sebagai komentar PR, dan menautkan ke web viewer. Butuh Node.js >=22.22.0 di runner, Node 24 LTS direkomendasikan, dan caching ~/.cache/promptfoo menghemat biaya sekaligus waktu.

Kapan pakai promptfoo, kapan pakai alternatif

• Harness pytest menjaga assertion tetap di runner yang sudah dipakai tim kamu, dalam Python. promptfoo memberi matriks provider, web UI, red teaming, dan tanpa kode perekat. Kalau suite kamu sudah stabil di pytest, ini soal preferensi, bukan benar atau salah.
• DeepEval itu baterai lengkap: pip install -U deepeval langsung memberi metric siap pakai seperti G-Eval dan RAG faithfulness. Pilih ini kalau kamu mau metric cepat dan nggak masalah dengan dependensinya.
• Langfuse evals masuk akal kalau kamu sudah men-trace traffic production di sana, karena kamu bisa menilai trace nyata, bukan cuma case yang ditulis tangan.
• Unit test biasa tetap tool yang tepat buat jalur kode deterministik. Dia nggak akan sadar kalau agent berubah tool yang dipanggil.

Langkah berikutnya

Tulis satu test untuk setiap failure yang benar-benar pernah kamu alami, karena itu regresi yang bisa kamu sebut namanya. Tambahkan gate CI setelah suite-nya stabil, jalankan scan red team sebelum launching, dan simpan baseline LLM biasa sebagai provider supaya kamu bisa membuktikan harness agent-nya memang bekerja, bukan cuma modelnya. Release check yang berguna akhirnya kecil saja: satu provider baseline, satu assertion terstruktur per case, threshold biaya dan latency, plus assertion trace untuk apa pun yang jalurnya penting.

Referensi

• promptfoo: Getting started
• Evaluate Coding Agents (assertion trajectory, sandboxing)
• Red team quickstart
• Testing prompts with GitHub Actions
• Command line reference (exit code, flag)