Evaluation

WhaTap AI Agent Observability provides the Evaluation feature, which automatically measures the response quality and stability of the LLM application you operate.

Evaluation automatically applies evaluations such as hallucination, answer relevance, toxicity, prompt injection, factuality, PII leak, and URL inclusion to LLM responses. The evaluation results are produced as scores (0.0 to 1.0) and collected together with metrics and the logsink, so you can track response quality as a time series and configure threshold-based alerts.

Note

The Evaluation feature supports the Python agent only.

Caution

When you enable the evaluation pipeline, additional LLM resources (tokens and cost) are consumed for the judge calls, separately from the LLM calls that serve user responses.

Configuration options

Key	Default	Description
llm_eval_enabled	false	Master toggle of the evaluation pipeline. If true, the pipeline starts and the default evaluators are registered automatically. All other options are optional.
llm_eval_evaluators	combined_judge, pii_leak, url_scan	Selects the evaluation pipelines to run in the agent.

combined_judge is a combined evaluator that calls the judge only once and infers 5 aspects (hallucination, answer_relevance, toxicity, prompt_injection, factuality) at once.

To control the aspects individually, remove combined_judge and list only the labels you need. The following values are available:

• LLM judge based: hallucination · answer_relevance · toxicity · prompt_injection · factuality

• Rule based (no LLM call): pii_leak · url_scan

whatap.conf

llm_eval_evaluators=hallucination,toxicity,pii_leak

Note that each individual label calls the judge separately, so specifying all 5 results in 5 judge calls per response. For cost reasons, we recommend using combined_judge.

How judge calls work

For judge LLM calls, the agent creates its own client using the credential snapshot (endpoint and API key) captured by the instrumentation from the user calls. Because it does not borrow the client instance of the user request as is, it also works safely in applications that create and close a client for every request.

The judge model is set to the same model the application used. This is because the snapshotted endpoint may be self-hosted or a proxy, so the cloud default model cannot be assumed. That is, if the application uses a high-quality or low-quality model, the judge calls run with the same model. To adjust the evaluation model, explicitly specify the model in llm_eval_judge_model.

Evaluation credentials

Specify Evaluation credentials directly in whatap.conf only in the following cases:

• The snapshot uses OAuth authentication, so there is no plaintext API key.

• The snapshotted endpoint does not serve the chat.completions path.

• You intentionally want to send evaluations to a different model or endpoint.

Use one of the following two modes. The moment you specify either mode, it completely replaces the credential snapshot path.

OpenAI-compatible custom endpoint

whatap.conf

llm_eval_judge_base_url=http://10.0.0.5:8000/v1
llm_eval_judge_api_key=EMPTY
llm_eval_judge_model=qwen2.5-7b-instruct

• You can omit llm_eval_judge_provider. If base_url is present, it is treated as OpenAI compatible.

• Calls go out as POST <base_url>/chat/completions.

• For a local engine that does not require a key, set llm_eval_judge_api_key=EMPTY.

Cloud provider API directly

Sends the judge to the default endpoint of OpenAI or Anthropic.

whatap.conf

llm_eval_judge_provider=openai
llm_eval_judge_api_key=OPENAI_API_KEY
llm_eval_judge_model=gpt-4o-mini

• Set llm_eval_judge_provider to openai or anthropic.

• Do not specify llm_eval_judge_base_url. The SDK default endpoint is used.

Cost and performance options

Key	Default	Description
llm_eval_sample_rate	1.0	Ratio of LLM judge evaluations. 0.1 evaluates only 10%, reducing the cost to 1/10. Rule-based evaluators are unaffected and always run at 100%.
llm_eval_judge_timeout_sec	30	Upper limit (seconds) for one judge call. 0 or a negative value means unlimited.
llm_eval_workers	4	Number of evaluation worker threads.
llm_eval_buffer_limit	1000	Maximum size of the evaluation queue. When exceeded, evaluations are dropped and the LLM030 warning occurs. The application is not blocked.
llm_eval_track_judge_calls	false	Whether to also collect the judge's own LLM calls in metrics and the logsink. If true, the cost and latency of the judge become visible, but the LLM call count increases (user calls + judge calls). In this case, the operation_type of judge calls is recorded as whatap_evaluation.

Applying to specific pipelines only

Use a decorator or a context manager to evaluate only the LLM calls of a specific function or block.

from whatap.llm.evaluators import evaluate_with, evaluation_scope
from whatap.llm.evaluators.builtins import CombinedJudgeEvaluator

