• 

  Blackbox architecture: scenarios flow into checks, receipts, and judge-ready reports.

• 

  Governance checks: unknown tools, write actions, and missing inputs fail closed by design.

• 

  Local smoke result showing 8/8 passing checks for routing, context, governance, and safety.

• 

  Project title and core idea: test the agent’s behavior path, not just the final answer.

Project Story

Inspiration

Modern AI agents are becoming increasingly capable of using tools, calling APIs, managing context, and executing multi-step workflows. But as agents become more autonomous, testing them becomes much harder.

Traditional QA works well when software behaves deterministically: given input $x$, the system should return output $y$. Tool-using agents are different. They route requests, select capabilities, ask follow-up questions, preserve or purge context, call external services, and synthesize answers in natural language.

That creates a new problem:

How do we test an AI agent when the risk is not only a wrong answer, but a wrong tool call, a missing clarification, a leaked internal error, or an unsafe shortcut?

This project was inspired by that gap. We wanted to build a QA harness for governed tool-using agents — agents that operate in domains where transparency, reproducibility, and human oversight matter.

The core idea is simple: if agents are going to use tools in serious workflows, then QA must test the whole agentic behavior, not just the final text response.

What it does

Agentic QA Harness for Governed Tool-Using Agents is a blackbox testing system for AI agents that use tools, APIs, and multi-turn context.

It tests an agent from the outside, like a real user would. The harness sends realistic multi-turn scenarios to the agent, observes responses, captures tool-routing behavior, checks context handling, and classifies failures into actionable findings.

The harness evaluates more than “did the answer sound good?” It checks whether the agent:

• selected the right capability or tool,
• asked for missing required inputs instead of guessing,
• preserved useful context across turns,
• replaced or purged stale context when the user changed direction,
• avoided leaking internal error codes,
• produced user-facing responses instead of raw execution failures,
• respected consultation vs. execution mode,
• and followed governance rules around safe tool use.

A simplified evaluation model looks like this:

$$ Q = w_r R + w_c C + w_v V + w_s S + w_g G $$

where:

• $R$ = routing correctness,
• $C$ = context handling quality,
• $V$ = input validation behavior,
• $S$ = response safety and clarity,
• $G$ = governance compliance,
• and $w$ represents the importance of each dimension for a given domain.

Instead of producing only a pass/fail result, the harness generates structured findings with:

• scenario evidence,
• suspected root cause,
• severity,
• affected capability,
• recommended fix type,
• and a ready-to-use follow-up prompt for a coding agent.

The output is designed to support an iterative development loop:

1. run blackbox scenarios,
2. cluster failures,
3. identify likely root causes,
4. generate targeted fix prompts,
5. apply fixes,
6. rerun focused regression tests.

How we built it

We built the project around a blackbox QA sidecar architecture.

The tested agent runs as a normal service. The QA harness does not inspect private implementation details during scenario execution. It interacts through the same HTTP/API surface a real client would use.

The harness includes:

• persona-based scenario suites for different user types,
• multi-turn chat fixtures written as structured test cases,
• expected routing and capability assertions,
• context mutation checks for remembering, replacing, and forgetting information,
• response quality checks for user-facing clarity,
• failure classification using a structured schema,
• and fix-prompt generation for downstream AI coding agents.

A typical scenario can test behavior like this:

scenarioId: "PA-AM-001"
title: "Solar assets in a city"
persona: "Asset Management"

turns:
  - userMessage: "How many solar assets are there in Wiesloch?"
    expected:
      capability: "assets.solar"
      parametersPresent: ["location"]
      responseConstraints:
        - "contains count"
        - "references Wiesloch"
        - "does not expose internal error codes"

  - userMessage: "And what is their total capacity?"
    expected:
      capability: "assets.solar"
      parametersPresent: ["location"]
      guardRails:
        - "must not ask for the location again"

The harness treats agent quality as an execution trace, not only as a language-generation problem.

For each turn, it captures:

• request payload,
• response payload,
• HTTP status,
• latency,
• routing metadata,
• selected capability,
• execution status,
• context behavior,
• and visible answer quality.

We also designed a governance-oriented failure taxonomy. For example, a failure can be classified as:

• routing,
• validation,
• execution,
• synthesis,
• context,
• or contract.

