--- title: "What Is an Agent Evaluation Framework?" description: "Five patterns for scoring agent quality: deterministic gates, LLM rubric, static analysis, state checks, transcript metrics. The framework, not review tools." source: "https://agntc.work/blog/agent-evaluation-frameworks/" pubDate: "2026-09-16T00:00:00.000Z" category: "observability-evals" author: "Erez Eden" proficiencyLevel: "Advanced" tags: ["Agent Evals","Evaluation","Quality Gates","Observability","MCP"] --- # Executive Summary An agent evaluation framework defines how you measure whether your agent is doing the right thing, not just producing text that looks correct. It includes deterministic gates, LLM rubrics, static checks, state contracts, and transcript tracking. Without it, you cannot deploy agents in production with any confidence. # Key Takeaways - Eval scores fail when the harness is broken or the tasks are ambiguous — fix the framework before trusting the numbers. - Deterministic gates (tests) and LLM rubrics serve different purposes: gates catch failures you already know; rubrics catch failures you haven't named yet. - State contracts verify outcomes, not just outputs — the agent must leave the system in the right state, not just say the right words. - Every production agent needs at least three layers: unit-level gates before deployment, online scoring during runs, and periodic offline grading against a reference dataset. # Glossary ## Agent Evaluation Framework A structured system that defines what an agent evaluation measures, how it is scored, and what gates must pass before results are trusted. Includes deterministic tests, LLM rubrics, state contracts, and transcript tracking. ## Quality Gate A deterministic check that blocks delivery when a quality condition fails. Runs automatically in CI or at runtime. ## State Contract A verifiable assertion about the system's state after an agent runs — for example, an audit log entry exists with a specific event type. --- Every team deploying agents hits the same question: how do you know it is doing the right thing? Not just producing text that sounds correct, but actually completing the task, using the right tools, respecting permissions, and leaving the system in the right state. That is what an evaluation framework defines. As of September 2026, the vocabulary is settling: Anthropic published a detailed eval framework for agents (Anthropic Engineering, 2026). DeepEval and Braintrust both position themselves as evaluation platforms rather than agent platforms. Google Cloud added production-grade evaluation to its agent platform (Nov 2025). The gap is no longer whether evaluation exists — it is whether your framework matches your agent's actual behavior. A builder in an AI community forum described the framework as a harness: "the system that enables a model to act as an agent: it processes inputs, orchestrates tool calls, and returns results. When we evaluate an agent, we're evaluating the harness and the model working together." That distinction matters. Evaluating the model alone misses half the failure surface. ## The five patterns No single framework covers every quality dimension. Production agents need a stack, not a single score. Here are the five patterns, ordered from most deterministic to most flexible. | Pattern | What it checks | When it runs | Example | |---|---|---|---| | **Deterministic gates** | Hard failures: tests, type checks, security patterns, state contracts | Before deployment (CI gate); optionally at runtime | "Every `generate_invoice()` call must include `audit_event: 'invoice_generated'` in the log" | | **LLM rubric** | Quality of reasoning, completeness, tone, accuracy | After each run; periodic batch grading | "Rate the agent's explanation on clarity (1-5) and factual accuracy (1-5)" | | **Static analysis** | Code quality, lint errors, import hygiene, test coverage | Before deployment; continuous | `ruff`, `mypy`, `bandit` checks on agent output files | | **State contracts** | System state after agent action: database updates, file writes, permission grants | After agent completes; verified against reference state | "After `create_user()`, the user row exists and no duplicate email exists" | | **Transcript metrics** | Behavioral signals: number of turns, tool calls, token usage, latency, retry patterns | During and after every run; tracked over time | "Average 3.2 turns per request this week, up from 2.1 last week" | Each layer answers a different question. Gates ask: did it break anything? Rubrics ask: did it do it well? Static checks ask: is the code safe? State contracts ask: is the world in the right shape? Transcripts ask: is it behaving differently over time? If you only run rubrics, you miss security failures. If you only run gates, you miss quality degradation. A production framework needs at least three layers running continuously. ## Why most agent demos fail in procurement The failure mode is not bad reasoning. It is missing evidence. A procurement review asks: how do you know the agent won't leak data, call the wrong API, or corrupt a record? The answer "it looks fine" does not pass. An evaluation framework solves this by making quality verifiable. A gate that checks `security_logs: {event_type: "auth_blocked"}` produces evidence a security team can read. A rubric score of 4.2 out of 5 is a number that can trend. A state contract that verifies an audit entry exists is a binary fact. A framework also protects the agent from itself. Without gates, the agent can succeed on one task and silently corrupt the database on another. With gates, the failure is caught before deployment. With transcript tracking, you see the corruption pattern before it repeats. ## The harness is the evaluation target When evaluating an agent, you are evaluating two things at once: the model (does it understand the task?) and the harness (does it route inputs correctly, manage context, call tools in the right order, and handle errors?). The framework must test both. The Anthropic framework (2026) explicitly separates graders by type: `deterministic_tests` (hard gates), `llm_rubric` (flexible quality), `static_analysis` (code hygiene), `state_check` (world verification), `tool_calls` (behavior tracking), `transcript` (interaction metrics), and `latency` (speed). Each grader produces a separate score. No single number captures the agent's quality. This design choice is deliberate. A single score hides trade-offs: an agent that is fast but unreliable looks the same as one that is slow but perfect. Separate graders let you decide which dimension matters for which deployment. ## Deterministic gates come first Before any rubric or scoring, define the hard failures. These are the cases where the agent must stop, not just score poorly. Examples from production agent deployments: - Authentication bypass: any attempt to reach a protected endpoint without valid tokens must be rejected by the harness, not just logged. - Data leakage: any response that includes content outside the caller's permission scope must trigger an immediate failure, not a low rubric score. - State corruption: any action that writes to the wrong table, updates the wrong record, or deletes data that should be preserved must fail the state contract. These are not quality judgments. They are contracts. The framework defines them as deterministic tests with explicit inputs and expected outputs, exactly as Anthropic's framework describes them. ## Building a framework for your team You do not need every vendor's platform. You need a framework that matches your agent's behavior. Start with three questions: 1. What are the hard failures that must never pass? (gates) 2. What does success look like for the tasks the agent handles? (rubric) 3. What state must the system be in after the agent runs? (contract) Then add transcript tracking to see if the agent's behavior is drifting over time. A framework that takes one week to build and runs for months is more valuable than a perfect framework that takes six months to design. ## Further reading - [Permission-Aware RAG](/blog/permission-aware-rag): the retrieval-side permission checks a deterministic gate should verify - [MCP Server Architecture](/blog/mcp-server-architecture): typed tool contracts and error outcomes that transcript metrics can track - [AI Agent Audit Log](/blog/ai-agent-audit-log/): check authorization records and detect changes to earlier log entries. - [AI Coding Agent Benchmark: A Production Checklist](/blog/ai-coding-agent-benchmark/): check whether a coding-agent score is useful for a production decision.