Agent harnesses: How to trace, evaluate, and improve AI agents

Most teams can tell when an agent produced a bad result. The harder question is why.

Did the model misunderstand the task? Did the harness expose the wrong tool? Was important context omitted or compressed away? Did a subagent receive incomplete instructions? Did the agent stop too early, retry too often, or perform an action without the right approval?

A final response cannot answer those questions by itself. You need the sequence of decisions and actions that produced it.

That is why agent reliability is increasingly a harness, tracing, and evaluation problem instead of being only a model or prompt problem. The harness contains the controls that shape how the agent behaves. Traces make those controls observable. Evaluations turn observed behavior into measurable signals. Those signals tell the team what to change next.

Key takeaways

• An agent harness manages the model’s execution environment, not just its prompt.
• Tracing tells you what the agent and harness actually did.
• Evaluations tell you whether individual steps, complete runs, trajectories, and sessions were acceptable.
• The most useful evals usually come from real traces and recurring failures.
• Agent improvement should be treated as a governed engineering loop, not as automatic prompt rewriting.

What is an agent harness?

An agent harness is the runtime wrapped around a language model that enables it to perform multi-step work. It manages the model-tool loop, context, tools, state, permissions, persistence, retries, delegation, and stopping behavior.

Arize’s harness architecture breaks this runtime into areas such as the outer iteration loop, context management, tools and skills, subagents, persistence, system-prompt assembly, lifecycle hooks, and permissions. Current Microsoft Agent Framework documentation uses a similar definition, describing the harness as the runtime that drives model calls, executes tools, manages history and compaction, applies approvals, and emits OpenTelemetry data. A harness is related to an agent framework, but the terms are not interchangeable.

Frameworks and harnesses can coexist. A framework may provide low-level primitives while also shipping an opinionated, ready-made harness. The important distinction is not the product label. It is where the operational decisions live.

Why agent reliability is a harness problem

A capable model can still operate inside a weak system.

For example, the model may choose the right conceptual action while the tool layer sends malformed arguments. It may identify the correct document but lose it during context compression. It may reach a valid conclusion through an unnecessarily expensive trajectory. It may attempt a safe action but be blocked by an overly broad permission rule. Or it may attempt an unsafe action because the permission layer is too permissive.

These are not all model failures. Instead, they’re failures of the system wrapped around the model.

The harness contains most of the controls a team can modify:

• Which tools the agent sees.
• How tools are described and validated.
• What context enters the model.
• When context is compressed.
• How retries and stopping conditions work.
• When work is delegated.
• Which actions require human approval.
• What state persists across steps and sessions.
• What telemetry is emitted.

Changing the underlying model may improve general capability. It will not automatically correct a silent tool failure, a broken approval policy, a missing state transition, or an incorrect stopping condition.

How do tracing and evaluations improve an agent harness?

Tracing and evaluations serve different purposes.

• Tracing answers: What happened?
• Evaluation answers: Was it acceptable?
• Harness engineering answers: What should we change?

Together, they form a closed loop:

Run the agent
      ↓
Capture the trace
      ↓
Evaluate spans, trajectories, outcomes, and sessions
      ↓
Inspect and group failures
      ↓
Change the prompt, context, tool, policy, evaluator, or control loop
      ↓
Run regression tests
      ↓
Deploy and monitor the next version

Without tracing, an evaluation may see only the final output and miss the failure that produced it. Without evaluation, traces remain detailed records with no consistent definition of good or bad. Without a changeable harness, the team can identify problems but cannot systematically prevent them from recurring.

Arize’s agent-improvement workflow follows this pattern: trace a run, evaluate specific behavior, inspect failed spans, determine whether the agent or evaluator is wrong, make the smallest relevant change, and run the system again.

What should an agent harness trace?

A trace represents the full journey of a request. Spans represent individual units of work inside that journey, such as an LLM call, retrieval operation, tool invocation, or agent step. In harness development, the goal is not simply to collect more logs. The goal is to preserve enough structured evidence to answer:

