English | 中文
Every employee gets an AI representative. The representatives collaborate so humans don't have to.
Firefly is a collaborative AI operating system for 20–200 person cross-border and domestic e-commerce organizations. It gives every employee a dedicated AI agent; the agents communicate horizontally over Google's A2A protocol, and every cross-person decision goes through a human-in-the-loop (HITL) approval — AI proposes, people decide.
Internal codename: E-Commerce-MultiHuman-MultiAgent-OS (design docs and code identifiers keep this name for traceability).
Not another 1-agent-per-person tool (like Cursor), nor a human-replacing 0-human-company (like Paperclip) — instead, it directly lowers the cost of collaboration inside an organization:
| Collaboration cost | What Firefly does |
|---|---|
| Information transfer: meetings, group chats, repeated explanation | Agents auto-translate, summarize, and inherit context |
| Alignment cost: cross-department meetings, email | A2A protocol structures alignment; deadlocks auto-escalate to a human |
| Oversight cost: manual daily/weekly reports | Conversation is the ERP data layer — captured automatically |
| Page | Path | Purpose |
|---|---|---|
| 🤖 My Agent | /my-agent |
Chat with your own agent + read-only chat with colleagues' agents (two tabs) |
| 📊 Dashboard | /dashboard |
Company-wide task flow + KPIs + sparkline trends |
| 🌐 Organization | /organization |
Visual org tree (@xyflow/react); node CRUD + auto skill assignment + prompt init |
| ⚡ Workflows | /workflows |
DAG SOP editor; AI generation + team-discussion mode (CEO + managers meet live) |
| 📬 A2A Messages | /messages |
Cross-employee agent comms hub (7 message types + two-way HITL approval) |
| ✨ Skills | /skills |
Company skill library (35 baseline skills) + override chain + version rollback |
| 📚 Knowledge | /knowledge |
Three-tier namespaces + RAG + embeddings |
| ⚙️ Settings | /settings |
Account + organization + members + departments + projects |
- One-click org generation — upload an org-chart screenshot → AI parses it → admin activates → the whole org goes live.
- CEO task fan-out — the CEO issues a strategic directive → it auto-decomposes to each department → employees are notified.
- HITL approval loop — an employee finishes work → submits → the supervisor's agent advises → the supervisor approves.
- A2A horizontal collaboration — Alice's agent asks Bob's agent for data → two-way HITL approval → the information flows back.
- Deadlock protection — two agents argue for several rounds without converging → the system pauses and summons both employees to decide.
Application layer (4 core visual modules, all driven by one graph engine)
Agent workspace ╲ Dashboard task flow ╲ Org chart ╲ SOP workflow editor
shadcn/ui + @assistant-ui/react | @xyflow/react
▼
Agent Runtime layer
Vercel AI SDK v6 ToolLoopAgent ─ HITL Tool Approval ─ Tools ─ Streaming
▼
A2A protocol layer (Google A2A Protocol v1.2)
inform / sync / request / commit / handoff / escalate / block
Sender approval + Receiver handling + deadlock detection
▼
Infrastructure
Next.js 16 (App Router) + Drizzle ORM + Postgres (Neon) + pgvector
Better Auth + Inngest (durable workflows) + Vercel AI Gateway
See docs/architecture/ for the full architecture.
- Frontend: Next.js 16 + React 19 + Tailwind CSS v4 + shadcn/ui
- Graph engine: @xyflow/react v12 (org tree / SOP DAG / task flow)
- Chat UI: Vercel AI SDK v6 + assistant-ui + shiki (syntax highlighting)
- Backend: Next.js Route Handlers + SSE
- Database: PostgreSQL 17 (Neon) + Drizzle ORM + pgvector
- Auth: Better Auth (OAuth + self-service password change + account deletion)
- AI routing: Vercel AI Gateway (Anthropic / Google / OpenAI)
- Workflows: Inngest (task-review / theater-meeting)
- i18n: English / 中文 / Bahasa Melayu (next-intl), English default with browser-language detection
- Demo module: Firefly Theater (Phaser 3 + pixel-art isometric office, 10 characters + 8 rooms)
# Node 24+ and pnpm
node --version # >= v24
pnpm --versionCopy the template and fill in your own keys:
cd web
cp .env.example .env
# Open .env and fill in:
# DATABASE_URL (Neon Postgres free tier works; remember CREATE EXTENSION vector)
# BETTER_AUTH_SECRET (generate: node -e "console.log(require('crypto').randomBytes(32).toString('base64'))")
# AI_GATEWAY_API_KEY (https://vercel.com/dashboard/ai/gateway)pnpm install
pnpm drizzle-kit migrate # apply schema to the DBpnpm dev
# open http://localhost:3000The first account to register becomes the organization owner (CEO).
firefly/
├── web/ # Next.js main app
│ ├── app/ # App Router routes (8 pages + 60+ API endpoints)
│ ├── components/ # Main UI components (organization / workflows / my-agent / messages / theater)
│ ├── lib/
│ │ ├── ai/ # Agent runtime + tools + skill matcher + prompt generator
│ │ ├── db/schema/ # Drizzle schema (orgs / agents / tasks / a2a / sop / knowledge / theater)
│ │ ├── inngest/ # Durable workflows
│ │ └── stores/ # Zustand stores (org-draft, etc.)
│ ├── drizzle/ # SQL migrations
│ └── i18n/messages/ # en.json + zh.json + ms.json (English / 中文 / Bahasa Melayu)
├── docs/ # Documentation archive (organized by topic)
│ ├── product/ # PRD
│ ├── delivery/ # Historical delivery reports
│ ├── design/ # Design system (visual source of truth)
│ ├── architecture/ # Current / target architecture + entry README
│ ├── plans/ # Full design docs (ideation / design / ui / api / plan / rules)
│ ├── critique/ # Critique reports (one per page)
│ ├── pipeline/ # AutoDev pipeline status
│ ├── pitch/ # Investor pitch drafts
│ └── references/ # Reference repositories, etc.
└── assets/ # Third-party assets (Modern Interiors tileset, etc.)
-
Owner-is-CEO invariant — the server guarantees the signed-in operator always appears in the
employeestable as the owner. LLM-parsed org charts often omit the CEO who is actually typing, so the server injects a fallback automatically. -
AI SOP generation + team discussion — type a fuzzy requirement like "customer-complaint handling process" → pick team-discussion mode → the CEO's and middle-manager agents hold a real 2–3 round meeting → the result is auto-assembled into a DAG → editable visually like n8n.
-
Three clearly layered conversation semantics:
- Me ↔ my agent (read/write)
- Me ↔ another employee's agent (read-only, like "calling a colleague to ask")
- My agent ↔ another agent (A2A, two-way HITL approval)
-
Zero-string-matching semantic skill assignment — one LLM call matches skills to roles by meaning, not string matching: "VP Sales" ≡ "销售总监" ≡ "Sales Director" all resolve to the same concept.
-
Deadlock detection — 6 messages in one thread without convergence → the system pauses and summons both employees to decide.
-
A real agent-mesh runtime — on receiver Accept, a fire-and-forget non-interactive chat (
generateText+stepCountIs(4)) runs the receiver's agent, so agents genuinely "talk" rather than just store messages.
The Firefly source code is released under the MIT License — © 2026 Firefly.
Third-party assets and dependencies retain their own licenses:
- Pixel art: Modern Interiors v2.2 (Limezu) — see
assets/theater-tileset/Modern tiles_Free/LICENSE.txt - Fonts: Inter / Lora / JetBrains Mono (Google Fonts, OFL 1.1)
- Icons: Lucide Icons (ISC)
- AI models: Anthropic Claude / Google Gemini (via Vercel AI Gateway)
#multi-agent #A2A-protocol #HITL #Next.js #AI-SDK-v6 #@xyflow/react #enterprise-AI #agent-mesh