Agent World

Build AI agent teams with just words—no coding required.

Why Agent World?

Traditional AI frameworks force you to write hundreds of lines of code just to make agents talk to each other. Agent World lets you create intelligent agent teams using nothing but plain natural language.

https://github.com/user-attachments/assets/cc507c95-01a4-4c27-975a-f8f67d8cf0d7

Audio introduction: Listen here

Other frameworks:

• Install SDKs → write code → handle loops → deploy containers
• Learn Python/TypeScript before "Hello, world"

Agent World:

• Write prompts → for multiple agents → communicating in a shared world

You are @moderator. When someone says "start debate", 
ask for a topic, then tag @pro and @con to argue.

Paste that prompt. Agents come alive instantly.

Why It Works

• ✅ No Code Required - Agents are defined entirely in natural language
• ✅ Natural Communication - Agents understand context and conversations
• ✅ Built-in Rules for Messages - Turn limits to prevent loops
• ✅ Multiple AI Providers - Use different models for different agents
• ✅ Modern Web Interface - React + Next.js frontend with real-time chat

What You Can Build

• Debate Club

@moderator: Manages rounds, keeps time
@pro: Argues for the topic  
@con: Argues against the topic

• Editorial Pipeline

@planner: Assigns articles
@author: Writes drafts
@editor: Reviews and edits
@publisher: Formats and publishes

• Game Master

@gm: Runs the game, manages state
@player1, @player2: Take turns
@assistant: Helps with rules

• Social Simulation

@alice: Friendly neighbor
@bob: Practical problem-solver  
@charlie: Creative dreamer

• Customer Support

@triage: Categorizes requests
@specialist: Handles technical issues
@manager: Escalates complaints

How Agents Communicate

Each Agent World has a collection of agents that can communicate through a shared event system. Agents follow simple rules:

Message Rules

| Message Type | Example | Who Responds | |--------------|---------|--------------| | Human message | Hello everyone! | All active agents | | Direct mention | @alice Can you help? | Only @alice | | Paragraph mention | Please review this:\n@alice | Only @alice | | Mid-text mention | I think @alice should help | Nobody (saved to memory) | | Stop World | <world>pass</world> | No agents |

Agent Behavior

Agents always respond to:

• Human messages (unless mentioned agents exist)
• Direct @mentions at paragraph start
• World messages

Agents never respond to:

• Their own messages
• Other agents (unless @mentioned), but will save message to memory
• Mid-text mentions (will save message to memory)

Turn limits prevent loops:

• Default: 5 responses per conversation thread
• Agents automatically pass control back to humans
• Configurable per world

Installation & Setup

Prerequisites

• Node.js 20+
• An API key for your preferred LLM provider

Quick Start

Option 1: Web Interface

npx agent-world-server

Option 2: CLI Interface

1. Interactive Mode

npx agent-world

2. Command Mode

npx agent-world -w default-world "hi" 

3. Pipeline Mode

echo "hi" | npx agent-world -w default-world

Project Structure

See Project Structure Documentation

Environment Setup

Export your API keys as environment variables

# Required if Choose one or more
export OPENAI_API_KEY="your-key-here"
export ANTHROPIC_API_KEY="your-key-here"  
export GOOGLE_API_KEY="your-key-here"

# Default: For local models
export OLLAMA_BASE_URL="http://localhost:11434"

Or create a .env file in your working directory with:

Testing

Run all tests:

npm test              # Run all unit tests
npm run test:watch    # Watch mode with hot reload
npm run test:ui       # Visual test UI
npm run test:coverage # Generate coverage report

Run specific tests:

npm test -- tests/core/events/  # Test a directory
npm test -- message-saving      # Test files matching pattern

Integration tests:

npm run test:integration  # Run integration tests with real filesystem

Agent World uses Vitest for fast, modern testing with native TypeScript support.

Logging and Debugging

Agent World uses scenario-based logging to help you debug specific issues without noise. Enable only the logs you need for your current task.

Quick Examples

# Database migration issues
LOG_STORAGE_MIGRATION=info npm run server

# MCP server problems  
LOG_MCP=debug npm run server

# Agent response debugging
LOG_EVENTS_AGENT=debug LOG_LLM=debug npm run server

For complete logging documentation, see Logging Guide.

Learn More

World Database Setup

The worlds are stored in the SQLite database under the ~/agent-world directory. You can change the database path by setting the environment variable AGENT_WORLD_SQLITE_DATABASE.

Or, you can change the storage type to file-based by setting the environment variable AGENT_WORLD_STORAGE_TYPE to file. And set the AGENT_WORLD_DATA_PATH to your desired directory.

# Use file storage
export AGENT_WORLD_STORAGE_TYPE=file
export AGENT_WORLD_DATA_PATH=./data/worlds

Learn More

• Building Agents with Just Words - Complete guide with examples

Experimental Features

• MCP Support - Currently in experiment - Model Context Protocol integration for tools like search and code execution. e.g.,

{
	"servers": {
		"playwright": {
			"command": "npx",
			"args": [
				"@playwright/mcp@latest"
			]
		}
	}
}

It supports transport types stdio and http.

Future Plans

• Long Run Worlds - Worlds can run for days or weeks, with agents evolving over time
• Dynamic Worlds - Worlds can provide real-time data to agents, e.g. date and time
• Agent Learning - Agents will evolve based on interactions
• Agent Replication - Agents can create new agents

Contributing

Agent World thrives on community examples and improvements:

1. Share your agent teams - Submit interesting prompt combinations
2. Report bugs - Help us improve the core system
3. Suggest features - What would make agents more useful?
4. Write docs - Help others learn faster

License

MIT License - Build amazing things and share them with the world!

Copyright © 2025 Yiyi Sun