Skip to content

Commit aa9ee13

Browse files
author
Lummy
committed
refactor: move FuguAgent to examples/multi_agent/fugu_agent
- Remove FuguAgent from swarms/agents/__init__.py exports - Remove FuguAgent from SwarmType literal and _create_fugu_agent() in swarm_router.py - Move FuguAgent implementation to examples/multi_agent/fugu_agent/ with improvements: - Replace dataclasses with pydantic models (AgentTask, AgentTaskResult, VerificationResult) - Add comprehensive type hints throughout - Add docstrings to all public methods and classes - Add __repr__ methods for debugging - Create example files (example_basic.py, example_with_workers.py) - Update examples/single_agent/fugu_example.py to redirect to new location with deprecation warning - Add README.md with full documentation
1 parent b85e4dc commit aa9ee13

7 files changed

Lines changed: 1201 additions & 0 deletions

File tree

‎PR.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
# FuguAgent: Multi-Agent System as a Single Model
2+
3+
## Description
4+
5+
New `FuguAgent` class (`swarms/agents/fugu.py`) implementing the Fugu/Trinity orchestration pattern — a multi-agent system that presents itself as a single model API.
6+
7+
### Core Architecture
8+
9+
The `FuguAgent` coordinates a pool of worker agents through a dedicated coordinator model using **tool-calling** (not text parsing). At each step the coordinator calls the `decide_next_step` tool, committing to a structured `AgentTask {role, worker, instruction, visibility}`. The result is stored directly via closure capture, bypassing fragile history parsing.
10+
11+
**Key components:**
12+
13+
- **`decide_next_step` tool** — Function-call based orchestration. The coordinator decides role, worker, instruction, and visibility for each step and commits via the tool. No JSON text parsing required.
14+
- **Dynamic roles** — Roles are not hardcoded. The coordinator assigns whichever role fits: `planner`, `researcher`, `coder`, `writer`, `verifier`, `reviewer`, `executor`, `summarizer`, etc.
15+
- **Model capability ranking** — Workers are ranked by `MODEL_TIER` scores. The coordinator's system prompt lists workers by tier, ensuring the most powerful models handle the hardest subtasks.
16+
- **`MemoryStore`** — SQLite-backed persistent memory across turns and sessions.
17+
- **Visibility routing** — Each `AgentTask` specifies which prior step outputs (by index) the worker can see, implementing the Conductor's access-list pattern.
18+
- **Chain-of-thought aggregation** — Final answer synthesized by passing all step outputs through the coordinator.
19+
20+
**Files changed:**
21+
22+
| File | Change |
23+
|------|--------|
24+
| `swarms/agents/fugu.py` | New — core FuguAgent implementation (380 LOC) |
25+
| `swarms/agents/__init__.py` | Added `FuguAgent` export |
26+
| `swarms/structs/swarm_router.py` | Added `"FuguAgent"` to `SwarmType` + `_create_fugu_agent()` |
27+
| `examples/single_agent/fugu_example.py` | New — minimal usage example |
28+
29+
## Architecture
30+
31+
```mermaid
32+
flowchart TD
33+
User(["User Task"]) --> Coordinator
34+
35+
Coordinator -->|"decide_next_step()"| Tool
36+
Tool -->|"AgentTask JSON"| Holder
37+
Holder --> T1
38+
39+
subgraph T1[" "]
40+
direction LR
41+
T2["_decide_holder read"]
42+
end
43+
44+
T2 --> ExecStep["execute_step()"]
45+
ExecStep --> ExRole{role}
46+
ExRole -->|planner / researcher / coder / writer| Execute
47+
ExRole -->|verifier / reviewer| Verify
48+
ExRole -->|any| Context["build visibility context"]
49+
50+
subgraph Worker_Pool["Worker Pool"]
51+
W1["[7] general (gpt-4o)"]
52+
W2["[5] coder (gpt-4o-mini)"]
53+
W3["[5] researcher (claude-sonnet)"]
54+
end
55+
56+
Execute --> Context
57+
Context --> W1
58+
Context --> W2
59+
Context --> W3
60+
61+
W1 --> R1[/Result/]
62+
W2 --> R2[/Result/]
63+
W3 --> R3[/Result/]
64+
65+
R1 --> WS[WorkflowState]
66+
R2 --> WS
67+
R3 --> WS
68+
69+
Verify --> VResult{ver.accept?}
70+
VResult -->|ACCEPT| Done
71+
VResult -->|REVISE| Coordinator
72+
73+
WS --> Aggregator
74+
Done --> Aggregator["coordinator.aggregate()"]
75+
Aggregator --> Final(["Final Answer"])
76+
77+
subgraph Mem["MemoryStore (SQLite)"]
78+
M1["per-turn artifacts"]
79+
M2["session context"]
80+
end
81+
82+
WS -.-> M1
83+
M1 -.-> M2
84+
```
85+
86+
### Execution Loop
87+
88+
```mermaid
89+
sequenceDiagram
90+
participant User
91+
participant Coord as Coordinator
92+
participant Tool
93+
participant Fugu
94+
participant Worker
95+
participant Verifier
96+
97+
User->>Fugu: run(task)
98+
99+
loop max_turns
100+
Fugu->>Coord: coordinator.run(history_ctx + memory)
101+
Coord->>Tool: decide_next_step(role, worker, instruction, visibility)
102+
Tool->>Tool: store task in _decide_holder
103+
Tool-->>Coord: AgentTask JSON
104+
Coord-->>Fugu: run() returns
105+
106+
Fugu->>Fugu: agent_task = _decide_holder.pop()
107+
108+
alt agent_task.role in verifier / reviewer
109+
Fugu->>Verifier: run(accumulated_work)
110+
Verifier-->>Fugu: ACCEPT or REVISE + diagnosis
111+
Fugu->>Fugu: if accept: break
112+
else
113+
Fugu->>Worker: run(instruction + visibility_context)
114+
Worker-->>Fugu: result
115+
end
116+
117+
Fugu->>Fugu: WorkflowState.results.append()
118+
Fugu->>Fugu: MemoryStore.save(turn)
119+
end
120+
121+
Fugu->>Coord: coordinator.run(synthesis_prompt)
122+
Coord-->>Fugu: Final Answer
123+
Fugu-->>User: Final Answer
124+
```
125+
126+
## Usage
127+
128+
```python
129+
from swarms import FuguAgent
130+
131+
agent = FuguAgent(
132+
coordinator_model="gpt-4o-mini",
133+
max_turns=5,
134+
verbose=True,
135+
)
136+
137+
result = agent.run("Write a short story about a robot discovering music.")
138+
```
139+
140+
Workers are auto-detected from `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `GOOGLE_API_KEY`, or can be passed explicitly:
141+
142+
```python
143+
from swarms import FuguAgent, Agent
144+
145+
agent = FuguAgent(
146+
workers=[
147+
Agent(agent_name="coder", model_name="gpt-4o"),
148+
Agent(agent_name="researcher", model_name="claude-sonnet-4-5"),
149+
],
150+
max_turns=5,
151+
)
152+
```
153+
154+
Also available via `SwarmRouter`:
155+
156+
```python
157+
from swarms import SwarmRouter, Agent
158+
159+
router = SwarmRouter(
160+
agents=[Agent(agent_name="a", model_name="gpt-4o"), Agent(agent_name="b", model_name="claude-sonnet-4-5")],
161+
swarm_type="FuguAgent",
162+
max_loops=5,
163+
)
164+
result = router.run("Write a story about a robot.")
165+
```
166+
167+
## Issue
168+
169+
N/A — new feature.
170+
171+
## Dependencies
172+
173+
None beyond existing swarms dependencies. No new packages required.
174+
175+
## Tag Maintainer
176+
177+
kye@swarms.world
178+
179+
## Twitter Handle
180+
181+
N/A

‎examples/multi_agent/fugu_agent/README.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# FuguAgent
2+
3+
A multi-agent orchestration system that behaves like a single model API.
4+
5+
## Overview
6+
7+
FuguAgent implements the **Fugu/Trinity pattern** — a multi-agent system that presents itself as a single model API. A dedicated coordinator model dynamically assigns tasks to a ranked pool of worker agents using **tool-calling** (not text parsing).
8+
9+
## Architecture
10+
11+
```
12+
User Task --> Coordinator --> decide_next_step() tool --> AgentTask {role, worker, instruction, visibility}
13+
|
14+
v
15+
+------------------+
16+
| Worker Execution |
17+
+------------------+
18+
|
19+
v
20+
WorkflowState
21+
+ MemoryStore
22+
|
23+
v
24+
Aggregation
25+
|
26+
v
27+
Final Answer
28+
```
29+
30+
## Key Features
31+
32+
- **Tool-calling orchestration**: The coordinator commits to structured AgentTasks via tool calls, not fragile text parsing
33+
- **Dynamic roles**: Roles are not hardcoded — coordinator assigns whichever fits: planner, coder, researcher, writer, verifier, reviewer, etc.
34+
- **Model capability ranking**: Workers ranked by MODEL_TIER scores; hardest tasks assigned to most capable models
35+
- **SQLite persistent memory**: Task artifacts and metadata persist across turns and sessions
36+
- **Visibility routing**: Each AgentTask specifies which prior step outputs the worker can see
37+
38+
## Installation
39+
40+
FuguAgent is part of the swarms package and requires API keys for the models you want to use.
41+
42+
Set environment variables:
43+
```bash
44+
export OPENAI_API_KEY="sk-..."
45+
export ANTHROPIC_API_KEY="sk-ant-..."
46+
export GOOGLE_API_KEY="..."
47+
```
48+
49+
## Quick Start
50+
51+
### Auto-detect models (simplest)
52+
53+
```python
54+
from examples.multi_agent.fugu_agent import FuguAgent
55+
56+
agent = FuguAgent(
57+
coordinator_model="gpt-4o-mini",
58+
max_turns=5,
59+
verbose=True,
60+
)
61+
62+
result = agent.run("Write a short story about AI discovering music.")
63+
```
64+
65+
### With explicit workers
66+
67+
```python
68+
from swarms import Agent
69+
from examples.multi_agent.fugu_agent import FuguAgent
70+
71+
workers = [
72+
Agent(agent_name="coder", model_name="gpt-4o", max_loops=1),
73+
Agent(agent_name="researcher", model_name="claude-sonnet-4-5", max_loops=1),
74+
Agent(agent_name="writer", model_name="gpt-4o-mini", max_loops=1),
75+
]
76+
77+
agent = FuguAgent(
78+
coordinator_model="gpt-4o-mini",
79+
workers=workers,
80+
max_turns=5,
81+
)
82+
83+
result = agent.run("Research, write, and review an article about quantum computing.")
84+
```
85+
86+
## Configuration Options
87+
88+
| Parameter | Type | Default | Description |
89+
|-----------|------|---------|-------------|
90+
| `coordinator_model` | str | `"gpt-4o-mini"` | Model for the coordinator agent |
91+
| `workers` | list[Agent] | `None` | Explicit worker agents |
92+
| `worker_models` | list[str] | `None` | Model names to auto-create workers |
93+
| `max_turns` | int | `5` | Maximum workflow turns before terminating |
94+
| `confidence_threshold` | float | `0.85` | Min confidence for verification acceptance |
95+
| `verbose` | bool | `False` | Enable verbose output |
96+
| `memory_db_path` | str | `None` | Custom path for SQLite memory database |
97+
98+
## How It Works
99+
100+
1. **Coordinator decides**: The coordinator receives the original task, history, and memory context, then calls `decide_next_step` tool to assign a role/worker/instruction
101+
2. **Worker executes**: The assigned worker runs with visibility into relevant prior outputs
102+
3. **Verification**: Special roles like "verifier" or "reviewer" trigger built-in verification against accumulated work
103+
4. **Aggregation**: After max_turns or acceptance, coordinator synthesizes all step outputs into a final answer
104+
105+
## Model Tiers
106+
107+
Workers are automatically ranked by capability:
108+
109+
| Tier | Models |
110+
|------|--------|
111+
| 10 | GPT-5, o3, o4 |
112+
| 9 | Claude Opus 4/3, Gemini 3 Ultra |
113+
| 8 | Claude Sonnet 4-5, Gemini 3 Pro, Llama 4 405B |
114+
| 7 | Claude Sonnet 3-5, Gemini 2.5 Pro, GPT-4o |
115+
| 6 | Gemini 2.5 Flash, GPT-4 Turbo, Llama 4 70B, DeepSeek R1/V3 |
116+
| 5 | Gemini 2.0 Flash, GPT-4o-mini, Qwen 3 32B, DeepSeek R1 |
117+
| 4 | GPT-4, Qwen 3 8B, Llama 4 8b, Gemma 3 12B |
118+
| 3 | GPT-3.5 Turbo (and below) |
119+
120+
## Files
121+
122+
- `fugu_agent.py` — Core implementation with pydantic models and type hints
123+
- `example_basic.py` — Minimal usage with auto-detected models
124+
- `example_with_workers.py` — With explicit worker configuration
125+
126+
## Testing
127+
128+
Run examples directly:
129+
```bash
130+
python example_basic.py
131+
python example_with_workers.py
132+
```
133+
134+
## License
135+
136+
Part of the swarms package.

‎examples/multi_agent/fugu_agent/__init__.py‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
"""
2+
FuguAgent: A multi-agent orchestration system that behaves like a single model API.
3+
4+
This module implements the Fugu/Trinity pattern where a dedicated coordinator
5+
model dynamically assigns tasks to a ranked pool of worker agents using tool-calling.
6+
"""
7+
8+
from examples.multi_agent.fugu_agent.fugu_agent import (
9+
FuguAgent,
10+
AgentTask,
11+
AgentTaskResult,
12+
VerificationResult,
13+
WorkflowState,
14+
MemoryStore,
15+
MODEL_TIER,
16+
_model_tier,
17+
_detect_models,
18+
_rank_workers,
19+
_make_decide_tool,
20+
_build_coordinator_system_prompt,
21+
)
22+
23+
__all__ = [
24+
"FuguAgent",
25+
"AgentTask",
26+
"AgentTaskResult",
27+
"VerificationResult",
28+
"WorkflowState",
29+
"MemoryStore",
30+
"MODEL_TIER",
31+
"_model_tier",
32+
"_detect_models",
33+
"_rank_workers",
34+
"_make_decide_tool",
35+
"_build_coordinator_system_prompt",
36+
]

‎examples/multi_agent/fugu_agent/example_basic.py‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
"""
2+
Basic FuguAgent usage example.
3+
4+
This example demonstrates minimal FuguAgent usage with auto-detected API keys.
5+
The agent will automatically detect OPENAI_API_KEY, ANTHROPIC_API_KEY, or
6+
GOOGLE_API_KEY and build a worker pool from available models.
7+
8+
Usage:
9+
python example_basic.py
10+
"""
11+
12+
from dotenv import load_dotenv
13+
14+
from examples.multi_agent.fugu_agent import FuguAgent
15+
16+
load_dotenv()
17+
18+
19+
def main() -> None:
20+
"""Run a simple FuguAgent task."""
21+
agent = FuguAgent(
22+
coordinator_model="gpt-4o-mini",
23+
max_turns=5,
24+
verbose=True,
25+
)
26+
27+
result = agent.run(
28+
"How to solve Turing's halting problem?"
29+
)
30+
print("\n=== Final Answer ===")
31+
print(result)
32+
33+
34+
if __name__ == "__main__":
35+
main()

0 commit comments

Comments
 (0)