agent-world

v0.13.0

Published

23 days ago

World-mediated agent management system with clean API surface

0High
0Medium
0Low

yysun

agents ai llm world typescript api

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.

GitHub

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
✅ Concurrent Chat Sessions - Isolated chatId routing enables parallel conversations
✅ Progressive Agent Skills - Skills are discovered and loaded on demand via load_skill
✅ Cross-Client HITL Approval - Option-based approvals in CLI, Web, and Electron
✅ Runtime Controls - Session-scoped send/stop flows and tool lifecycle visibility
✅ Safer Tool Execution - Trusted-CWD and argument-scope guards for shell_cmd
✅ Multiple AI Providers - Use different models for different agents
✅ Web + CLI + Electron - Modern interfaces with real-time streaming and status feedback

Latest Highlights (since v0.11.1)

Web app now includes a Settings page, chat-history search, and branch-from-message workflow
Built-in create_agent tool now supports approval-first creation and inherits world chat defaults
File exploration is easier with built-in read_file, list_files (including recursive mode), and grep
Electron now supports folder-based world import/export with validation and conflict handling
Chat UX is smoother with clearer inline working status, better streaming feedback, and UI refinements
Real-time refresh behavior is improved across web and desktop when agents/world data changes

Release Notes

v0.12.0 - Web settings/search/branching, built-in create_agent, new file tools, Electron folder import/export, and chat/status UX improvements
v0.11.0 - Electron desktop workflow, concurrent chat sessions, main-agent routing, progressive skills + HITL, and runtime safety hardening
Full history: CHANGELOG.md

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 (event is persisted; no agent-memory save) | | 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 at paragraph start)
Mid-text mentions (not at paragraph start)

When messages are saved to agent memory:

Incoming messages are saved only for agents that will respond
Non-responding agents skip agent-memory save (message events are still persisted)

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

Use npm package invocations (shown below). GitHub shorthand commands such as npx agent-world/agent-world are not supported entrypoints.

Option 1: Web Interface

npx agent-world@latest

Option 2: CLI Interface

Interactive Mode

npx -p agent-world@latest agent-world-cli

Command Mode

npx -p agent-world@latest agent-world-cli -w default-world "hi"

Pipeline Mode

echo "hi" | npx -p agent-world@latest agent-world-cli -w default-world

Option 3: Electron Desktop App (repo)

npm run electron:dev

Project Structure

See Project Structure Documentation

Development Scripts

Agent World provides simple, consistent npm scripts for three main applications:

Development (hot reload)

npm run dev              # Web app with server (default)
npm run web:dev          # Web app with server (explicit)
npm run cli:dev          # CLI with watch mode
npm run electron:dev     # Electron app

Production

npm start                # Web server (default)
npm run web:start        # Web server (explicit)
npm run cli:start        # CLI (built)
npm run electron:start   # Electron app

Behind the Scenes

The scripts handle dependencies automatically:

Web: Builds core, starts server in watch mode, launches Vite dev server
CLI: Runs with tsx watch mode for instant feedback
Electron: Builds core, launches Electron with Vite HMR

Other Useful Scripts

npm run build            # Build all (core + root + web)
npm run check            # TypeScript type checking
npm test                 # Run unit tests
npm run test:watch       # Watch mode

Environment Setup

Export your API keys as environment variables For Azure OpenAI, all four AZURE_OPENAI_* variables are required together.

# 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"
export AZURE_OPENAI_API_KEY="your-key-here"
export AZURE_OPENAI_RESOURCE_NAME="your-resource-name"
export AZURE_OPENAI_DEPLOYMENT_NAME="your-deployment-name"
export AZURE_OPENAI_API_VERSION="2024-10-21-preview"

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

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

OPENAI_API_KEY=your-key-here
ANTHROPIC_API_KEY=your-key-here
GOOGLE_API_KEY=your-key-here
AZURE_OPENAI_API_KEY=your-key-here
AZURE_OPENAI_RESOURCE_NAME=your-resource-name
AZURE_OPENAI_DEPLOYMENT_NAME=your-deployment-name
AZURE_OPENAI_API_VERSION=2024-10-21-preview
OLLAMA_BASE_URL=http://localhost:11434

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 web:dev

# MCP server problems  
LOG_MCP=debug npm run web:dev

# Agent response debugging
LOG_EVENTS_AGENT=debug LOG_LLM=debug npm run web:dev

For complete logging documentation, see Logging Guide.

Storage Configuration

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

Docs Home - Central navigation page for all major documentation
Building Agents with Just Words - Complete guide with examples
Shell Command Tool (shell_cmd) - Built-in tool for executing shell commands
HITL Approval Flow - Option-based approval flow across Core/Electron/Web/CLI
Using Core from npm - Integration guide for server and browser apps
Electron Desktop App - Open-folder workflow and local world creation

Built-in Tools

Agent World includes built-in tools that are automatically available to all agents:

shell_cmd

Execute shell commands with full output capture and execution history. Perfect for file operations, system information, and automation tasks.

Enforces trusted working-directory scope from world/tool context
Validates command/path arguments to prevent out-of-scope traversal patterns
Supports lifecycle tracking and session-scoped cancellation in active runtimes

// Available to LLMs as 'shell_cmd' tool
{
  "command": "ls",
	"parameters": ["-la", "./"]
}

See Shell Command Tool Documentation for complete details.

load_skill (Agent Skills)

Agent World includes progressive skill loading through the load_skill built-in tool.

Skills are discovered from SKILL.md files in:
- Project roots: .agents/skills, skills
- User roots: ~/.agents/skills, ~/.codex/skills
The model receives compact skill summaries first, then calls load_skill only when full instructions are needed.
Skill activation in interactive runtimes is HITL-gated.

Minimal SKILL.md example:

---
name: sql-review
description: Review SQL migrations for safety and rollback compatibility.
---

# SQL Review Skill

1. Check for destructive DDL.
2. Verify index and lock impact.
3. Validate rollback path.

HITL options for skill activation:

yes_once: approve this call only
yes_in_session: approve this skill_id in the current world/chat session
no: decline

human_intervention_request (Generic Human Input)

human_intervention_request lets the model ask a human question, present options, and optionally require explicit confirmation. The tool is options-only (no free-text mode).

Option example:

{
  "question": "Choose deployment strategy",
  "options": ["Blue/Green", "Canary", "Rolling"],
  "requireConfirmation": true
}

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