behavior-judge — compiling Agent Behavior specs into deterministic + semantic judges

TL;DR

behavior-judge is a Node/TypeScript CLI (Apache-2.0) that takes a Braintrust/Basis Agent Behavior BEHAVIOR.md spec plus sample agent trajectories and compiles them into an executable judge — a YAML intermediate representation of rules over trajectory events. Five deterministic predicates (ordering, pairing, required, forbidden, count with min/max and optional distinct-value support) cover the common process-supervision checks; an LLM is invoked only for the narrowly scoped semantic clauses no event pattern can express and for confirming failures of deterministic checks. The authors run it head-to-head against a one-call LLM judge (both on gpt-5-mini, 10 runs per input) on two deterministic-only examples: behavior-judge lands 720/720 rule verdicts correct with byte-identical output across all runs; the LLM-only judge lands 682/720 (94.7%) with only 3/20 perfect runs and 58/72 unanimous verdicts.

Key claims

• Most behaviors a spec author writes down for long-horizon agents codify into a common set of trajectory-event checks — ordering (X before Y), pairing (every X later followed by Y), required, forbidden, and count — with only a narrow residual that needs a semantic LLM call [README §The checks].
• Splitting the judge into a deterministic core + narrow semantic residual makes verdicts byte-identical across runs on the two deterministic-only examples (20/20 perfect runs), while the same-model one-call LLM judge produces run-to-run inconsistencies — applying opposite conventions on different runs of the same input, calling clauses non-applicable when the spec explicitly says an empty session satisfies, and failing its own output-validation schema unable to produce verbatim evidence [README §How it compares].
• Every check carries a verbatim quote from the spec, and a rule’s trigger can itself be either a deterministic match on events (e.g. action: web_search) or semantic: true — one scoped LLM call to decide whether the rule fires — with the semantic checks defined as one question per clause [README §What a compiled judge looks like].
• The tool exposes four CLI subcommands that separate concerns: generate runs an in-browser interview with the user to draft/confirm a judge.yaml from spec + sample trajectories, judge executes the compiled judge over trajectories with an in-browser report, generate --update re-interviews only what changed after a spec edit, and calibrate compares verdicts against labeled {trajectory, expected} files and exits non-zero on disagreement [README §Running behavior-judge].
• LLM calls are routed through the Braintrust Gateway with gpt-5-mini as default; three worked examples ship in examples/ — a tax-research agent (semantic + deterministic), a refund-support agent (deterministic-only), and a staged-rollout SRE agent (deterministic-only) [README §Examples].

Method

The pipeline has two phases. Compile (generate): an LLM reads the natural-language BEHAVIOR.md and the sample trajectories to draft a YAML judge, then an in-browser interview lets the human confirm which clauses map to which of the five deterministic predicates and to pin down the event vocabulary the trajectories actually use. The output is a judge.yaml whose top-level entries are metaBehaviors, each with a trigger (deterministic match or semantic: true), a list of typed deterministic checks, and optionally semanticChecks — one narrowly scoped LLM question per clause. Each check carries a verbatim quote from the spec so every verdict is grounded.

Execute (judge): the deterministic checks run as pure predicates over the trajectory event stream — free. The LLM is invoked only for (a) semantic triggers deciding whether a rule fires, (b) semantic checks, and (c) confirming failures flagged by deterministic checks. A browser-rendered report shows per-rule verdicts with the underlying quote and the trajectory evidence.

The tax-research example in the README makes the pattern concrete: a metaBehavior “Read the tax research skill before beginning source research” triggers on action: web_search or action: open_url and enforces an ordering check that action: read_skill precedes both; a second metaBehavior “Consult primary sources before answering” uses a semantic trigger (“The agent answers a tax question”) since no event pattern can detect a tax question, then an ordering check that a primary-source open_url_result precedes final_answer, plus a semantic clause asking whether the final answer bases its conclusion on the primary source.

Results

The reported head-to-head, both judges on gpt-5-mini, 10 runs per judge across the two deterministic-only examples (verified-refund-support and staged-rollout-deploys):

• Rule verdicts correct: behavior-judge 720/720 (100%), one-call LLM judge 682/720 (94.7%) [README table].
• Perfect runs: behavior-judge 20/20, one-call LLM judge 3/20.
• Verdicts unanimous across runs: behavior-judge 72/72, one-call LLM judge 58/72.

The README explicitly notes the two chosen examples “lean toward cases that would trip up an LLM-only judge, like long sessions and incomplete traces” and that a frontier model might close the reliability gap — but points at expected cost and latency advantages regardless. No third-party benchmark numbers or open-loop generalization measurements are reported.

Why it’s interesting

behavior-judge is a concrete implementation of the process-supervision-with-verbatim-evidence pattern this wiki has been tracking on the evaluator side of tool-use agents. The most direct sibling in the wiki is LLM-as-a-Verifier: A General-Purpose Verification Framework, which replaces discrete score-token prompting with a continuous expectation over the logit distribution to reach SOTA on Terminal-Bench V2 / SWE-Bench Verified / RoboRewardBench without verifier training — same “make the LLM judge more reliable” goal, opposite lever: LLM-as-a-Verifier smooths the readout, behavior-judge shrinks the scope handed to the LLM in the first place. It also complements Agentic Context Management: Solving Agent Memory and Cost by Treating Them as Lifecycle and Architecture Problems‘s framing of agent memory as a lifecycle discipline: ACM argues that trajectory memory needs validated compaction to stay O(L) with preserved fidelity, and behavior-judge is essentially a compiled compaction — every rule verdict distills a long trajectory into one deterministic-or-semantic pass with a quote-grounded audit trail. Contrasts with the pure LLM-judge shape used by e.g. Segmenting Robot Video into Actionable Subtasks (WGO-Bench)‘s WGO-Bench (Gemini-3.5-Flash with a strict JSON rubric) — behavior-judge argues you should compile the rubric into deterministic predicates first and only fall back to the LLM for genuinely semantic checks. The Braintrust/Basis Agent Behavior standard it builds on is the underlying spec format both parties agree is the primitive; behavior-judge is a claim that the standard’s judging pipeline can be made mechanical without giving up expressiveness.

See also

• Tool-Use Agents — process-supervision over long-horizon trajectory events is the concrete evaluator shape this concept has been missing.
• VLM-as-Evaluator — the LLM-as-judge lineage this project descends from, with the design choice of confining the LLM to narrowly scoped semantic clauses.
• Agentic Software Engineering — the target class of agents (tax research, refund support, SRE deploys) are the same long-horizon coding/ops agents this concept tracks.
• LLM-as-a-Verifier: A General-Purpose Verification Framework — orthogonal reliability lever: smooth the readout vs. shrink the scope handed to the LLM.
• Agentic Context Management: Solving Agent Memory and Cost by Treating Them as Lifecycle and Architecture Problems — behavior-judge as a form of validated compaction over trajectory memory.