# AgentSim — Complete Technical Reference

> Multi-agent social simulation engine powered by Claude AI. Drop AI agents into a world and watch what happens.

## Overview

AgentSim is an open-source (Apache 2.0) multi-agent social simulation engine that uses Anthropic's Claude AI to power autonomous agent cognition. It creates rich, emergent social dynamics between AI agents — each defined with distinct personalities, memories, goals, values, and fears. No outcomes are scripted; all behavior emerges from agent interactions.

**Repository**: https://github.com/vinimartinson/agent-sim
**Website**: https://www.agentsim.io
**License**: Apache 2.0 — Free forever
**Author**: Vinicius Martinson

---

## What Makes AgentSim Different

Unlike chatbot frameworks or simple prompt chains, AgentSim is a full simulation runtime. Agents don't just respond to prompts — they perceive their environment, maintain persistent memory, track relationships with other agents, and make decisions based on personality psychology (Big Five model). The result is believable, emergent social behavior that unfolds over time.

Key differentiators:
- **Personality-driven cognition**: Big Five (OCEAN) personality model scores 0–100 per trait
- **Persistent directional relationships**: Trust and tension tracked per agent pair, evolving each tick
- **Memory with compression**: Private memory arrays auto-summarized by Claude when full
- **God Mode intervention**: Inject events, send secret messages, observe private reasoning mid-simulation
- **Real-time observation**: WebSocket streaming with D3 network visualization

---

## Agent Model

Each agent in AgentSim is defined by:

### Personality Traits (Big Five / OCEAN)
- **Openness** (0–100): Creativity, curiosity, willingness to try new things
- **Conscientiousness** (0–100): Organization, discipline, goal-orientation
- **Extraversion** (0–100): Sociability, assertiveness, energy from social interaction
- **Agreeableness** (0–100): Cooperation, empathy, conflict avoidance
- **Neuroticism** (0–100): Emotional reactivity, anxiety, stress response

### Additional Agent Properties
- **Values**: Core principles that guide decision-making (e.g., "honesty", "loyalty", "survival")
- **Fears**: Anxieties that influence behavior under stress (e.g., "abandonment", "failure")
- **Goals**: Objectives the agent actively pursues (e.g., "gain trust of the group", "find an escape route")
- **Backstory**: Narrative context that informs the agent's worldview
- **Private Memory**: jsonb array (capped at 40 entries) of observations, decisions, and reflections

### Data Model
```
agent.personality_traits → jsonb { O: 88, C: 82, E: 35, A: 55, N: 42 }
agent.values → ["loyalty", "truth"]
agent.fears → ["betrayal", "isolation"]
agent.goals → ["protect the group", "uncover the truth"]
agent.memories → jsonb[] (max 40, auto-compressed)
```

---

## Relationship System

Relationships in AgentSim are **directional** — Agent A's trust in Agent B is independent of Agent B's trust in Agent A.

Each relationship tracks:
- **Trust** (-100 to +100): How much one agent relies on another
- **Tension** (0 to 100): Conflict or unresolved friction between agents

Relationships evolve each tick based on agent actions:
```
relationship.apply_delta!(trust: +12, tension: -3)
```

This creates asymmetric social dynamics: Agent A might trust Agent B deeply while Agent B is secretly plotting against them.

---

## Simulation Tick Architecture

Each simulation progresses through discrete "ticks." Every tick follows four phases:

### Phase 1: Perceive
Agents observe all public actions from the previous tick and receive any private messages (including God Mode injections). The agent's perception is filtered through their personality — a high-Neuroticism agent may interpret neutral events as threatening.

### Phase 2: Decide
Claude AI evaluates the full agent context:
- Current personality traits and emotional state
- All memories (recent and compressed)
- Relationship states with every other agent
- Current environment description and active events
- Personal goals, values, and fears

The model selects an action and generates internal reasoning (visible in God Mode).

