Agent World Builder

Agent World Builder is a configurable sandbox engine for building interactive, multi-agent learning worlds. It turns domain knowledge, curriculum goals, scenario design, NPC roles, relationship graphs, events, and tutor feedback into runnable simulation worlds.

Try Live Demo · Watch 60s Demo · Build Your First World

The project is designed for classroom role-play, social-economic simulation, literature immersion, history deduction, business strategy training, and other learning experiences where a learner should not merely read content, but act inside a living system.

Most educational chatbots answer questions. Agent World Builder builds worlds.

A world in this project has state, resources, characters, relationships, hidden information, random events, consequences, memory, and an AI tutor. A learner's action can change local relationships, trigger events, shift NPC attitudes, expose misconceptions, and generate a debrief that maps play back to learning goals.

• Config-driven worlds: each sandbox lives under worlds/<world_id>/ with a world bible, cards, and runtime configs.
• Multi-agent runtime: NPCs react to player actions, remember interactions, and can interact with each other.
• Mechanism skill library: reusable economics, sociology, psychology, organization, pedagogy, simulation, and game-design mechanisms.
• Tutor layer: observes actions, detects learning signals, offers guidance, and supports final reflection.
• Relationship graph UI: visualizes people, organizations, influence, trust, supply, authority, and hidden dependencies.
• World generation pipeline: converts prompts, knowledge sources, and skills into structured world cards and runtime config.
• Ready-made sandboxes: includes history, literature, business, community operations, and social-economic scenarios.

Example worlds include:

• beer_game_supply_chain - supply chain coordination and delayed feedback.
• dream_cafe_startup - startup operations, customer trust, and resource allocation.
• g7h_12_three_kingdoms - historical strategy and alliance dynamics.
• g8h_26_market_economy - market economy mechanisms and policy trade-offs.
• g9y_11_drunken_pavilion - literature immersion and perspective-taking.
• 社区菜鸟驿站的日常运营与决策沙盘 - community parcel-station operations and neighborhood relationships.

Knowledge / curriculum / cases
        -> skill_library/
        -> world cards
        -> world_bible.md
        -> runtime configs
        -> FastAPI runtime
        -> React sandbox UI
        -> tutor feedback and debrief

Core directories:

backend/        FastAPI runtime, session state, events, NPCs, tutor, memory
frontend/       React + Vite sandbox interface
pipelines/      world generation and config conversion tools
skill_library/  reusable mechanism documents
worlds/         runnable sandbox definitions
docs/           design standards and architecture notes

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python -m uvicorn backend.app.main:app --reload --host 127.0.0.1 --port 8000

cd frontend
npm install
npm run dev

Open http://localhost:3000.

Copy .env.example to .env and fill in one provider:

DEEPSEEK_API_KEY=your_key_here
DEEPSEEK_MODEL=deepseek-chat

The runtime can still load and inspect worlds without an LLM key, but generation, dialogue, and richer tutor behavior need a configured provider.

Each complete world usually contains:

worlds/<world_id>/
  world_bible.md
  cards/
    world_brief.md
    actor_card.md
    relationship_card.md
    hidden_information_card.md
    randomness_card.md
    event_card.md
    learning_card.md
    evaluation_card.md
    resource_card.md
  configs/
    world_config.yaml
    npc_profiles.json
    relationship_graph.json
    event_rules.json
    skill_bindings.json
    mentor_flow.json
    dashboard_config.json
    consequence_rules.json

This separation keeps the app generic: new worlds are added through configuration rather than hard-coded frontend or backend logic.

• Project Overview
• World Design SOP
• Skill Design Standard
• NPC Interaction Protocol
• Runtime Architecture
• World Generation Pipeline
• v0.1.0 Release Notes

Useful checks:

python -m py_compile backend/app/main.py
cd frontend && npm run build

Generated caches, local logs, .env, node_modules, and runtime memory files are intentionally ignored.

MIT. See LICENSE.