🧪 12-Factor Agents

Collection of AI Agent examples to weigh various framework benefits

A comprehensive monorepo showcasing different AI agent frameworks and their capabilities. Perfect for developers looking to compare LangGraph, hand-rolled solutions, and other agent architectures in production-ready examples.

🚀 Why This Repository?

As AI agent frameworks rapidly evolve in 2025, choosing the right one for your project can be challenging. This repository provides:

• Framework Comparison: Side-by-side implementations using different approaches
• Production Examples: Real-world agent patterns, not just tutorials
• 12-Factor Compliance: Scalable, maintainable architectures following industry best practices
• Performance Insights: Understand the trade-offs between different frameworks

🎯 Quick Start

# Clone the repository
git clone https://github.com/enso-labs/12-factor-agents.git
cd 12-factor-agents

# Update submodules
make update-submodules

# Choose your framework and follow the setup guide below

🏗️ Agent Examples

🌊 LangGraph Agent

Location: examples/langchain/langgraph_agent/

A state-based workflow agent demonstrating LangGraph's graph-based architecture:

• Stateful Workflows: Graph-based execution with conditional routing
• Tool Integration: Weather and stock price APIs with error handling
• Streaming Responses: Real-time output with Redis caching
• Persistence Layer: Built-in memory and fault tolerance

Best For: Complex multi-step tasks requiring precise control and state management

cd examples/langchain/langgraph_agent
uv sync
python src/langgraph_agent/main.py

⚡ Next.js Agent

Location: examples/nextjs/simple-af-agent/

A hand-rolled agent implementation built with Next.js 15 showcasing custom agent logic:

• Streaming UI: Real-time response generation with optimistic updates
• Multi-Tool Execution: Handle multiple API calls in parallel
• Memory Management: XML-based conversation context
• Custom Classification: Intent recognition without heavy frameworks

Best For: High-performance web applications with custom agent requirements

cd examples/nextjs/simple-af-agent
npm install
echo "OPENAI_API_KEY=your_key" > .env.local
npm run dev

🖥️ Terminal Agent

Location: examples/terminal/gilfoyle/

A lightweight CLI agent built with Ink for terminal-based interactions:

• Terminal UI: Rich command-line interface with React components
• Fast Startup: Minimal dependencies for quick agent deployment
• Cross-Platform: Works on Windows, macOS, and Linux

Best For: Developer tools, automation scripts, and lightweight deployments

cd examples/terminal/gilfoyle
npm install
npm start

📊 Framework Comparison

Feature	LangGraph	Next.js (Hand-rolled)	Terminal (Ink)
Learning Curve	High	Medium	Low
Control Level	Precise	Full	Simple
Performance	Medium	High	High
Streaming	✅	✅	⚠️
State Management	Built-in	Custom	Minimal
Tool Integration	Framework	Custom	Basic
Memory/Persistence	Redis/Built-in	XML/Custom	In-memory
Web Interface	❌	✅	❌
CLI Interface	⚠️	❌	✅
Production Ready	✅	✅	⚠️

🛠️ Development Setup

Prerequisites

• Node.js 18+ (for Next.js and Terminal agents)
• Python 3.12+ (for LangGraph agent)
• Redis (for LangGraph persistence)
• OpenAI API Key (for AI functionality)

Development Commands

# Update all submodules
make update-submodules

# Individual project setup
cd examples/[framework]/[project-name]
# Follow framework-specific setup in each directory

🏗️ Architecture Principles

All implementations follow the 12-factor app methodology ensuring:

• 📦 Dependencies: Explicitly declared with lock files (package-lock.json, uv.lock)
• ⚙️ Config: Environment variables for API keys and settings
• 🔌 Backing Services: External APIs treated as attached resources
• 🚀 Processes: Stateless execution with external state management
• 📝 Logs: Structured logging to stdout/stderr
• 🔄 Disposability: Graceful shutdown and fast startup

🎯 When to Use Each Framework

Choose LangGraph when:

• Building complex, multi-step agent workflows
• Need built-in persistence and fault tolerance
• Require sophisticated state management
• Want framework-provided agent abstractions

Choose Hand-rolled (Next.js) when:

• Need maximum performance and control
• Building web-based agent interfaces
• Require custom agent logic not supported by frameworks
• Want to minimize dependencies and framework overhead

Choose Terminal (Ink) when:

• Building developer tools or CLI utilities
• Need lightweight, fast agent deployment
• Targeting terminal-based workflows
• Want simple, focused agent interactions

🚀 Monorepo Structure

12-factor-agents/
├── examples/
│   ├── langchain/
│   │   └── langgraph_agent/     # LangGraph implementation
│   ├── nextjs/
│   │   └── simple-af-agent/     # Next.js hand-rolled agent
│   └── terminal/
│       └── gilfoyle/            # Terminal CLI agent
├── Makefile                     # Monorepo automation
├── .gitmodules                  # Submodule configuration
└── README.md                    # This comprehensive guide

🤝 Contributing

We welcome contributions! Here's how to get started:

🎯 Ways to Contribute

• 📝 Add New Framework Examples: Implement agents using CrewAI, AutoGen, Semantic Kernel, etc.
• 🔧 Improve Existing Examples: Enhance performance, add features, or fix bugs
• 📚 Documentation: Improve setup guides, add tutorials, or create comparison docs
• 🐛 Bug Reports: Find and report issues with clear reproduction steps
• 💡 Feature Requests: Suggest new agent patterns or framework integrations

🚀 Development Workflow

1. Fork the repository and clone your fork
2. Create a feature branch: git checkout -b feature/new-framework-example
3. Develop your changes following our patterns:
   • Follow 12-factor app principles
   • Add comprehensive README for new examples
   • Include setup scripts and clear documentation
4. Test your implementation thoroughly
5. Submit a pull request with detailed description

📋 Guidelines for New Agent Examples

When adding a new framework implementation:

• 📁 Directory Structure: examples/[framework-category]/[project-name]/
• 📝 Documentation: Include comprehensive README with setup instructions
• 🔧 12-Factor Compliance: Follow environment config, dependency management
• 🎯 Feature Parity: Implement similar functionality to existing examples for comparison
• ⚡ Performance: Consider streaming, tool integration, and memory management

💻 Local Development

# Clone your fork
git clone https://github.com/YOUR_USERNAME/12-factor-agents.git
cd 12-factor-agents

# Update submodules
make update-submodules

# Create feature branch
git checkout -b feature/your-feature-name

# Make changes and test
# Submit PR when ready

🌟 Community & Growth

📈 Project Stats

🎉 Recognition

⭐ Star this repo if it helps with your agent development!
🍴 Fork it to create your own agent examples
🔄 Share it with developers exploring AI agent frameworks

🛡️ Environment Variables

Each project uses environment variables for secure configuration:

Variable	Required	Description	Used By
OPENAI_API_KEY	✅	OpenAI API access	All examples
REDIS_URL	⚠️	Redis connection	LangGraph
DEBUG	❌	Enable debug logging	All examples
API_PORT	❌	Custom port binding	Web examples

💡 See individual project READMEs for framework-specific configuration

📚 Resources & Links

🔗 Framework Documentation

• LangGraph Official Docs
• Next.js 15 Documentation
• Ink CLI Framework

📖 Related Reading

• 12-Factor App Methodology
• AI Agent Framework Comparison 2025
• OpenAI Agent SDK

📄 License

This project is open source and available under the Apache 2.0 License.

💬 Support & Community

• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Discussions
• 📧 Questions: Open an issue with the question label

---

Built with ❤️ by the Enso Labs team and amazing contributors