Multi-Agent Architectures Learning Platform

An educational TypeScript project for learning different multi-agent architectures using LangChain and LangGraph. This platform provides hands-on experience with 5 distinct architectural patterns, featuring verbose console output to help students understand how agents interact and coordinate.

Learning Objectives

• Understand different multi-agent coordination patterns
• See how agents spawn, communicate, and complete tasks
• Compare architectural trade-offs (speed vs. quality, simplicity vs. flexibility)
• Learn LangGraph state management and graph construction
• Observe LLM calls, tool usage, and reasoning in real-time

🏗️ Architectures Implemented

1. 🔗 Sequential (Chain)

Pattern: Linear execution where each agent builds on the previous agent's output.

Best For: Tasks with clear sequential dependencies (analyze → process → synthesize)

Key Concept: Fixed execution order with state accumulation

→ View Documentation

---

2. 🔀 Router

Pattern: Classifies input and routes to specialized agents based on task type.

Best For: Diverse requests requiring different expertise (math, text, code)

Key Concept: Conditional routing with specialized agents

→ View Documentation

---

3. ⚡ Parallel

Pattern: Multiple agents execute simultaneously, results are aggregated.

Best For: Independent subtasks that can run concurrently (intro, body, conclusion)

Key Concept: Fan-out/fan-in with concurrent execution

→ View Documentation

---

4. 🔄 Reflection

Pattern: Generator creates content, critic reviews it, iterates until acceptable.

Best For: Tasks requiring quality refinement (writing, code generation)

Key Concept: Cycles in graph for iterative improvement

→ View Documentation

---

5. 📋 Hierarchical

Pattern: Manager coordinates specialized workers, reviews outputs, synthesizes final result.

Best For: Complex tasks requiring multiple specialized skills (research, analysis, writing)

Key Concept: Two-level coordination with central oversight

→ View Documentation

Quick Start

Prerequisites

• Node.js 18+
• npm or yarn
• An API key for at least one LLM provider (OpenAI, Anthropic, or local Ollama)

Installation

# Clone or navigate to the project
cd agents-playground

# Install dependencies
npm install

# Setup environment
cp .env.example .env
# Edit .env and add your API keys

Configuration

Edit .env file:

# Choose your LLM provider
LLM_PROVIDER=openai  # or anthropic, ollama

# Add API key for your provider
OPENAI_API_KEY=your-key-here
# ANTHROPIC_API_KEY=your-key-here
# OLLAMA_BASE_URL=http://localhost:11434

# Logging verbosity
LOG_LEVEL=verbose  # verbose, normal, or minimal

Running the Interactive CLI

npm start

This launches an interactive menu where you can:

1. Select an architecture
2. Enter your task
3. Watch the agents work with verbose logging
4. Compare different architectures on the same task

Educational Features

Verbose Console Logging

Every architecture provides detailed, color-coded output showing:

• 🤖 Agent Spawning: See when agents are created and their roles
• 🧠 LLM Calls: View prompts sent to the LLM and responses received
• 🔧 Tool Usage: Observe when agents use calculator, search, or other tools
• 💭 Reasoning: Follow agent thinking and decision-making
• ⚡ Transitions: Track how control flows between agents
• 🎉 Final Results: See the completed output

Example Output

╔════════════════════════════════════════╗
║   Sequential Architecture              ║
║                                        ║
║   Agents execute in linear order,     ║
║   each building on previous output    ║
╚════════════════════════════════════════╝

┌─ 🤖 Agent Spawned: Analyzer
│  Role: Input Analysis
│  Input: "Write a blog post about TypeScript"

  🧠 LLM Call (gpt-4-turbo-preview)
     Prompt: You are an Analyzer agent...
  ✓ LLM responded
     Response: I'll analyze this task...

└─ ✓ Agent Complete: Analyzer

⚡ Transition: analyzer → processor

Learning Path

For Beginners

1. Start with Sequential - simplest pattern
2. Try Router - adds conditional logic
3. Explore Parallel - introduces concurrency
4. Study Reflection - adds iteration
5. Master Hierarchical - most complex

For Each Architecture

1. Read the architecture's README
2. Review the diagram and flow
3. Run the example with verbose logging
4. Examine the code (nodes.ts and graph.ts)
5. Try different tasks to see how it behaves

Experiments to Try

• Run the same task across all architectures and compare outputs
• Modify max iterations in Reflection (1, 3, 5, 10)
• Add a new specialist to Router (e.g., "science" specialist)
• Create custom tasks that favor certain architectures
• Combine patterns (e.g., Router + Reflection)

Project Structure

agents-playground/
├── src/
│   ├── index.ts                          # Interactive CLI
│   ├── shared/                           # Shared utilities
│   │   ├── config/                       # LLM provider configuration
│   │   ├── logging/                      # Educational console logger
│   │   ├── tools/                        # Calculator & search tools
│   │   └── types/                        # State type definitions
│   └── architectures/                    # Architecture implementations
│       ├── sequential/                   # Chain pattern
│       ├── router/                       # Routing pattern
│       ├── parallel/                     # Concurrent pattern
│       ├── reflection/                   # Iterative pattern
│       └── hierarchical/                 # Manager-worker pattern
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

Each architecture folder contains:

• README.md - Documentation with diagrams and explanations
• nodes.ts - Agent node implementations
• graph.ts - LangGraph workflow definition

Customization

Switching LLM Providers

Simply change LLM_PROVIDER in .env:

• openai - GPT-4, GPT-3.5
• anthropic - Claude models
• ollama - Local models (Llama, Mistral, etc.)

Adjusting Logging Verbosity

In .env:

• verbose - Show everything (default for learning)
• normal - Show key events only
• minimal - Show only final results

Additional Resources

• LangChain Documentation
• LangGraph Concepts
• Multi-Agent Systems
• Plan file with implementation details

Contributing

This is an educational project. Feel free to:

• Add new architectures
• Improve logging and visualization
• Create new example tasks
• Enhance documentation
• Report issues or suggest improvements

License

MIT License - feel free to use for learning and teaching.

What's Next?

After mastering these architectures:

1. Build your own custom architecture
2. Combine patterns for complex workflows
3. Add persistence with LangGraph checkpointing
4. Implement human-in-the-loop patterns
5. Scale to production systems

---

Happy Learning!

This project demonstrates fundamental multi-agent patterns. Each architecture teaches unique concepts that apply to real-world AI systems.