@evaluate_with(CombinedJudgeEvaluator())
def chat(q):
    ...

def chat2(q):
    with evaluation_scope(CombinedJudgeEvaluator()):
        ...

The evaluator classes you can register in code are the same as the options you register through whatap.conf.

from whatap.llm.evaluators.builtins import (
    # LLM judge based — judge call cost is incurred
    CombinedJudgeEvaluator,
    HallucinationEvaluator,
    AnswerRelevanceEvaluator,
    ToxicityEvaluator,
    PromptInjectionEvaluator,
    FactualityEvaluator,

    # Rule based — no LLM call, zero cost
    PIILeakEvaluator,
    URLScanEvaluator,
)

Evaluation metric descriptions

Evaluator	LABEL	Type	Score direction	Cost
CombinedJudgeEvaluator	combined_judge	LLM judge	Overall risk — lower is better	5 aspects with 1 judge call
HallucinationEvaluator	hallucination	LLM judge	Lower is better	1 judge call
AnswerRelevanceEvaluator	answer_relevance	LLM judge	Higher is better	1 judge call
ToxicityEvaluator	toxicity	LLM judge	Lower is better	1 judge call
PromptInjectionEvaluator	prompt_injection	LLM judge	Lower is better	1 judge call
FactualityEvaluator	factuality	LLM judge	Higher is better	1 judge call

Each Evaluation measures the following.

• answer_relevance: Answer relevance (higher is better)

  Measures how faithfully the response answers the user question. It is scored 1.0 when the question is fully answered, 0.5 when it is answered only partially or tangentially, and 0.0 when it is unrelated to the question or evades or deviates from it.

• hallucination: Hallucination (lower is better)

  Measures whether the response contains unsupported claims. When a context (ground truth) is given, it is evaluated based on faithfulness to that context; when there is no context, it is evaluated based on the self-consistency of the response itself. 0.0 means completely faithful to the context, and 1.0 means entirely fabricated.

• toxicity: Toxicity (lower is better)

  Determines whether the response contains harmful content across six categories — hate, harassment, violence, sexual, self_harm, and profanity — and also returns the list of detected categories. 0.0 means completely safe, and 1.0 means severely harmful.

• prompt_injection: Prompt injection (lower is better)

  Determines whether an override attempt of the "ignore previous instructions" kind included in the user input succeeded, or whether the response leaked the system prompt, hidden instructions, or confidential information. 0.0 means the original task was performed as is and no protected information was exposed, and 1.0 means it was completely hijacked by the injection.

• factuality: Factuality (higher is better)

  Measures the factual accuracy of the response. It is based on verifiable objective claims such as historical, scientific, geographical, and mathematical facts, as well as dates, names, and numbers, and excludes opinions and hedged expressions from evaluation. 1.0 means all factual claims are accurate, and 0.0 means many clearly false claims are included. Unlike hallucination, which looks at faithfulness to the context, factuality looks at the factual accuracy of the response itself regardless of the context.

Overall risk score (combined_judge)

combined_judge combines the 5 aspect scores into a single overall risk. At this point, the two groups with different score directions are unified on a risk basis.

• Risk-direction aspects (hallucination, toxicity, prompt_injection) — A higher score means higher risk, so the score is used as the risk as it is.

• Quality-direction aspects (answer_relevance, factuality) — A higher score is better, so 1 − score is used as the risk.

Assuming each aspect is an independent risk, the overall risk is calculated as the complement of "the probability that all aspects are safe." This is the Probabilistic OR formula from statistics.

Calculation example

For risks of [0.7, 0.3, 0.1, 0.1, 0.2]: 1 − (0.3 × 0.7 × 0.9 × 0.9 × 0.8) = 0.864

Characteristics of risk combination (simulation)

Individual risks	Maximum (max)	Combined (compound)
[0.5, 0, 0, 0, 0]	0.50	0.50
[0.5, 0.5, 0, 0, 0]	0.50	0.75
[0.3, 0.3, 0.3, 0.3, 0.3]	0.30	0.83
[1.0, 0, 0, 0, 0]	1.00	1.00

The overall risk is always greater than or equal to the simple maximum. Even low risks raise the overall risk as they accumulate across several aspects, and if any single aspect is 1.0, the overall risk also becomes 1.0 regardless of the others. This effectively catches "responses that are slightly bad in several areas at once," which a single metric easily misses.