-
-
Agent Society — five specialist AI agents collaborating through Qwen Cloud
-
Complete system architecture — Qwen Cloud, FastAPI backend, SQLite database, and web frontend all connected
-
The five agents and their roles — Planner, Researcher, Writer, Critic, and Executor
-
The self-correction engine — Writer and Critic negotiate until quality reaches 8/10 or higher
-
The shared memory whiteboard — how all five agents stay synchronized during a task
-
Real SQLite database persisting every session — task, plan, draft, critique, and final output saved permanently
-
Offline simulator showing the complete agent pipeline — no API key required to preview the flow
-
Live run on real Qwen Cloud — generating a go-to-market strategy for an AI tutoring app in Nigeria
-
The working web interface — real-time agent collaboration with properly formatted output
-
Real output sample — executive brief generated for the Nigeria AI tutoring app task
-
Benchmark results — Agent Society scores higher than a single-agent baseline across all three test tasks
-
FastAPI REST backend — interactive API documentation for submitting tasks
-
Open source repository — MIT licensed, fully documented on GitHub
-
How Agent Society addresses all four hackathon judging criteria
-
Key results at a glance from live testing on real Qwen Cloud tasks
Agent Society — Project Story
Inspiration
The idea did not come from a textbook. It came from watching people work.
Every great outcome I have ever witnessed involved division of labour — a strategist, a researcher, a creator, a critic, and someone who ties it all together. No single person does all five jobs well simultaneously. Yet every AI tool I had used handed me exactly that: one model, one brain, one shot.
That felt fundamentally broken.
The economist Adam Smith demonstrated in 1776 that dividing a pin-making job across ten specialists produced thousands of times more output than one person doing every step alone. I asked myself one question:
What happens when you apply that same principle to artificial intelligence?
Agent Society was born from that question.
What It Does
Agent Society is a multi-agent collaboration system where five specialist AI agents — each powered by Qwen Cloud — work together on any complex task the way a real expert team would.
You submit one task. The pipeline activates:
$$\text{Task} \xrightarrow{\text{Planner}} \text{Plan} \xrightarrow{\text{Researcher}} \text{Knowledge} \xrightarrow{\text{Writer}} \text{Draft} \xrightarrow{\text{Critic}} \text{Feedback} \xrightarrow{\text{Revise}} \text{Approved} \xrightarrow{\text{Executor}} \text{Deliverable}$$
| Agent | Role |
|---|---|
| 🗺️ Planner | Decomposes the task into subtasks with explicit role assignments and dependencies |
| 🔍 Researcher | Synthesises relevant knowledge into structured facts and data points |
| ✍️ Writer | Produces drafts, then revises iteratively based on critic feedback |
| 🔎 Critic | Scores every draft across five dimensions and negotiates improvements |
| 📦 Executor | Packages the approved output into a polished final deliverable |
The Critic scores every draft using a mean quality threshold:
$$\bar{S} = \frac{S_{\text{accuracy}} + S_{\text{completeness}} + S_{\text{clarity}} + S_{\text{structure}} + S_{\text{depth}}}{5}$$
The approval decision follows a simple rule:
$$\text{Verdict} = \begin{cases} \textbf{APPROVED} & \text{if } \bar{S} \geq 8 \ \textbf{REVISE} & \text{if } \bar{S} < 8 \end{cases}$$
All agents share a common memory whiteboard — every plan, research brief, draft, and critique written to named keys that every other agent can read before responding. This is what makes the collaboration real rather than simulated.
How We Built It
The system is built in Python with a clean modular architecture across five layers:
agent_society/
├── orchestrator/ ← Master coordinator
├── agents/ ← Five specialist agents
├── memory/ ← Shared whiteboard
├── api/ ← FastAPI REST backend
└── simulate.py ← Offline demo pipeline
Every agent inherits from a BaseAgent class that handles all Qwen Cloud API calls via the OpenAI-compatible DashScope endpoint:
response = client.chat.completions.create(
model="qwen-plus",
messages=[
{"role": "system", "content": self.role_prompt}, # agent personality
{"role": "user", "content": context}, # enriched prompt
]
)
The SharedMemory class acts as the whiteboard. The Critic–Writer negotiation loop runs until approval or the maximum round limit is reached:
for round_num in range(1, max_rounds + 1):
draft = writer.run(prompt)
critique = critic.run(draft)
if "APPROVED" in critique.upper():
break # quality confirmed — exit early
The efficiency gain of multi-agent collaboration over a single-agent baseline is estimated as:
$$\Delta Q = Q_{\text{multi-agent}} - Q_{\text{single-agent}}$$
where $Q$ is the mean evaluator score across $n$ benchmark tasks:
$$Q = \frac{1}{n} \sum_{i=1}^{n} \bar{S}_i$$
The backend is a FastAPI REST API deployed on Alibaba Cloud ECS, with session logs and memory snapshots persisted to Alibaba Cloud OSS — the Object Storage Service that acts as the project's audit filing cabinet.
Challenges I Ran Into
🐛 Debugging across five agents
When output quality was poor, five suspects were in the room. The fix was a full conversation audit log — every agent message and memory write, timestamped — so failures could be replayed and traced to the exact link in the chain where they broke.
💻 Simulating locally without a live API key
Before Qwen Cloud credentials arrived, the full pipeline still needed to be testable and demonstrable. An offline simulator was built with realistic mocked responses and colour-coded terminal output — printing each agent's dialogue in sequence — so the entire flow could be seen, debugged, and shown to others without a single real API call.
🔑 Configuring the Alibaba Cloud API and DashScope endpoint
Understanding the difference between qwen-turbo, qwen-plus, and qwen-max, and discovering that Qwen Cloud accepts the standard OpenAI Python SDK with only a swapped base_url, took meaningful time to work through. Once that single insight clicked, everything else unlocked rapidly.
🎭 Preventing agent drift
Without strict prompt design, agents began echoing each other rather than specialising. Keeping each agent's role_prompt narrow, format-constrained, and focused exclusively on its own job — blind to the internal reasoning of other agents — was the discipline that kept five voices genuinely distinct.
Accomplishments That I am Proud Of
- ✅ A fully working five-agent pipeline running end-to-end on Qwen Cloud with a benchmarked quality improvement over single-agent baselines
- ✅ A Critic–Writer negotiation loop with structured scoring, per-dimension feedback, and early exit on approval — a genuine self-correction engine requiring zero human intervention
- ✅ An offline simulator with colour-coded terminal output that makes the agent flow instantly visible and demonstrable to anyone, no API key required
- ✅ A benchmark script that runs identical tasks through single-agent and multi-agent approaches, scores both with an independent evaluator agent, and produces a JSON comparison report as concrete proof of efficiency gain
- ✅ A live FastAPI backend on Alibaba Cloud ECS with OSS log persistence, satisfying all cloud infrastructure requirements
What I Learned
It is better to try and stumble than to stand still and wonder.
Architecture matters more than code. Getting the five-agent structure right — what each agent knows, what it writes to memory, what it reads before responding — was more valuable than any individual function.
System prompts are personalities.
The difference between a Critic that gives vague feedback and one that gives scored, actionable notes is entirely in its role_prompt. Prompt engineering is not a trick. It is character design.
Shared memory is what makes it a society. Without the common whiteboard, agents repeat each other's work. With it, every agent compounds what the previous one discovered. The quality gain lives entirely in that compounding effect.
Failure is the fastest teacher. Every misconfigured API call, every agent that returned nonsense, every simulation that broke mid-flow was a lesson no tutorial could have given. The debugging was frustrating. The learning was irreplaceable.
What's Next for Agent Society
Agent Society in its current form is a foundation. The roadmap is clear:
| Phase | Feature | Impact |
|---|---|---|
| v1.1 | 🌐 Live web search via MCP for the Researcher | Real-time data, not just trained knowledge |
| v1.2 | 🧠 Persistent vector memory across sessions | Society learns and improves over time |
| v2.0 | 👥 User-defined custom agent roles | Legal, medical, financial specialist societies |
| v2.1 | 🔁 Autonomous parallel task chaining | Multiple societies running simultaneously on sub-tasks |
| v3.0 | 🌍 Domain-specific pre-configured societies | Legal Society, Research Society, Marketing Society |
The north star is simple:
$$\text{Agent Society} = \lim_{n \to \infty} \left( \text{one person} + n \text{ expert collaborators} \right)$$
Every person deserves an expert team on demand. Agent Society is how we get there.
The society is ready. The work has just begun.
Log in or sign up for Devpost to join the conversation.