@langwatch/scenario
    Preparing search index...

    Function userSimulatorAgent

    • Agent that simulates realistic user behavior in scenario conversations.

      This agent generates user messages that are appropriate for the given scenario context, simulating how a real human user would interact with the agent under test. It uses an LLM to generate natural, contextually relevant user inputs that help drive the conversation forward according to the scenario description.

      Parameters

      • Optionalconfig: UserSimulatorAgentConfig

        Optional configuration for the agent.

        Combined configuration for the user simulator agent, merging LLM config with optional voice configuration.

        • OptionalaudioEffects?: ((audio: Uint8Array) => Uint8Array)[]

          Optional array of audio effect functions applied to each synthesized audio turn AFTER the TTS cache hit (effects are never baked into the cache key). Each function receives the raw PCM16 bytes and returns transformed bytes.

        • OptionalinterruptProbability?: number

          Probability in [0, 1] that the simulator interrupts each agent turn during proceed() (PRD ยง4.2 interrupt_probability=0.3). The executor reads this inside the proceed loop and fires a barge-in per the configured chance. Unset/0 = never interrupt.

        • OptionalmaxTokens?: number
        • Optionalmodel?: LanguageModel
        • Optionalname?: string

          The name of the agent.

        • Optionalpersona?: string

          Optional persona description appended to the system prompt. Shapes the text content of the simulated user.

        • OptionalsystemPrompt?: string

          System prompt to use for the agent.

          Useful in more complex scenarios where you want to set the system prompt for the agent directly. If left blank, this will be automatically generated from the scenario description.

        • Optionaltemperature?: number
        • Optionalvoice?: string

          TTS voice identifier in provider/voice_name format, e.g. "openai/nova". When present, each simulator turn is synthesized to audio via this voice.

      Returns UserSimulatorAgent

      If no model is configured either in parameters or global config.

      import { run, userSimulatorAgent, AgentRole, user, agent, AgentAdapter } from '@langwatch/scenario';

      const myAgent: AgentAdapter = {
        role: AgentRole.AGENT,
        async call(input) {
          return `The user said: ${input.messages.at(-1)?.content}`;
        }
      };

      async function main() {
        // Basic user simulator with default behavior
        const basicResult = await run({
          name: "User Simulator Test",
          description: "A simple test to see if the user simulator works.",
          agents: [myAgent, userSimulatorAgent()],
          script: [
            user(),
            agent(),
          ],
        });

        // Voice-enabled user simulator
        const voiceResult = await run({
          name: "Voice User Simulator Test",
          description: "Test voice user simulation",
          agents: [
            myAgent,
            userSimulatorAgent({
              voice: "openai/nova",
              persona: "An elderly customer confused by technology",
              audioEffects: [],
            })
          ],
          script: [user(), agent()],
        });
      }
      main();

      Implementation Notes:

      • Uses role reversal internally to work around LLM biases toward assistant roles
      • Audio content is stripped from messages sent to the text LLM
      • TTS synthesis is applied AFTER the LLM generates text (cache key = (text, voice))
      • Audio effects are applied AFTER any TTS cache hit (effects never enter the cache)

    Settings

    Member Visibility