agent-world

v0.15.0

Published

2 months 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
✅ World-Level Tool Permissions - Read, Ask, and Auto modes control write and execution capabilities
✅ Cross-Client HITL Approval - Option-based approvals in CLI, Web, and Electron
✅ Reasoning Controls - World-scoped reasoning effort with separate reasoning-token rendering
✅ Heartbeats & Queueing - Queue-backed world prompts and cron scheduling with explicit controls
✅ Marketplace & Imports - Bring in worlds, agents, and skills from local folders or curated GitHub sources
✅ 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 (v0.15.0)

World-level tool permissions add Read, Ask, and Auto control modes in both the web and Electron composers
Supported providers can use world-scoped reasoning_effort, with reasoning tokens streamed and rendered separately from final answers
World and heartbeat prompts now enter the same queue-backed message flow as human turns, with explicit heartbeat controls and next-run visibility
Electron now includes marketplace-style import flows for discovering and importing worlds, agents, and skills
Web and Electron transcripts have tighter parity with compact tool rows, improved status rendering, and cleaner working indicators
Clicking markdown links in Electron messages now opens the external browser instead of attempting in-app navigation

Release Notes

v0.15.0 - Tool permission modes, reasoning-token support, queue-backed world/heartbeat flow, marketplace imports, and transcript/UI refinements
v0.14.0 - User message queue, write_file/web_fetch/send_message, shell risk gating, E2E harnesses, skill editor, and heartbeat scheduling
v0.13.0 - Better HITL prompts, improved streaming/main-agent UX, and smoother message rendering
v0.12.0 - Web settings/search/branching, built-in create_agent, new file tools, Electron folder import/export, and chat/status UX improvements
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 Shape | Example | Who Responds | |--------------|---------|--------------| | Public human or world message | Hello everyone! | All active agents | | Paragraph-start mention | @alice Can you help? | Only mentioned agents | | Paragraph-start mention after text | Please review this:\n@alice | Only mentioned agents | | Mid-text mention only | 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:

Public human or world messages when there is no paragraph-start mention
Direct @mentions at paragraph start

Agents never respond to:

Their own messages
Other agents (unless @mentioned at paragraph start)
Mid-text mentions (not at paragraph start), including world prompts

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

core/ - shared runtime, storage, tools, provider integrations, and event flow
server/ - REST API and SSE transport
web/ - browser app
electron/ - desktop app (main, preload, renderer)
cli/ - terminal interface

For broader architecture and usage docs, start with Docs Home.

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

Optional Opik Layer

Opik is optional and fully gated.

OPIK_ENABLED=false
OPIK_SAFETY_ENABLED=false
OPIK_EVAL_ENABLED=false
OPIK_API_KEY=
OPIK_WORKSPACE=
OPIK_PROJECT=agent-world-debugging

Rules:

OPIK_ENABLED=false: all Opik integration/safety/eval paths are inert.
OPIK_ENABLED=true: tracing can attach only if OPIK_API_KEY + OPIK_WORKSPACE are set.
Safety and eval still require their sub-flags (OPIK_SAFETY_ENABLED, OPIK_EVAL_ENABLED).

Fallback Behavior

When Opik is enabled but something is missing, startup always continues normally — no crashes.

| Condition | Result | Log | |-----------|--------|-----| | OPIK_ENABLED=false | No Opik code runs | none | | Enabled but OPIK_API_KEY or OPIK_WORKSPACE missing | Tracer skipped | warning: Opik enabled but required env is missing | | Enabled + config present but packages/opik not installed | Tracer skipped | warning: Opik enabled but optional dependency is unavailable | | Enabled + config present + module loaded but tracer init fails | Tracer skipped | warning: Opik module loaded but tracer initialization failed | | Enabled + config present + module loaded + tracer created | Tracer attaches to world | info: Opik tracer attached |

Opik is storage-agnostic — it attaches to world.eventEmitter and works identically with sqlite, file, or memory storage backends.

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
npm run test:coverage:gate # Coverage + core threshold gate + subsystem scorecard

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
npm run ci:test           # CI gate: coverage threshold + integration

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

Coverage Gates

npm run test:coverage:gate enforces minimum core coverage thresholds and generates a subsystem scorecard:

core statements >= 68%
core branches >= 56%
core functions >= 75%
core lines >= 69%

The scorecard is written to:

coverage/scorecard.md
coverage/scorecard.json

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

# Chat restore/HITL replay debugging
LOG_CHAT_RESTORE=debug LOG_CHAT_RESTORE_RESUME=debug LOG_CHAT_RESTORE_RESUME_TOOLS=debug LOG_HITL=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
API Reference - OpenAPI 3.1 spec for the REST API
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:

read_file, list_files, grep - inspect project files and source trees
write_file - update files inside trusted workspace scope
web_fetch - fetch web pages and convert them to Markdown for agent use
send_message - dispatch trusted chat-context messages to other agents
create_agent - create new agents during a conversation
shell_cmd - run shell commands with trusted-scope validation and lifecycle controls
load_skill - progressively load SKILL.md instructions and related scripts
human_intervention_request - ask the user for structured options and approvals

World owners can set built-in tool access to Read, Ask, or Auto so write/execute actions are blocked, approval-gated, or automatic depending on the world.

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.
load_skill always performs the same preflight flow: script references are discovered from instructions, script execution is HITL-approved and scope-validated, and reference-file context is collected when active resources are present.

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