Agent-Worlds

**[中文](README_zh.md) | English**

# Agent-Worlds

> Multi-Agent OS — AI characters live, wander, and talk in a pixel-art world

![Python](https://img.shields.io/badge/Python-3.10+-blue)
![React](https://img.shields.io/badge/React-18-blue)
![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-green)
![License](https://img.shields.io/badge/License-MIT-green)

![Main Map](docs/screenshots/01-main-map.jpg)

## What is this?

Agent-Worlds is an **operating system for AI agents**. You drop NPC characters into a 2D pixel-art world, and they:

- **Wander** around the map autonomously
- **Bump into** each other and start conversations
- **Remember** what happened (RAM buffer during chat, persistent HJL memory after)
- **Use tools** — browse the web, generate images, write code, call external APIs
- **Collaborate** — chain multiple NPCs to complete complex workflows

Think of it as a SimCity for LLM agents, with a real-time pixel map, a skill system, and MCP protocol support.

## Features

- **Collision-driven social engine** — NPCs meet on the map and autonomously decide to chat
- **Pixel-art 2D map** — Real-time rendered 48x48 pixel world with multiple scenes
- **Skill system** — Give an NPC abilities with one line of config: `"skills": ["programmer"]`
- **MCP protocol** — Connect external tool servers (browser, database, etc.)
- **Layered memory** — RAM buffer (live conversation) + HJL file (persistent history)
- **Multi-world** — Switch between worlds: modern city, wasteland camp, comic studio
- **Comic production pipeline** — Example: scriptwriter -> storyboard -> artist -> layout -> voice actor
- **Multi-LLM support** — DeepSeek, Zhipu GLM, Volcano Engine, OpenAI-compatible, local models
- **Player mode** — Join the world as a player and talk to NPCs directly

### Screenshots

| NPC Conversation | World Management | NPC Configuration |
|:---:|:---:|:---:|
| ![Conversation](docs/screenshots/02-conversation.jpg) | ![World](docs/screenshots/03-world-panel.jpg) | ![NPC Con