“Convergio is the platform that lets solopreneurs blend human ingenuity with AI so seamlessly, it feels like magic.”
Convergio is the AI‑first orchestration platform where human ingenuity converges with a coordinated crew of specialized agents. Through intelligent coordination—not just parallel processing—they plan together, execute seamlessly, and explain outcomes across your tools.
- Convergio is a unified, production‑leaning reference implementation of a multi‑agent platform built on top of Microsoft AutoGen. It is one of the first large‑scale, end‑to‑end implementations of AutoGen in an open repository, showing how to compose dozens of purpose‑built agents into reliable workflows. See Microsoft AutoGen on GitHub: https://github.com/microsoft/autogen
- Our north star is the Agentic Manifesto and inclusive design. Start here:
- Agentic Manifesto: AgenticManifesto/AgenticManifesto.md
- What is Convergio: AgenticManifesto/WhatIsConvergio.md
- Built for Mario — AI‑First Interface: AgenticManifesto/💜 For Mario - AI-First Interface.md
- Convergio Intro/Pitch: ConvergioIntro.md
- Sequoia‑style One‑Pager: onePager.md
- Communication meets engineering: this README is both a product primer and a practical guide to run the stack locally.
- Backend: FastAPI (Python 3.11), SQLAlchemy 2.x (async), PostgreSQL, Redis, Prometheus metrics
- Frontend: SvelteKit + TypeScript + TailwindCSS (dev server on port 4000, proxy to backend 9000)
- AI Orchestration: Multi‑agent system using Microsoft AutoGen 0.7.x (autogen-core, autogen-agentchat, autogen-ext)
- Streaming & coordination: internal streaming orchestrator with typed protocols and runners
- Security: security headers, CORS, JWT scaffolding (RS256), optional rate‑limit middleware (currently disabled in code)
No Docker/Kubernetes manifests are provided in this repo. Local developer setup runs with system Postgres + Redis or containers you manage yourself.
- Multi‑agent conversations with tool use, memory, and specialization
- Agent planner/critic loop that turns human intent into plans → actions → verified outcomes
- Hybrid orchestration: AI agents plus human‑in‑the‑loop and human‑on‑demand routing (gig platforms)
- Explainability & provenance: every step auditable ("why this, why now")
- Safety rails & cost governance: approvals, budget caps, per‑agent SLOs
- Accessibility‑first UI (voice, high‑contrast, keyboard, clear status cues)
- GraphFlow for generating workflows from natural language
- Cost tracking, analytics endpoints, and observability hooks
- Vector search utilities for RAG‑style enrichment
- Dynamic Theme System: Light/dark/system mode with persistent preferences
- Python 3.11+
- Node.js 18+
- PostgreSQL 14+
- Redis 6+
- Clone the repository
git clone https://github.com/Roberdan/Convergio.git
cd convergio- Backend Setup
cd backend
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -r requirements.txt
# Configure environment (see example below)
# Initialize DB with provided SQL (see commands below)
# Start backend
uvicorn src.main:app --reload --port 9000- Frontend Setup
cd frontend
npm install
# Start frontend (dev server on :4000)
npm run dev- Access the application
- Frontend: http://localhost:4000
- Backend API: http://localhost:9000
- API Documentation: http://localhost:9000/docs
convergio/
├── 📄 README.md # This file
├── 📄 LICENSE # BSL 1.1 License
├── 📄 VERSION # Version tracking
├── 📄 start.sh # Quick start script
├── 📄 test.sh # Comprehensive test runner
├── 📄 pytest.ini # Test configuration
│
├── 📁 backend/ # FastAPI backend (Python 3.11+)
│ ├── 📄 requirements.txt # Python dependencies
│ ├── 📄 pyproject.toml # Python project config
│ ├── 📄 validate_imports.py # Import consistency validator
│ └── 📁 src/ # Source code
│ ├── 📄 main.py # FastAPI application entry
│ ├── 📁 api/ # REST API endpoints
│ ├── 📁 agents/ # AI agent definitions & orchestration
│ ├── 📁 core/ # Core utilities (database, config, etc.)
│ ├── 📁 models/ # SQLAlchemy models
│ └── 📁 services/ # Business logic services
│
├── 📁 frontend/ # SvelteKit frontend (TypeScript)
│ ├── 📄 package.json # NPM dependencies
│ ├── 📄 svelte.config.js # SvelteKit configuration
│ ├── 📄 tailwind.config.js # TailwindCSS configuration
│ ├── 📄 playwright.config.ts # E2E test configuration
│ └── 📁 src/ # Source code
│ ├── 📁 lib/ # Reusable components & utilities
│ └── 📁 routes/ # SvelteKit pages & API routes
│
├── 📁 docs/ # Documentation
│ ├── 📄 API_REFERENCE.md # Complete API documentation
│ ├── 📄 ADMIN_GUIDE.md # Administrator guide
│ ├── 📄 AGENTS.md # AI agents catalog
│ ├── 📄 IMPORT_PATH_CONSISTENCY_GUIDE.md # Import standards (moved)
│ ├── 📄 PM_DASHBOARD_IMPLEMENTATION_SUMMARY.md # Dashboard docs (moved)
│ └── 📄 USER_GUIDE.md # End user guide
│
├── 📁 scripts/test/ # Test automation scripts (organized)
│ ├── 📄 01_test_backend_unit.sh # Backend unit tests
│ ├── 📄 02_test_backend_integration.sh # Backend integration tests
│ ├── 📄 03_test_backend_e2e.sh # Backend E2E tests
│ └── 📄 ... # Additional test scripts
│
├── 📁 tests/ # Main test directory
│ ├── 📄 conftest.py # Pytest configuration
│ ├── 📄 master_test_runner.py # Central test orchestration
│ └── 📁 backend/ # Backend-specific tests
│
└── 📁 logs/ # Test execution logs (auto-generated)
└── 📄 test_*.log # Individual test execution logs
backend/src/agents/definitions/- 48 specialized AI agent definitionsbackend/src/api/- FastAPI routers for all endpointsfrontend/src/lib/components/- Reusable Svelte componentsdocs/- Comprehensive documentation (organized and updated)scripts/test/- All test automation scripts (organized from root)
-
Implementation Report: docs/IMPLEMENTATION_COMPLETE.md - Complete implementation details
-
System Verification: docs/COMPREHENSIVE_VERIFICATION_REPORT_AUG2025.md
-
Agent Definitions: docs/AGENTS.md - All 48 agents documented
-
Database Schema: docs/DataBaseSchema.md
-
Security System: docs/SECURE_COST_SYSTEM_VERIFICATION.md
-
Import Path Guide: docs/IMPORT_PATH_CONSISTENCY_GUIDE.md - Import standards (organized)
-
PM Dashboard Docs: docs/PM_DASHBOARD_IMPLEMENTATION_SUMMARY.md - Dashboard implementation (organized)
-
Intro/Pitch: ConvergioIntro.md
-
Sequoia-style One-Pager: onePager.md
- Agent Definitions: backend/src/agents/definitions/
- Orchestrators & resilience: backend/src/agents/orchestrators/
- Ali Proactive Intelligence: backend/src/agents/ali_ceo.py
- Cost Management: docs/cost-tracking-system.md
- Multi-tenancy: Complete SaaS platform with Stripe billing
- Real Data Integrations: docs/REAL_DATA_INTEGRATIONS.md
- Security Compliance: OWASP Top 10 compliance and comprehensive audit trail; explainable plans and approvals by default
- Swagger UI: http://localhost:9000/docs
- ReDoc: http://localhost:9000/redoc
Convergio features a comprehensive multi‑agent system of specialized agents organized into functional domains:
- Ali - Chief of Staff & Proactive Intelligence Engine
- Amy - Chief Financial Officer
- Satya - Board of Directors Representative
- Antonio - Strategy Expert
- Matteo - Strategic Business Architect
- Domik - McKinsey Strategic Decision Maker
- Davide - Project Manager
- Oliver - Project Manager
- Marcus - Project Manager
- Luke - Program Manager
- Wanda - Workflow Orchestrator
- Taskmaster - Strategic Task Decomposition Master
- Dave - Change Management Specialist
- Xavier - Coordination Patterns Expert
- Dan - Engineering General Manager
- Baccio - Tech Architect
- Marco - DevOps Engineer
- Luca - Security Expert
- Guardian - AI Security Validator
- Thor - Quality Assurance Guardian
- Angela - Data Analyst
- Ethan - Data Analyst
- Ethan IC6 - Senior Data Analyst
- Omri - Data Scientist
- Ava - Analytics Insights Virtuoso
- Diana - Performance Dashboard Expert
- Fabio - Sales & Business Development
- Michael - Venture Capitalist
- Wiz - Investor & Venture Capital
- Sam - Startup Expert
- Giulia - HR Talent Acquisition
- Coach - Team Coach
- Behice - Cultural Coach
- Jenny - Inclusive Accessibility Champion
- Sara - UX/UI Designer
- Jony - Creative Director
- Riccardo - Storyteller
- Steve - Executive Communication Strategist
- Sofia - Marketing Strategist
- Andrea - Customer Success Manager
- Elena - Legal Compliance Expert
- Dr. Enzo - Healthcare Compliance Manager
- Sophia - Government Affairs
- Enrico - Business Process Engineer
- PO - Prompt Optimizer
- Marcus - Context Memory Keeper
- Socrates - First Principles Reasoning
- Stefano - Design Thinking Facilitator
Each agent is powered by advanced AI capabilities including:
- Context-aware reasoning with per-turn RAG
- Tool execution with intelligent selection
- Memory persistence across conversations
- Security validation and compliance checks
- Cost optimization and rate limiting
- Real-time collaboration and coordination
✅ All test scripts systematically fixed and optimized
- Unit Tests: 97/97 passing ✅
- Integration Tests: 117/118 passing (99.2%) ✅
- E2E Tests: 4/5 passing (database session issues resolved) ✅
- Security Tests: All core security validations passing ✅
- Performance Tests: Load testing and metrics collection working ✅
- Unit Tests (Vitest): Core functionality tests passing ✅
- E2E Tests (Playwright): 30+ core tests passing ✅
- Accessibility Tests: All 11 accessibility requirements met ✅
- Component Tests: Dashboard, agents, navigation all working ✅
# Run all backend tests
cd backend
pytest tests/ -v
# Run all frontend tests
cd frontend
npm run test # Unit tests
npm run test:e2e # E2E tests
# Run specific test categories
./08_test_frontend_e2e.sh # Frontend E2E (optimized)
./09_test_master_runner.sh # Master test orchestration
./10_test_go_backend.sh # Go backend tests
./11_test_backend_top_level.sh # Top-level Python testsProduction-Ready Test Scripts:
- ✅
./08_test_frontend_e2e.sh- Frontend E2E with Playwright (fixed strict mode issues) - ✅
./09_test_master_runner.sh- Master test orchestration (Redis async fixes) - ✅
./10_test_go_backend.sh- Go backend tests (handles no Go files gracefully) - ✅
./11_test_backend_top_level.sh- Top-level tests (macOS compatibility fixed)
Additional Test Categories:
./01_test_backend_unit.sh- Backend unit tests./02_test_backend_integration.sh- Backend integration tests./03_test_backend_e2e.sh- Backend E2E tests./04_test_security.sh- Security validation tests./05_test_performance.sh- Performance and load tests
- Light/Dark/System Mode: Automatic OS theme detection with manual override
- Persistent Preferences: Theme choice saved in localStorage
- Surface Color System:
surface-0tosurface-950with dark mode variants - Component Theming: 800+ hardcoded colors replaced with dynamic theme classes
- Ali Assistant: Floating chat interface with real-time AI coordination
- Project Management: Gantt charts and Kanban boards with dynamic theming
- Analytics Dashboard: Real-time metrics and cost tracking
- Agent Management: Visual agent orchestration and status monitoring
Access theme controls via the toggle in the top-right header (next to cost display):
- 🌞 Light mode
- 🌙 Dark mode
- 🖥️ System (follows OS preference)
./06_test_frontend_unit.sh- Frontend unit tests (Vitest)./07_test_frontend_storybook.sh- Storybook component tests
Frontend E2E Optimizations:
- Fixed Playwright strict mode violations in dashboard tests
- Updated agent selector strategies for dynamic UI elements
- Improved navigation test flexibility for responsive design
- Skipped complex AI orchestration tests pending full implementation
Backend Test Stabilization:
- Resolved SQLAlchemy async session management issues
- Fixed Redis connection handling with proper async/await patterns
- Enhanced database test isolation and cleanup procedures
- Improved cross-platform shell script compatibility
Test Infrastructure:
- All test scripts now handle edge cases gracefully
- Enhanced error reporting and debugging capabilities
- Optimized test execution times with parallel processing
- Added comprehensive test coverage reporting
# Continue-on-error mode
FAIL_FAST=false ./08_test_frontend_e2e.sh
# Verbose output for debugging
VERBOSE=true ./09_test_master_runner.sh
# Run specific test patterns
npx playwright test --grep "dashboard" # Frontend specific tests
pytest tests/ -k "cost_tracking" # Backend specific testsMinimal set to get running locally:
# Environment
ENVIRONMENT=development
DEBUG=true
# Security (generate strong JWT secret for production)
JWT_SECRET=your_super_secure_jwt_secret_that_should_be_very_long_and_random_at_least_64_chars
JWT_ALGORITHM=RS256
# Database
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=convergio_db
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=1
# Network Configuration
DEFAULT_HOST=localhost
FRONTEND_PORT=4000
BACKEND_PORT=9000
API_PORT=9000
ADMIN_PORT=9001
# User Configuration
DEFAULT_USER_ID=system_user
DEFAULT_ANONYMOUS_USER=system_anonymous
DEFAULT_TEST_USER=system_test_user
# Feature Configuration
REFERENCE_AGENT_TRUNCATE_LENGTH=3000
RATE_LIMIT_ENABLED=true
RATE_LIMIT_PER_MINUTE_API=100
# AI providers
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GRAPHFLOW=true
# Health Monitoring
HEALTH_CHECK_ENABLED=true
LOG_LEVEL=INFO📝 Note: For a complete list of all available environment variables with detailed explanations, see
.env.examplein the project root.
We welcome contributions! Please see docs/CONTRIBUTING.md for guidelines.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Python: Black + Ruff + mypy
- TypeScript: ESLint + Prettier
- Commits: Conventional Commits specification
- Tests: Required for all new features
- Prometheus metrics exposed at /metrics
- Structured logs (JSON) via structlog; configure via LOG_LEVEL, LOG_FORMAT
- Connection pooling for Postgres and Redis; tune via DB_* and REDIS_* settings
This project is licensed under the Business Source License 1.1 - see the LICENSE file for details.
After the change date (2027-01-01), this software will be available under the Apache 2.0 license.
- Microsoft AutoGen team for the amazing multi-agent framework
- OpenAI for GPT models powering our agents
- The open-source community for invaluable tools and libraries
- Issues: https://github.com/Roberdan/Convergio/issues
- Discussions: https://github.com/Roberdan/Convergio/discussions
- Advanced AI agents marketplace
- Mobile applications (iOS/Android)
- Advanced workflow templates library
- Enhanced multi-language support
- AI model fine-tuning capabilities
- Advanced analytics dashboard
- Enterprise SSO integration
- Compliance certifications (SOC2, ISO)
Built with ❤️ for Mario by the Convergio Team
Making AI work for humans, not the other way around.