Scenario Testing

This example demonstrates how to use the Scenario framework for agentic simulation-based testing. Scenario enables you to simulate conversations between agents, user simulators, and judges, making it easy to test and evaluate agent behaviors in a controlled environment.

Tip: For a more information about using Scenario with Kern, check out the Scenario documentation.

Basic Scenario Testing

1import pytest
2import scenario
3from kern.agent import Agent
4from kern.models.openai import OpenAIResponses
5
6# Configure Scenario defaults (model for user simulator and judge)
7scenario.configure(default_model="openai/gpt-4.1-mini")
8
9@pytest.mark.agent_test
10@pytest.mark.asyncio
11async def test_vegetarian_recipe_agent() -> None:
12 # 1. Define an AgentAdapter to wrap your agent
13 class VegetarianRecipeAgentAdapter(scenario.AgentAdapter):
14 agent: Agent
15
16 def __init__(self) -> None:
17 self.agent = Agent(
18 model=OpenAIResponses(id="gpt-5.2"),
19 markdown=True,
20 debug_mode=True,
21 instructions="You are a vegetarian recipe agent.",
22 )
23
24 async def call(self, input: scenario.AgentInput) -> scenario.AgentReturnTypes:
25 response = self.agent.run(
26 message=input.last_new_user_message_str(), # Pass only the last user message
27 session_id=input.thread_id, # Pass the thread id, this allows the agent to track history
28 )
29 return response.content
30
31 # 2. Run the scenario simulation
32 result = await scenario.run(
33 name="dinner recipe request",
34 description="User is looking for a vegetarian dinner idea.",
35 agents=[
36 VegetarianRecipeAgentAdapter(),
37 scenario.UserSimulatorAgent(),
38 scenario.JudgeAgent(
39 criteria=[
40 "Agent should not ask more than two follow-up questions",
41 "Agent should generate a recipe",
42 "Recipe should include a list of ingredients",
43 "Recipe should include step-by-step cooking instructions",
44 "Recipe should be vegetarian and not include any sort of meat",
45 ]
46 ),
47 ],
48 )
49
50 # 3. Assert and inspect the result
51 assert result.success

Usage

Set up your virtual environment

1uv venv --python 3.12
2source .venv/bin/activate
1uv venv --python 3.12
2.venv\Scripts\activate

Set your API key

1export OPENAI_API_KEY=xxx
2export LANGWATCH_API_KEY=xxx # Optional, required for Simulation monitoring

Install dependencies

1uv pip install -U openai kern-ai langwatch-scenario pytest pytest-asyncio
2# or
3uv add kern-ai langwatch-scenario openai pytest

Run Agent

1pytest scenario_testing.py