DEV Community

Cover image for What Is MiroFish? A Multi-Agent AI Simulation Platform for Predicting Social Media Outcomes
Wanda
Wanda

Posted on • Originally published at apidog.com

What Is MiroFish? A Multi-Agent AI Simulation Platform for Predicting Social Media Outcomes

Introduction

You’ve seen it happen. A company announces a new policy. A celebrity makes a controversial statement. A news story breaks that nobody expected. Social media explodes, and the consequences ripple outward in ways nobody predicted.

Try Apidog today

What if you could see how a scenario plays out before it happens in the real world?

MiroFish is a multi-agent AI simulation platform that answers “what if” questions about social media. It creates a digital parallel world where hundreds of AI agents with distinct personalities, memories, and behavioral patterns interact freely. You upload seed material—a news article, a policy draft, a research paper—and MiroFish simulates how different audiences might react over time.

💡 The MiroFish team built and tested all simulation APIs using Apidog. From designing the graph construction endpoints to validating interview API responses, Apidog served as the single source of truth for the backend/frontend contract throughout development.

This explainer covers what MiroFish does, how multi-agent simulation works, and when you might use it.

What Problem Does MiroFish Solve?

The Prediction Gap

Social media moves fast and reacts in unpredictable ways. Traditional analysis tools look backward:

  • Sentiment analysis tells you what people think now
  • Trend monitoring shows you what’s popular today
  • Engagement metrics measure what already happened

None of these help you see what might happen if you publish that announcement, release that report, or respond to that controversy.

The Alternative: Digital Parallel Worlds

MiroFish takes a different approach. Instead of analyzing real social media, it creates a simulated version:

  1. Build a knowledge graph from your source documents
  2. Extract entities (people, organizations, media outlets) and turn them into AI agents
  3. Assign personalities based on extracted information (activity levels, influence weights, stance positions)
  4. Run a simulation where agents post, comment, and react over simulated hours or days
  5. Analyze the outcome to see how narratives form, which voices dominate, and what counter-movements emerge

Think of it as a flight simulator for social media scenarios.

How MiroFish Works: The Five-Step Workflow 

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Step 1    │ ──► │   Step 2    │ ──► │   Step 3    │ ──► │   Step 4    │ ──► │   Step 5    │
│  Ontology   │     │  GraphRAG   │     │   Env       │     │ Simulation  │     │   Report    │
│  Generation │     │   Build     │     │   Setup     │     │   Run       │     │ Generation  │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
Enter fullscreen mode Exit fullscreen mode

Step 1: Ontology Generation

  • Analyze input documents and simulation requirements.
  • Use an LLM to generate a custom ontology:
    • 10 entity types (e.g., Student, Professor, University, MediaOutlet, GovernmentAgency)
    • 10 relationship types (e.g., WORKS_FOR, COMMENTS_ON, RESPONDS_TO)
    • Attributes for each type
  • Two-tier structure: 8 specific types from your content, plus 2 fallback types (Person, Organization).

Step 2: GraphRAG Construction

  • Chunk documents (500 chars with 50-char overlap) and send to Zep Cloud in batches.
  • The system:
    1. Creates a standalone graph with a unique ID
    2. Sets the custom ontology
    3. Sends text batches for entity and relationship extraction
    4. Waits for Zep to process each episode
    5. Retrieves the final graph with nodes and edges

Result: a knowledge graph with hundreds or thousands of entities connected by relationships.

Step 3: Environment Setup

  • Simulation config generator analyzes the knowledge graph and creates agent parameters:
    • Time configuration (e.g., Chinese timezone: peak hours 19-22, dead hours 0-5)
    • Event configuration (initial posts, hot topics)
    • Agent activity configs (posts per hour, response delays, influence weights)
    • Platform configs for Twitter and Reddit (different viral thresholds)

Step 4: Simulation Run

  • Agents act based on activity schedules (posting, commenting, reacting).
  • Parallel simulations for Twitter and Reddit.
  • Every action is logged to JSONL files in real-time.
  • Example: A 72-hour simulation generates thousands of actions per platform.

Step 5: Report Generation

  • The Report Agent uses 3 core retrieval tools:
    • InsightForge: Deep-dive search, decomposes questions into sub-queries
    • PanoramaSearch: Full-scope view, including expired/invalid historical facts
    • InterviewAgents: Real-time interviews with active agents via IPC

The final report covers narrative evolution, key moments, influential voices, and counter-movements.

What Are AI Agents in MiroFish?

Each agent is an independent AI entity:

Attribute Description Example
Identity Name, username, bio “@ZhangWei_Student”
Persona Personality and background “Graduate student researching AI ethics”
Activity Level How often they post (0.0-1.0) 0.8 = very active
Active Hours When they’re online [8,9,10,11,18,19,20,21,22,23]
Response Delay How fast they react (minutes) 5-30 min
Influence Weight How likely others see their posts 0.8 (low) to 3.0 (high)
Stance Position on topics Supportive, opposing, neutral, observer
Memory Past actions and interactions Stored in Zep Cloud graph

Agents decide autonomously: when to post, what to comment on, and how to respond, based on their personality and current simulation state.

What Can You Simulate?

News and Policy Announcements

  • Upload a policy draft or news article.
  • Simulate reactions by different stakeholder groups:
    • Which voices amplify the message?
    • What criticisms emerge?
    • How do narratives evolve over 24-72 hours?

Academic Research

  • Upload a research paper.
  • Simulate academic and public reception:
    • Which findings get attention?
    • What misunderstandings arise?
    • How do expert and layperson responses differ?

Crisis Scenarios

  • Upload incident reports or background materials.
  • Test response strategies:
    • How does the narrative shift if you respond immediately vs. wait?
    • What counter-narratives emerge?
    • Which influencers drive the conversation?

