# I Built a Multi-Agent Framework That Does What LangGraph, CrewAI and Swarm Can't

> TL;DR: I open-sourced **Nexus** — a Python framework that unifies three orchestration paradigms (static graph, dynamic router, self-organizing adaptive) with native A2A + MCP protocol support. 5 lines of code to run a multi-agent team. Here's the story of why I built it and what makes it different.

---

## The Problem

I've been building with AI agents for the past year. Here's what I've learned:

**Swarm** is beautiful in its simplicity — 3 primitives, zero abstractions. But try running it in production. No checkpoints. No budget control. No retry logic. One failed API call and your entire pipeline is gone.

**LangGraph** is production-ready — state machines, persistence, the works. But the learning curve is brutal. I spent more time fighting the framework than solving my actual problem.

**CrewAI** makes teams easy to define. But under the hood, you're locked into their orchestration model. When I needed a static pipeline for content creation AND a dynamic router for customer support in the same app? Nope.

**AutoGen** pioneered the space. But the API is... complex. And when I tried to connect my agents to external tools or other agent systems? Protocol mismatch everywhere.

I kept thinking: **Why do I have to choose?**

## The "Aha" Moment

I was reading about Google's A2A protocol and Anthropic's MCP standard, and it clicked:

> What if the framework was built on open protocols from day one? And what if it could switch between orchestration modes — graph, router, or self-organizing — based on the problem?

That's Nexus.

## What Is Nexus?

**Three primitives:**
- `Agent` — An LLM with instructions, tools, and capabilities
- `Task` — A unit of work with full lifecycle management
- `Handoff` — Three patterns: delegate (sub-task), transfer (hand-over), broadcast (fan-out)

**Three orchestration modes:**
- **Graph** — Static DAG when you know the workflow (like LangGraph)
- **Router** — Dynamic routing when you want flexibility (like Swarm)
- **Adaptive** — Self-organizing when agents should figure it out themselves (this is new)

**Two protocols:**
- **A2A** — For agent-to-agent communication across boundaries
- **MCP** — For connecting agents to any tool server

## Show Me the Code

Here's a multi-agent team in 5 lines:

```python
import asyncio
from nexus import Team

async def main():
    async with Team(model="gpt-4o") as team:
        team.add_agent("researcher", instructions="You research topics thoroughly.")
        team.add_agent("writer", instructions="You write engaging articles.")
        result = await team.run("Write a blog post about AI agents")
        print(result)

asyncio.run(main())
```

The router automatically figures out which agent should handle each task.

### But Wait — Graph Mode

Need a fixed pipeline? Switch to graph mode:

```python
graph = GraphOrchestrator()
graph.add_node("research", researcher)
graph.add_node("write", writer)
graph.add_node("review", reviewer)
graph.add_edge("__start__", "research")
graph.add_edge("research", "write")
graph.add_edge("write", "review")
graph.add_edge("review", "__end__")
```

### And Adaptive Mode — The Secret Sauce

This is what I'm most excited about. Agents have **capability vectors**:

```python
team = Team(model="gpt-4o", mode=TopologyMode.ADAPTIVE)

coder = team.add_agent("coder", 
    capabilities=AgentCapability(coding=1.0, reasoning=0.8))
writer = team.add_agent("writer", 
    capabilities=AgentCapability(creativity=1.0, language=0.9))

# The system matches tasks to agents using cosine similarity
# AND tracks performance with ELO-like ratings
await team.run("Implement quicksort")  # → coder
await team.run("Write a haiku")        # → writer
```

Over time, the system learns which agents are good at what. Agents that consistently deliver high quality rise in the rankings. Poor performers get fewer tasks.

## The Production Stuff

This is where most frameworks fall short:

### Durable Execution
```python
engine = ExecutionEngine(
    checkpoint_store=FileCheckpointStore("./checkpoints")
)
# Crash mid-execution? Resume exactly where you left off.
result = await engine.resume_task(task_id="abc123")
```

### Token Budget Control
```python
team = Team(
    model="gpt-4o",
    budget=BudgetConfig(
        max_cost_usd=10.0,
        degradation_strategy="downgrade_model",
    ),
)
# Approaching budget limit? Auto-switch from GPT-4o to GPT-3.5-turbo
```

### Error Recovery Chain
```
Retry (exponential backoff)
  → Fallback (try a different agent)
    → Escalation (loop in a human)
```

### Full Observability
OpenTelemetry-compatible tracing. Per-agent metrics. Token cost tracking. You see everything.

## How It Compares

| | Nexus | Swarm | LangGraph | CrewAI | AutoGen |
|---|---|---|---|---|---|
| Learning curve | Low | Low | High | Medium | High |
| Orchestration modes | 3 | 1 | 1 | 1 | 1 |
| Protocol support | A2A + MCP | — | — | — | — |
| Checkpoint/resume | ✅ | ❌ | ✅ | ❌ | ⚠️ |
| Token budget | ✅ | ❌ | ❌ | ❌ | ❌ |
| Capability matching | ✅ | ❌ | ❌ | ⚠️ | ❌ |
| Multi-provider | ✅ | ❌ | ✅ | ✅ | ✅ |

## What I Learned Building This

1. **Protocols matter more than abstractions.** Building on A2A and MCP means Nexus agents can talk to ANY other agent system, not just Nexus agents.

2. **One topology doesn't fit all.** A content pipeline needs a graph. A customer support system needs a router. A research team needs adaptive self-organization. The framework should support all three.

3. **The "last mile" of agent systems is reliability**, not intelligence. Budget control, checkpointing, retry policies — these boring features are what separate a demo from a product.

## Try It

```bash
pip install nexus-agents[openai]
```

**GitHub**: https://github.com/songtianye/nexus

If you find this useful, I'd really appreciate a ⭐ on GitHub. And I'd love your feedback — what features would make this more useful for your projects?

---

*Nexus is MIT licensed. Use it however you want.*