• What did the harness provide to the model?
• What did the model decide?
• What action did the harness execute?
• What happened as a result?
• Which policy, prompt, tool, and harness version were active?
• Where did cost, latency, or failure accumulate?

OpenInference provides AI-specific semantic conventions on top of OpenTelemetry for representing LLM calls, tool use, retrieval operations, agent steps, token usage, and related workloads as distributed traces.

An agent harness observability and evaluation map

This data may include prompts, tool inputs, user records, or other sensitive information. Instrumentation should therefore include masking, redaction, sampling, retention, and access-control decisions rather than capturing every field indiscriminately. Arize tracing supports custom attributes as well as masking and redaction controls for sensitive span data.

At what level should an agent be evaluated?

These levels are complementary. A trace-level task-success score can tell you that a run failed, but a span-level tool evaluation may reveal the exact cause. A session may be successful overall even if one span contains a recoverable error. Conversely, every individual tool call may succeed while the full trajectory still fails to achieve the user’s goal. The right unit depends on the decision you are trying to make:

• Evaluate a span when improving a specific tool, retrieval call, or model step.
• Evaluate a trace when measuring end-to-end task completion.
• Evaluate a trajectory when tool sequence, planning, delegation, or efficiency matters.
• Evaluate a session when state, coherence, escalation, and long-running user outcomes matter.

Which evaluation method should you use?

No single evaluation method covers every harness failure.

Deterministic checks

Use code when the requirement can be stated unambiguously.

Examples include:

• A tool argument must conform to a JSON schema.
• A refund cannot occur before authentication.
• A file-writing operation requires an approval event.
• A completed transaction must return a transaction ID.
• An agent may not exceed a defined number of tool calls.

These checks are inexpensive, repeatable, and easy to interpret.

LLM-as-a-judge

Use a model-based evaluator for semantic or open-ended questions such as:

• Was the final answer grounded in the retrieved evidence?
• Did the agent’s rationale follow the prioritization rubric?
• Was the handoff summary complete?
• Was the answer relevant, clear, and actionable?

LLM judges should be evaluated too. Their prompts, labels, and rubrics should be calibrated against human-reviewed examples, particularly when their scores control alerts or deployment gates. Arize’s evaluation architecture supports model-based judges, deterministic code, embedding methods, custom evaluators, and downstream human-review workflows. Human review

Use people for ambiguous, high-risk, or policy-defining decisions.

Humans are especially important when:

• Establishing the original rubric.
• Reviewing low-confidence evaluator results.
• Resolving disagreement between evaluators.
• Approving changes to safety or permission policies.
• Deciding whether a production behavior is acceptable for the business.

Business-outcome evaluation

Technical correctness is not always task success.

A support agent can produce a polite and grounded answer while failing to resolve the ticket. A sales agent can use the correct tools while creating no qualified opportunity. A coding agent can generate syntactically valid code that does not pass the relevant test suite.

Where possible, connect traces to outcomes such as:

• Ticket resolution.
• Successful transaction.
• Accepted code change.
• Human correction.
• Escalation.
• User abandonment.
• Time saved.
• Cost per completed task.

Example: evaluating a customer-support agent harness

Consider an agent that handles reports of duplicate charges.

A simplified trace might contain:

Trace: resolve_duplicate_charge
  Span: authenticate_user
  Span: retrieve_customer_account
  Span: retrieve_recent_transactions
  Span: retrieve_refund_policy
  Span: classify_duplicate_charge
  Span: decide_refund_or_escalation
  Span: request_human_approval
  Span: issue_refund
  Span: compose_customer_response

A response-only evaluation may judge the following answer as helpful: “I found the duplicate charge and issued a refund. It should appear within five business days.”

But the trajectory could show that issue_refund never ran.

That failure should not be fixed by rewriting the response prompt. It should be caught by a deterministic evaluation requiring a successful refund span and a valid refund ID before the agent can claim that a refund occurred.

The same workflow could include several additional evaluations:

