understudy¶

Simulated user testing for AI agents.

Test your agents with synthetic conversations before they meet real users.

pip install understudy[all]

How It Works¶

Testing with understudy is 4 steps:

Wrap your agent — Adapt your agent (ADK, LangGraph, HTTP) to understudy’s interface
Mock your tools — Register handlers that return test data instead of calling real services
Write scenes — YAML files defining what the simulated user wants and what you expect
Run and assert — Execute simulations, check traces, generate reports

The key insight: assert against the trace, not the prose. Don’t check if the agent said “I’ve processed your return.” Check if it called create_return() with the right arguments and reached the return_created terminal state.

See It In Action¶

Browse real examples from the repo:

Example scene — YAML defining what the simulated user wants
Test file — pytest assertions against traces
Sample report — HTML report from understudy report

What a simulation run looks like:

=== return_eligible_backpack ===
Turns: 6
Tool calls: ['lookup_order', 'get_return_policy', 'create_return']
Terminal state: return_created

  ✓ required_tool: lookup_order called
  ✓ required_tool: create_return called
  ✓ terminal_state: return_created (allowed)

PASSED

Get Started¶

Installation — Install understudy
Quickstart — Write your first scene and run a simulation
ADK Integration Guide — Full guide for Google ADK agents
Examples — Complete working example