### Phase 3: Act
The chosen action is:
- Broadcast to all agents as a public event (or sent privately if it's a whisper)
- Relationship deltas are calculated and applied
- The action is stored in the acting agent's memory
- WebSocket event is emitted for real-time dashboard updates

### Phase 4: Reflect
When an agent's memory array approaches the 40-entry cap:
- Claude summarizes older memories into compressed form
- Key emotional moments and relationship shifts are preserved
- Routine observations are consolidated
```
ClaudeService.summarize_memories(agent, threshold: 40)
```

---

## Built-In Scenarios

### 1. The Cabin (Survival)
**Setting**: Remote Norwegian cabin during a severe snowstorm. No communication with the outside world.
**Premise**: Four strangers must cooperate to survive, but trust is scarce.
**Agents**:
| Name | Role | O | C | E | A | N |
|------|------|---|---|---|---|---|
| Nora | The Analyst | 88 | 82 | 35 | 55 | 42 |
| Dayo | The Charmer | 72 | 45 | 91 | 78 | 28 |
| Ingrid | The Survivor | 40 | 90 | 30 | 35 | 65 |
| Felix | The Wildcard | 95 | 25 | 85 | 60 | 75 |

### 2. The Office (Workplace)
**Setting**: Dunder Mifflin-inspired paper company office.
**Premise**: A workplace crisis forces the team to confront interpersonal dynamics.
**Agents**: Michael Scott, Dwight Schrute, Jim Halpert, Pam Beesly — each modeled with personality traits matching their TV characterizations.

### 3. Hospital (High-Stakes)
**Setting**: Night shift in an understaffed emergency room.
**Premise**: Limited resources and incoming patients force difficult triage decisions.
**Agents**:
| Name | Role |
|------|------|
| Dr. Rivera | Attending physician, calm under pressure |
| Nurse Okafor | Experienced ER nurse, empathetic but firm |
| Dr. Chen | Resident, brilliant but socially awkward |
| Nurse Kowalski | New hire, eager but overwhelmed |

### 4. Startup (Pressure)
**Setting**: NovaTech headquarters, a small tech startup.
**Premise**: 48 hours until the investor demo, but the core feature is broken.
**Agents**:
| Name | Role |
|------|------|
| Alex | Founder/CEO, visionary but stressed |
| Maya | Lead engineer, perfectionist |
| Jordan | Business development, hustler mentality |
| Sam | Designer, creative but conflict-averse |

### Custom Scenarios
Users can build custom worlds with:
- Custom environment descriptions
- Any number of agents with user-defined personality traits
- Custom goals, values, fears, and backstories per agent
- Configurable simulation parameters

---

## God Mode Features

God Mode gives the simulation operator full control:

- **Event Injection**: Add unexpected events mid-simulation (e.g., "A loud crash comes from the basement")
- **Secret Messages**: Send private information to specific agents that others cannot see
- **Memory Inspection**: Read any agent's private memory and internal reasoning
- **Relationship Dashboard**: View the full trust/tension matrix between all agents
- **Tick Control**: Pause, step through, or fast-forward the simulation

API endpoint: `POST /api/simulations/:id/messages`

---

## Technical Stack

| Layer | Technology |
|-------|-----------|
| Backend Framework | Ruby on Rails |
| Real-Time | ActionCable (WebSocket) |
| AI Engine | Anthropic Claude API |
| Database | PostgreSQL |
| Data Storage | jsonb columns for personality, memory, relationships |
| Frontend | React 19 + TypeScript |
| Styling | Tailwind CSS 4 |
| Visualization | D3.js (network graphs) |
| Build Tool | Vite |

---

## API Overview

### Simulation Lifecycle
- `POST /api/simulations` — Create a new simulation with agents and environment
- `GET /api/simulations/:id` — Retrieve simulation state
- `POST /api/simulations/:id/ticks` — Advance the simulation by one tick
- `POST /api/simulations/:id/messages` — Inject God Mode events or messages

### WebSocket Events
- `SimulationChannel.broadcast("tick_completed")` — Emitted after each tick
- Includes agent actions, relationship changes, and memory updates

---

## Installation and Quick Start

### Prerequisites
- Ruby 3.x
- Rails 7.x
- PostgreSQL
- Anthropic API key (Claude)

### Setup
```bash
git clone https://github.com/vinimartinson/agent-sim.git
cd agent-sim
bundle install
rails db:setup
rails server
```

### Configuration
Set your Anthropic API key as an environment variable:
```bash
export ANTHROPIC_API_KEY=your_key_here
```

---

## Use Cases

### AI Research
Study emergent behavior, social dynamics, and decision-making in multi-agent systems. AgentSim provides a controlled environment for observing how personality traits influence group outcomes.

### Game Design & NPCs
Prototype believable NPC social dynamics. Test how personality-driven agents form factions, negotiate, and respond to player-injected events.

### Education
Teach social psychology, group dynamics, and organizational behavior through interactive simulation. Students can modify personality parameters and observe behavioral changes.

### Interactive Storytelling
Generate unscripted, character-driven narratives. Each simulation run produces unique story arcs based on agent interactions and emergent social dynamics.

### Team Dynamics & Organizational Modeling
Model workplace scenarios to explore conflict resolution strategies, leadership dynamics, and team composition effects.

---

## Keywords and Topics

Multi-agent simulation, AI agents, social simulation, emergent behavior, Claude AI, Anthropic, Big Five personality model, OCEAN personality traits, agent-based modeling, AI NPCs, autonomous agents, social dynamics simulation, trust modeling, relationship simulation, personality-driven AI, open source AI tools, Ruby on Rails AI, WebSocket real-time AI, interactive simulation, agent cognition, memory compression, AI storytelling, narrative generation, group dynamics, organizational simulation, AI research tools

---

## Links

- **Source Code**: https://github.com/vinimartinson/agent-sim
- **Landing Page**: https://www.agentsim.io
- **Author GitHub**: https://github.com/vinimartinson
- **License**: Apache 2.0