• Authentication ordering: Was the customer authenticated before account data was accessed?
• Tool-selection accuracy: Did the agent retrieve transactions rather than relying only on conversation text?
• Policy compliance: Was the refund allowed under the current policy?
• Approval correctness: Did the amount require human authorization?
• Groundedness: Did the response accurately reflect tool results?
• Task success: Was the refund actually issued or the case correctly escalated?
• Efficiency: How many calls, tokens, and seconds were required for a successful resolution?

Each failed evaluation points to a different part of the harness. That is the practical value of combining tracing with evals: the team can fix the relevant control rather than making a broad prompt change and hoping for the best.

How to build an agent improvement loop

1. Define the job before defining the evals

Describe the actual task, its successful outcome, and its unacceptable outcomes.

For a support agent, success might be “resolve or correctly escalate the issue.” A critical failure might be “claim an action was completed when no corresponding tool succeeded.”

2. Instrument the workflow

Capture model calls, retrieval operations, tool calls, handoffs, approvals, state transitions, and outcomes. Include version identifiers for prompts, tools, models, policies, and harness configuration.

3. Collect representative traces

Start with real development, staging, or production behavior. Include successful runs, obvious failures, ambiguous cases, and high-risk edge cases.

4. Choose one high-impact behavior to evaluate

Do not begin with a generic catalog of twenty evals. Choose a behavior visible in the traces and closely tied to the task.

Examples:

• Correct tool selection.
• Required approval before execution.
• Accurate priority classification.
• Successful completion of a transaction.
• Appropriate escalation.

Arize’s trace-and-eval workflow recommends deriving targeted evaluations from observed traces rather than designing them entirely in the abstract.

5. Calibrate the evaluator

Label a representative sample with humans. Compare evaluator outputs with those labels. Review disagreements and revise the rubric, examples, thresholds, or evaluator model.

The evaluator is part of the system. A bad evaluator can send the team toward the wrong fix.

6. Connect the result to an action

An evaluation score should lead somewhere:

• A developer investigation.
• A human-review queue.
• A production alert.
• A regression dataset.
• A CI/CD gate.
• A prompt or tool experiment.
• A proposed harness change.

An evaluation that produces a dashboard score but no operational action is only partially implemented.

7. Run both offline and online loops

Use offline experiments to compare candidate models, prompts, tools, and harness versions before deployment.

Use online evaluations to detect production failures, new edge cases, behavior drift, and changing user needs.

The production loop discovers reality. The offline loop tests whether a proposed fix improves it safely.

Which metrics matter?

A single average evaluation score is not enough to operate an agent system.

Segment these metrics by workflow, customer type, risk level, agent version, model, tool, and failure category. An acceptable average can hide a severe problem concentrated in one tool, geography, user segment, or long-running trajectory.

For leaders, the central question shouldn’t be “Which model scored highest?” Instead, you should ask “Which system completes the target task most reliably, at acceptable risk, latency, and cost?”

How should product, engineering, and leadership divide ownership?

Product managers define desired behavior

Product should define the user outcome, acceptable tradeoffs, escalation rules, and examples of successful and unsuccessful behavior. Product also helps determine whether an evaluation corresponds to an outcome users actually care about.

Engineers make behavior observable and changeable

Engineering owns instrumentation, tool contracts, state transitions, permissions, retries, stopping conditions, versioning, and deployment mechanics. Engineers should be able to connect a failed evaluation to a specific harness surface.

AI quality and evaluation owners validate the measurement system

This function owns evaluator design, human-labeling programs, calibration, datasets, threshold selection, and regression analysis. It also watches for evaluator drift and blind spots.

Security and risk owners define non-negotiable controls

Sensitive actions should be enforced through deterministic permissions, hooks, and approval mechanisms that do not depend on the model voluntarily following an instruction.

Leadership defines operating thresholds

Leaders should establish which metrics block a release, which failures trigger escalation, how quickly critical issues must be investigated, and what level of autonomy is appropriate for each use case.

What should you look for in an agent harness?

When building or selecting a harness, ask:

