Multi-agent AI simulation runtime engine powered by TypeScript, BullMQ, and OpenAI
autobox-engine-ts is a TypeScript-based simulation runtime that orchestrates multi-agent AI conversations using OpenAI's GPT models. It's designed to simulate complex social interactions, decision-making scenarios, and collaborative problem-solving through autonomous AI agents.
This is a complete rewrite of the Python/Thespian-based engine, migrating from an actor-based architecture to a simpler message queue system using BullMQ and Redis.
- 🤖 Multi-Agent Orchestration - Coordinate multiple AI agents with distinct roles and personalities
- 📨 Message Queue Architecture - BullMQ-powered reliable message passing between agents
- 🎯 Structured Agent Roles - Orchestrator, Planner, Evaluator, Reporter, and Worker agents
- 📊 Real-time Metrics - Track simulation progress and evaluate outcomes
- 🔌 REST API - Control and monitor simulations via HTTP endpoints
- 🐳 Docker Ready - Containerized deployment for isolation and scalability
- ⚡ Hot Reload - Fast development with
tsxwatch mode - 📝 OpenAPI Documentation - Auto-generated Swagger UI for API exploration
┌─────────────────────────────────────────────────────────┐
│ Express API Server (Port 3000) │
│ (Status, Metrics, Instructions, Info) │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ Simulation Runtime │
│ │
│ ┌──────────────┐ ┌─────────────────────────────┐ │
│ │ Orchestrator │───→│ MessageBroker (Redis) │ │
│ └──────────────┘ │ │ │
│ ↓ │ ┌────────────────────────┐ │ │
│ ┌──────────────┐ │ │ Agent Queues (BullMQ)│ │ │
│ │ Planner │←──→│ │ - orchestrator-queue │ │ │
│ └──────────────┘ │ │ - planner-queue │ │ │
│ ↓ │ │ - evaluator-queue │ │ │
│ ┌──────────────┐ │ │ - reporter-queue │ │ │
│ │ Evaluator │←──→│ │ - worker-N-queue │ │ │
│ └──────────────┘ │ └────────────────────────┘ │ │
│ ↓ └─────────────────────────────┘ │
│ ┌──────────────┐ │
│ │ Reporter │ │
│ └──────────────┘ │
│ ↓ │
│ ┌──────────────┐ │
│ │ Worker Agents│ (Custom personas & roles) │
│ └──────────────┘ │
└─────────────────────────────────────────────────────────┘
↓
┌──────────────┐
│ OpenAI API │
│ (GPT Models) │
└──────────────┘
- Orchestrator: Coordinates simulation flow and decides which agent speaks next
- Planner: Creates conversation plan and manages turn order
- Evaluator: Evaluates simulation progress against defined metrics
- Reporter: Generates final simulation summary and insights
- Workers: Custom agents with unique personas (e.g., ANA, JOHN, DETECTIVE)
- Node.js 18+ and Yarn 4.x
- Redis server running locally or remotely
- OpenAI API Key with access to GPT models
- Docker (optional, for containerized deployment)
# Install dependencies
yarn install
# Copy environment template
cp .env.example .env
# Edit .env with your configuration
nano .envSet up your .env file:
# OpenAI API Key (required)
OPENAI_API_KEY=sk-your-api-key-here
# Redis Configuration
REDIS_HOST=localhost
REDIS_PORT=6379
# Server Configuration
PORT=3000
NODE_ENV=development
LOG_LEVEL=info
# JWT Configuration (for API auth)
JWT_SECRET=your-secret-key-here# Start development server with default simulation
yarn dev
# Run specific simulation
yarn dev --simulation-name=summer_vacation
yarn dev --simulation-name=crime_detective
yarn dev --simulation-name=gift_choice
yarn dev --simulation-name=nordic_teamThe API server will be available at http://localhost:3000 with Swagger documentation at http://localhost:3000/docs.
The project includes four example simulations in examples/simulations/:
File: summer_vacation.json
Scenario: A couple (ANA and JOHN) decides on a vacation destination
Agents: 2 workers
Use Case: Decision-making, negotiation, relationship dynamics
File: crime_detective.json
Scenario: Detective solves a murder at a high-society gala
Agents: DETECTIVE, SINGER, DRIVER, BANKER
Use Case: Mystery solving, interrogation, deduction
File: gift_choice.json
Scenario: Selecting the perfect gift
Use Case: Preference elicitation, recommendation
File: nordic_team.json
Scenario: Software development project planning
Agents: Team with Nordic names
Use Case: Project management, team collaboration
# Start with hot reload
yarn dev
# Run with custom config path
yarn dev --config=/path/to/configs --simulation-name=my_simulation# Build TypeScript
yarn build
# Run compiled code
yarn start
# Run in daemon mode (keeps server alive after simulation)
node dist/index.js --daemon --simulation-name=summer_vacation# Run linter
yarn lint
# Auto-fix linting issues
yarn lint:fix
# Format code with Prettier
yarn format
# Run tests (not yet implemented)
yarn test# Build images
yarn docker:build # Production image
yarn docker:build:dev # Development image
# Run containers (requires OPENAI_API_KEY)
export OPENAI_API_KEY=your-key
yarn docker:run # Production container
yarn docker:run:dev # Dev container with hot-reload
yarn docker:run:exit # Run and exit on completion
# Clean up
yarn docker:clean # Remove latest image
yarn docker:clean:all # Remove all images including devFor detailed Docker usage, configuration, and troubleshooting, see DOCKER.md.
GET /health- Health checkGET /ping- Simple ping endpointGET /v1/info- Get agent information (names and IDs)
GET /v1/status- Get current simulation statusGET /v1/metrics- Get simulation metricsPOST /v1/instructions/agents/:agent_id- Send instruction to specific agentPOST /v1/abort- Abort running simulation
GET /- OpenAPI specification (JSON)GET /docs- Interactive Swagger UI
# Check simulation status
curl http://localhost:3000/v1/status
# Get simulation metrics
curl http://localhost:3000/v1/metrics
# Get agent info
curl http://localhost:3000/v1/info
# Send instruction to agent
curl -X POST http://localhost:3000/v1/instructions/agents/{agent_id} \
-H "Content-Type: application/json" \
-d '{"instruction": "Focus on budget-friendly options"}'
# Abort simulation
curl -X POST http://localhost:3000/v1/abortCreate a new file in examples/simulations/my_simulation.json:
{
"name": "My Simulation",
"max_steps": 150,
"timeout_seconds": 600,
"shutdown_grace_period_seconds": 5,
"task": "Your simulation task description",
"description": "Detailed simulation description",
"orchestrator": {
"name": "ORCHESTRATOR",
"mailbox": { "max_size": 400 },
"llm": { "model": "gpt-4o-mini" }
},
"planner": {
"name": "PLANNER",
"mailbox": { "max_size": 400 },
"llm": { "model": "gpt-5-nano" }
},
"evaluator": {
"name": "EVALUATOR",
"mailbox": { "max_size": 400 },
"llm": { "model": "gpt-4o-mini" }
},
"reporter": {
"name": "REPORTER",
"mailbox": { "max_size": 400 },
"llm": { "model": "gpt-5-nano" }
},
"workers": [
{
"name": "AGENT1",
"description": "First agent description",
"context": "Role: ... Backstory: ... Personality: ...",
"mailbox": { "max_size": 100 },
"llm": { "model": "gpt-4o-mini" }
}
]
}Create examples/metrics/my_simulation.json:
[
{
"name": "decision_made",
"description": "Whether agents reached a decision",
"type": "GAUGE",
"unit": "boolean",
"tags": ["outcome"]
}
]yarn dev --simulation-name=my_simulationname: Agent identifier (uppercase recommended)description: Human-readable agent descriptioncontext: Role, backstory, and personality detailsinstruction: Optional specific instructionsmailbox.max_size: Queue capacity (100-400 recommended)llm.model: OpenAI model (e.g.,gpt-4o-mini,o4-mini)
max_steps: Maximum conversation turnstimeout_seconds: Simulation timeoutshutdown_grace_period_seconds: Graceful shutdown wait timetask: High-level simulation goaldescription: Detailed scenario description
autobox-engine-ts/
├── src/
│ ├── api/ # API routes and handlers
│ ├── core/ # Core simulation logic
│ │ ├── agents/ # Agent creation and handlers
│ │ ├── llm/ # LLM integration and prompts
│ │ ├── memory/ # Conversation memory
│ │ └── simulation/ # Simulation orchestration
│ ├── messaging/ # BullMQ message broker
│ ├── schemas/ # Zod validation schemas
│ ├── config/ # Configuration loaders
│ ├── middlewares/ # Express middlewares
│ └── index.ts # Entry point
├── examples/
│ ├── simulations/ # Simulation configs
│ ├── metrics/ # Metrics definitions
│ └── server/ # Server configs
├── dist/ # Compiled JavaScript
└── package.json
- Create handler:
src/core/agents/handlers/createMyAgentHandler.ts - Create factory:
src/core/agents/createMyAgent.ts - Add prompts:
src/core/llm/prompts/myagent/v0.0.1/ - Update
createSimulation()insrc/core/simulation/createSimulation.ts - Add to config schema:
src/schemas/internal/simulationConfig.ts
- Extend
MessageSchemainsrc/schemas/internal/message.ts - Add type guard function (e.g.,
isMyMessageType()) - Update agent handlers to process new type
The engine includes complete Docker support for both development and production environments. Docker provides isolation, reproducibility, and easy deployment.
# Build production image
yarn docker:build
# Set environment variables
export OPENAI_API_KEY=your-key-here
# Run with default simulation
yarn docker:run
# Run specific simulation
./bin/docker-run --simulation-name crime_detective- Multi-stage Production Build: Optimized image size (~200MB)
- Development Image: Hot-reload support with source mounting
- Auto Port Detection: Automatically finds free ports
- Volume Mounting: Persists logs and configuration
- Health Checks: Built-in HTTP health endpoint
- Redis Integration: Configured for BullMQ connectivity
| Command | Description |
|---|---|
yarn docker:build |
Build production image |
yarn docker:build:dev |
Build development image |
yarn docker:run |
Run production container |
yarn docker:run:dev |
Run dev container with hot-reload |
yarn docker:run:exit |
Run and exit on completion |
yarn docker:clean |
Remove latest image |
yarn docker:clean:all |
Remove all images |
If Redis is running in another Docker container:
# Start Redis
docker run -d --name redis -p 6379:6379 redis:alpine
# Run engine (use host.docker.internal on macOS/Windows)
./bin/docker-run --redis-host host.docker.internalFor complete Docker documentation including:
- Detailed script options
- Volume mounting configuration
- Multi-platform builds
- Troubleshooting guide
- Comparison with Python engine
See DOCKER.md
# Check if Redis is running
redis-cli ping
# Should return: PONG
# Start Redis (macOS with Homebrew)
brew services start redis
# Start Redis (Docker)
docker run -d -p 6379:6379 redis:alpine- Verify your API key is set:
echo $OPENAI_API_KEY - Check API key has sufficient credits
- Ensure model names are correct (e.g.,
gpt-4o-mini, notgpt-4o)
- Check logs for errors: simulation logs show in console
- Verify all config files exist in
examples/directories - Ensure Redis is accessible at configured host:port
- Message Throttling: 200ms delay between messages prevents queue flooding
- Queue Sizes: Configure
mailbox.max_sizebased on expected conversation length - Model Selection: Use
gpt-4o-minifor cost-effective performance - Timeout Values: Set
timeout_secondsappropriately for simulation complexity
- Implement comprehensive test suite
- Docker support with production and development images
- Add Docker Compose setup for Redis + Engine orchestration
- Support for multiple concurrent simulations
- Persistent storage for simulation history
- Real-time WebSocket updates
- Advanced metrics visualization
- Plugin system for custom agents
Contributions are welcome! Please follow these guidelines:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
ISC License - see LICENSE file for details
- autobox-api - REST API for simulation management
- autobox-ui - Web interface for monitoring simulations
- autobox-cli - Command-line tool for simulation control
- autobox-mcp - MCP server for Claude integration
For questions and support:
- Open an issue on GitHub
- Check the CLAUDE.md file for detailed development guidance
Built with ❤️ using TypeScript, BullMQ, and OpenAI