Literary and Historical Analysis

  • Upload a novel or historical text.
  • Explore “what if” scenarios:
    • How might characters react to events beyond the original ending?
    • What alternative outcomes are plausible?
    • Which relationships drive key plot points?

What Makes MiroFish Different?

Swarm Intelligence, Not Single Agents

Most AI tools use a single agent to simulate “a user.” MiroFish runs hundreds of agents with unique personalities, enabling emergent behaviors—narratives and movements from interactions, not scripts.

Dual-Platform Simulation

Simulates both Twitter and Reddit:

  • Twitter: Fast viral spread, high influencer impact
  • Reddit: Threaded discussions, community-driven narratives

Compare how platform mechanics affect outcomes.

Temporal Knowledge Graph

Relationships include time metadata:

  • valid_at: When the relationship became valid
  • invalid_at: When it became invalid
  • expired_at: When it was superseded

This enables tracking of relationship evolution—not just the current state.

Live Agent Interviews

Interview agents during/after simulation for qualitative insights:

Question: “What do you think about the university’s response?”

Agent 12 (Student): [Twitter] “They waited too long. By the time they responded, the narrative had already solidified.” [Reddit] “I get why they hesitated—legal review takes time. But the delay cost them credibility.”

Technical Architecture at a Glance 

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Frontend       │     │  Backend        │     │  External       │
│  (Vue.js)       │ ◄─► │  (FastAPI)      │ ◄─► │  Services       │
│                 │     │                 │     │                 │
│ - Graph builder │     │ - REST API      │     │ - Zep Cloud     │
│ - Simulation    │     │ - Subprocess    │     │ - LLM API       │
│   monitor       │     │   management    │     │ - OASIS         │
│ - Report viewer │     │ - JSONL stream  │     │   Framework     │
└─────────────────┘     └─────────────────┘     └─────────────────┘
Enter fullscreen mode Exit fullscreen mode

Backend Stack

  • Python FastAPI for REST endpoints
  • OASIS Framework for agent simulation
  • Zep Cloud for knowledge graph storage and retrieval
  • SQLite for simulation state databases

Frontend Stack

  • Vue.js 3 for reactive UI
  • WebSocket for real-time updates
  • D3.js for graph visualization

API Design with Apidog

The MiroFish backend exposes 40+ endpoints across 5 major services:

Service Endpoints Purpose
Graph Build 8 Ontology generation, batch upload, status polling
Entity Reader 4 Entity filtering, type selection, export
Config Generator 6 Time/event/agent/platform config generation
Simulation Runner 12 Start, stop, monitor, interview, state management
Report Generator 5 Retrieval, analysis, summary generation

Apidog was used to design all endpoints, mock responses, and generate API documentation—catching schema mismatches early and aligning the team throughout development.

When Should You Use MiroFish?

Good Use Cases

  • Scenario planning: “What if we announce X next week?”
  • Stakeholder analysis: “How will different groups react to Y?”
  • Narrative tracking: “What counter-arguments emerge against Z?”
  • Research validation: “Do our hypotheses about audience behavior hold up?”
  • Educational exploration: “How might these historical figures respond to modern events?”

Not Good Use Cases

  • Precise prediction: MiroFish shows plausible outcomes, not guaranteed futures
  • Real-time monitoring: It simulates scenarios, not live social media
  • Small-scale analysis: Best for hundreds of agents, not simple surveys
  • Non-social phenomena: Built for social media dynamics, not economics/physics

Getting Started with MiroFish

Requirements

  • Python 3.10+
  • Node.js 18+
  • Zep Cloud API key
  • LLM API access (OpenAI-compatible)

Quick Start 

# Clone the repository
git clone https://github.com/666ghj/MiroFish.git
cd MiroFish

# Install dependencies
pip install -r requirements.txt
npm install

# Configure environment
cp .env.example .env
# Edit .env with your API keys

# Start the backend
python backend/app/main.py

# Start the frontend
npm run dev
Enter fullscreen mode Exit fullscreen mode

First Simulation

  1. Upload documents: PDF, TXT, or MD files as source material
  2. Define simulation requirements: What question are you exploring?
  3. Generate ontology: Let the system analyze and propose entity types
  4. Build knowledge graph: Extract entities and relationships
  5. Configure and run: Set simulation duration and start
  6. Monitor and interview: Watch actions in real-time, interview agents
  7. Generate report: Get a summary of what happened

A typical first simulation takes 30-60 minutes end-to-end.

Frequently Asked Questions

How accurate are the simulations?

MiroFish generates plausible scenarios from input data and behavioral models. Use it to explore possibility space, not as a predictor of specific outcomes. Its value is in surfacing unexpected dynamics.

How many agents can MiroFish simulate?

The system runs 50-200 agents comfortably. Larger simulations (500+) require more compute and take longer.

Can I customize agent behavior?

Yes—modify activity patterns, influence weights, and stance distributions. Advanced users can edit agent configs directly before running simulations.

Does MiroFish support non-Chinese scenarios?

Default timezone config is for Chinese social media, but you can customize activity patterns for other regions in the time configuration.

Is my data private?

Documents are processed locally and sent to Zep Cloud for entity extraction. Zep retains data per their terms. For sensitive materials, use a local graph database alternative.

Conclusion

MiroFish lets you create digital parallel worlds to test social media scenarios before they happen. By simulating hundreds of AI agents with unique personalities and behaviors, you can reveal emergent narratives, counter-movements, and influential voices that traditional tools miss.

Whether you’re planning a policy announcement, researching audience behavior, or exploring literary “what ifs,” MiroFish offers a practical lens for understanding complex social dynamics.

Top comments (0)