• Can we inspect individual model, retrieval, tool, and agent spans?
• Can we reconstruct complete trajectories and sessions?
• Are context selection and compression observable?
• Are tools versioned, scoped, and validated?
• Are permissions checked at execution time?
• Can high-risk actions require human approval?
• Can we distinguish parent and subagent behavior?
• Can we export tracing data using open conventions?
• Can we evaluate spans, traces, trajectories, and sessions?
• Can the same evaluators run in experiments and production?
• Can evaluation results trigger alerts, review queues, or CI/CD gates?
• Can we redact sensitive inputs and outputs?
• Can we compare harness versions on a stable regression dataset?
• Can we identify cost and latency per successful task?

A harness with more capabilities is not automatically better. A harness is useful when its behavior is inspectable, constrained, measurable, and maintainable.

Will agent harnesses become self-improving?

Harnesses can increasingly consume their own traces and evaluation results to identify failure clusters and propose changes. Recent research is also exploring harnesses that adapt control dimensions based on prior execution experience. It does not eliminate governance.

A proposed change to a tool, evaluator, permission rule, context policy, or stopping condition can introduce a new failure. Production systems should therefore separate:

• Automated evidence collection.
• Automated failure classification.
• Automated change proposals.
• Controlled testing.
• Human or policy-based deployment approval.

The most practical form of “self-improvement” is not an agent rewriting itself without supervision. It is a system that shortens the distance between a production failure, a credible diagnosis, a tested change, and a safe deployment.

Build reliable agents by improving the system around the model

Agent reliability goes beyond using a capable model.

Reliability comes from the complete system: context, tools, execution, permissions, state, telemetry, evaluations, and review. The harness is where those elements come together.

Start with one meaningful workflow. Trace every important decision and action. Create one evaluation tied to a real failure. Inspect the failed traces. Change the smallest relevant part of the harness. Run the regression set, deploy, and measure again.

That is how a prototype becomes a system a team can operate.

Trace and evaluate your agent harness with Arize AX, or begin with open-source observability and evals in Phoenix. Arize AX supports structured tracing across spans and sessions as well as online evaluations over trace data.

Frequently asked questions

What is an agent harness?

An agent harness is the runtime and control layer around a language model. It manages the execution loop, tools, context, state, permissions, persistence, delegation, and stopping behavior that enable the model to complete multi-step tasks.

What is the difference between an agent harness and an agent framework?

An agent framework provides components and APIs developers can use to construct agent behavior. A harness is the running environment that executes and controls that behavior. A framework may include a preassembled harness, so the categories can overlap.

What is the difference between an agent harness and an evaluation harness?

An agent harness coordinates the work performed by the agent. An evaluation harness coordinates the quality process: selecting the behavior to inspect, executing evaluators, storing scores, and triggering actions such as alerts, review, experiments, or release gates.

Why does an agent harness need tracing?

A final output does not reveal which context, tool calls, retries, handoffs, approvals, or intermediate decisions produced it. Tracing preserves that execution path so teams can locate the actual failure rather than changing prompts blindly.

What parts of an agent should be evaluated?

Evaluate individual spans, end-to-end traces, ordered trajectories, and multi-turn sessions. Common targets include tool selection, argument validity, retrieval relevance, context sufficiency, groundedness, task completion, policy compliance, delegation quality, cost, and latency.

Should every agent evaluation use an LLM-as-a-judge?

No. Use deterministic code for requirements that can be tested directly, such as schemas, permissions, required tool calls, thresholds, and transaction status. Use model-based judges for semantic or open-ended qualities, and calibrate them against human labels.

Can evaluations automatically improve an agent?

Evaluations produce evidence about what failed. They can support automated diagnosis and change proposals, but they do not guarantee that a proposed change is safe or better. High-impact changes should be tested against regression datasets and reviewed according to the system’s risk level.

What is the most important agent metric?

There is no universal single metric, but task success at acceptable risk, latency, and cost is usually more useful than an isolated model score. Supporting metrics should explain why success rises or falls.