WorldSeed
A YAML-defined world engine for running, observing, and steering emergent multi-agent scenarios.
What does this agent do, and when should you use it?
WorldSeed is a local world engine for emergent multi-agent scenarios. You define entities, roles, private information, perception filters, actions, rules, and consequences in YAML, then start a scene with the worldseed CLI. Its tick loop gives each character a filtered view of the world and resolves actions through either the YAML DSL or an LLM-based Dungeon Master that returns structured effects. A local dashboard supports observation, private intervention, and playing as a character; runs are preserved for replay. Bundled scenes include AI Layoffs and Teahouse, while documented integration paths include OpenClaw agents, Codex subagents, and models supported by LiteLLM.
Run uv run worldseed validate configs/my_scene.yaml to validate a scene YAML file, then run uv run worldseed play configs/my_scene.yaml to execute it. On every tick, WorldSeed filters state through each character's perception rules, gathers proposed actions, resolves deterministic actions with the in-YAML DSL, and sends uncertain outcomes to the LLM Dungeon Master. The Dungeon Master returns structured effects, which mutate state, trigger consequences, and are logged as the world advances. The local dashboard at http://localhost:8000 provides Watch, Intervene, and Play modes. The /create-world command generates validated YAML scene and UI configuration from a prompt, and authors can also edit files such as configs/teahouse.yaml and configs/ai_layoffs.yaml directly.
- A research group wants specialist characters to turn an early idea into hypotheses, experiments, peer review, and an auditable research trail.
- A narrative or game designer needs to test an espionage or workplace scenario involving secrets, factions, and asymmetric information.
- An AI-tool team wants API researchers, builders, critics, audience agents, and a curator to compete over artifacts in one traceable scene.
- A developer wants to experiment with social-simulation rules, perceptions, and consequence chains in YAML instead of rebuilding a domain-specific engine.
- An engineering team wants to connect OpenClaw agents or Codex subagents to an observable world where operators can privately influence characters.
What are this agent's strengths and limitations?
- YAML declares characters, rules, private information, and perception filters, while the engine has no hardcoded domain knowledge.
- It separates deterministic DSL resolution from uncertain LLM judgment, with the Dungeon Master returning structured effects rather than free-form prose.
- Character-specific perception filtering directly supports secrets, conflicting beliefs, intelligence work, and social simulation.
- The local dashboard combines observation, private intervention, role-play, and replayable run history.
- The documented setup requires Python 3.11+, Node.js 18+, uv, and an npm frontend build.
- A LiteLLM provider configuration and credentials are required; Dungeon Master outcomes depend on the selected model.
- Creating robust worlds requires maintaining YAML scene and UI configuration, perception rules, and DSL rules.
- The documented path is local startup; production deployment, hosted operation, and cost controls are not specified.
How do you install or deploy this agent?
Requirements: Python 3.11+, Node.js 18+, and uv. Run:
git clone https://github.com/AIScientists-Dev/WorldSeed && cd WorldSeed
uv sync --extra dm
cd frontend && npm install && npm run build && cd ..
cp .env.example .env
Add credentials for a LiteLLM provider in .env; the documented examples include OpenAI, Anthropic, and Ollama.
How do you use this agent?
Validate a bundled scene with uv run worldseed validate configs/ai_layoffs.yaml, then start it with uv run worldseed play configs/ai_layoffs.yaml. Open http://localhost:8000 and choose Watch to observe, Intervene to privately message an agent, or Play to enter a character. For a new world, use /create-world "your world description", or author YAML directly, then validate and launch it with uv run worldseed validate configs/my_scene.yaml and uv run worldseed play configs/my_scene.yaml.