KyroActor Overview

Simulate human conversations with personality-driven AI actors. Automate end-to-end testing of your conversational AI agents.

@kyro/actor is a human conversation simulator. It creates AI-powered actors that roleplay as human users with defined personalities, following scripted scenarios against your live agents.

Use case

Traditional unit tests for AI agents test prompts in isolation. KyroActor tests the full conversation loop: send a message, wait for the agent's response, evaluate criteria, generate a contextually appropriate follow-up, and repeat — until success/failure/max turns.

import { Actor } from '@kyro/actor';
import { WebSocketConnection } from '@kyro/actor';
import { ProviderFactory } from '@kyro/shared';
 
const provider = ProviderFactory.create({ provider: 'openai', model: 'gpt-4o' });
const actor = new Actor('./personality.yaml', provider);
 
const ws = new WebSocketConnection('ws://localhost:3000/chat');
const transcript = await actor.run('./scenario.yaml', ws);
 
console.log(transcript.success); // true/false
console.log(transcript.turns);   // number of conversation turns

How it works

Load a personality YAML (name, role, background, traits, communication style)
Load a scenario YAML (first message, max turns, success/failure criteria, exit conditions)
Connect to your agent via a Connection (WebSocket or LangChain)
Run the conversation loop:
- Send the first message
- Wait for the agent response
- Check success/failure/exit criteria
- Generate the next actor message via the AI provider
- Repeat

Install

npm install @kyro/actor
 
# For WebSocket connections (optional)
npm install ws
npm install --save-dev @types/ws
 
# For LangChain connections (optional peer dep)
npm install @langchain/core

Return value

actor.run() returns a Transcript:

interface Transcript {
  messages: Array<{
    role: 'actor' | 'agent';
    content: string;
    timestamp: Date;
  }>;
  turns: number;
  completed: boolean;
  success: boolean;
  exitReason: 'success' | 'failure' | 'exit_condition' | 'max_turns';
}

KyroActor Overview

Use case

How it works

Install

Return value

On this page