Configuration for the scenario test.
Configuration for a scenario.
The agents participating in the scenario.
A description of what the scenario tests.
Optionalid?: stringOptional unique identifier for the scenario. If not provided, a UUID will be generated.
OptionalmaxTurns?: numberThe maximum number of turns to execute.
If no value is provided, this defaults to DEFAULT_MAX_TURNS.
Optionalmetadata?: Record<string, unknown>Optional metadata to attach to the scenario run.
Accepts arbitrary key-value pairs (e.g. prompt IDs, environments, versions).
The langwatch key is reserved for platform-internal use.
The name of the scenario.
OptionalonAudioChunk?: (chunk: AudioChunk) => voidOptional callback invoked for every audio chunk that flows through a voice adapter (both user-side and agent-side).
Mirrors Python scenario.run(on_audio_chunk=...). Best-effort — if
the hook throws, the scenario continues uninterrupted.
OptionalonVoiceEvent?: (event: VoiceEvent) => voidOptional callback invoked for every VoiceEvent appended to
the timeline (user_start_speaking, agent_stop_speaking, etc.).
Mirrors Python scenario.run(on_voice_event=...). Best-effort — if
the hook throws, the scenario continues uninterrupted.
Optionalscript?: ScriptStep[]The script of steps to execute for the scenario.
OptionalsetId?: stringOptional identifier to group this scenario into a set ("Simulation Set"). This is useful for organizing related scenarios in the UI and for reporting. If not provided, the scenario will not be grouped into a set.
OptionalthreadId?: stringOptional thread ID to use for the conversation. If not provided, a new thread will be created.
Optionalverbose?: booleanWhether to output verbose logging.
If no value is provided, this defaults to DEFAULT_VERBOSE.
Optionalvoice?: VoiceConfigPer-run voice configuration (ADR-002). This is the carrier that reaches
every call() via AgentInput.scenarioConfig — the STT/TTS
providers the judge's transcription pass and the user-simulator's TTS
pass read live here, NOT in a module global. An optional
RunOptions.voice override seeds this at the run() boundary
(options?.voice ?? cfg.voice ?? default); the resolved provider is
always read off cfg.voice. See voice/config.ts#resolveVoiceConfig.
Optionaloptions: RunOptionsA promise that resolves with the ScenarioResult containing the test outcome, conversation history, success/failure status, and detailed reasoning.
import { run, AgentAdapter, AgentRole, user, agent } from '@langwatch/scenario';
const myAgent: AgentAdapter = {
role: AgentRole.AGENT,
async call(input) {
return `The user said: ${input.messages.at(-1)?.content}`;
}
};
async function main() {
const result = await run({
name: "Customer Service Test",
description: "A simple test to see if the agent responds.",
agents: [myAgent],
script: [
user("Hello, world!"),
agent(),
],
});
if (result.success) {
console.log("Scenario passed!");
} else {
console.error(`Scenario failed: ${result.reasoning}`);
}
}
main();
High-level interface for running a scenario test.
This is the main entry point for executing scenario tests. It creates a ScenarioExecution instance and runs it.