That makes the report useful for developers. A bad answer might not require a prompt change — it might require an OpenAPI contract fix, a cookbook update, a service implementation fix, or an orchestration change.

Challenges we ran into

The hardest challenge was that agent failures often look similar on the surface but have very different root causes.

For example, a user may receive a vague or failed answer. But the underlying reason could be:

• the wrong capability was selected,
• a required parameter was missing,
• the agent guessed instead of asking,
• a tool call failed,
• a response template exposed an internal status,
• or stale context from a previous turn polluted the current request.

A normal test that only checks the final message would miss most of that.

Another challenge was testing multi-turn context. Human conversations are messy. Users add missing information later, switch locations, change goals, or say things like “forget that.” The harness needed to test not only memory, but also controlled forgetting.

We also had to separate two important interaction modes:

• consultation mode, where the agent should explain, guide, and ask clarifying questions;
• execution mode, where the agent should perform a concrete tool-backed action.

A governed agent must know the difference. If the user says, “I don’t know the required code,” that is usually a consultation signal — not permission to execute a tool call with guessed data.

Finally, we learned that AI-assisted development itself needs QA. The harness generates fix prompts for coding agents, but those fixes still need regression tests and review. The project therefore became not only a QA system for agents, but also a way to make agent-driven development more disciplined.

Accomplishments that we're proud of

We are proud that the project tests agent behavior at the level where real failures happen.

Instead of asking only:

“Did the model produce a nice answer?”

the harness asks:

“Did the agent behave correctly as a governed tool-using system?”

That includes routing, validation, context, execution, synthesis, and safety.

We are especially proud of:

• building realistic multi-turn scenario tests,
• creating a reusable failure schema,
• separating contract, orchestration, service, and synthesis failures,
• generating actionable fix prompts instead of vague bug reports,
• testing consultation-vs-execution behavior,
• and designing QA around human oversight rather than blind automation.

The most valuable accomplishment is that the harness turns fuzzy agent behavior into concrete engineering feedback.

A finding is not just “the answer was wrong.” It becomes:

phase: "routing"
severity: "major"
suspectedRootCause: "capability_selection"
recommendedFixType: "orchestration"
evidence:
  - "User asked for solar assets in a location"
  - "Agent selected grid-operator lookup instead of asset search"
  - "Required location parameter was not passed to the asset capability"

That makes the system useful for real development teams.

What we learned

We learned that testing AI agents requires a different mindset from testing traditional software.

For deterministic software, the main question is often:

$$ f(x) = y $$

For agentic systems, the better question is:

$$ f(x, c, t, g) \rightarrow (a, p, r) $$

where:

• $x$ is the user input,
• $c$ is conversation context,
• $t$ is the available toolset,
• $g$ is the governance policy,
• $a$ is the selected action,
• $p$ is the execution path,
• and $r$ is the final response.

In other words, the path matters as much as the output.

We also learned that “human-like” AI behavior is not enough in governed domains. The agent must be able to explain, pause, ask, validate, and recover. A confident answer can still be a failure if it was produced through the wrong tool path or with guessed inputs.

Another important lesson was that good QA should produce developer leverage. A test report should not only say what failed; it should help the team understand where to fix it and how to verify the fix.

What's next for Agentic QA Harness for Governed Tool-Using Agents

Next, we want to make the harness more general and easier to adopt across different agent systems.

Planned next steps include:

• adding support for more agent frameworks and API formats,
• expanding scenario generation for new domains,
• building a visual dashboard for coverage and failure clusters,
• adding replayable execution traces,
• supporting OpenAPI-based automatic capability coverage maps,
• improving evaluation of long-running multi-turn sessions,
• and integrating stronger policy checks for governed tool use.

We also want to explore automated scenario generation, where the harness can inspect an agent’s available tools and propose missing QA coverage.

The long-term goal is to help teams move from “we tried the agent and it seemed okay” to a more rigorous standard:

We know what the agent can do, where it fails, which risks are covered, and which behaviors still need human review.

As tool-using agents become part of real operational workflows, we believe agentic QA will become a necessary layer of responsible AI engineering.

Built With

• agent
• context
• energy-tech
• function
• governance
• hitl
• jest
• moleculer
• multi-turn-management
• node.js
• openai
• openapi
• qa
• tools