{"id":47808271,"url":"https://github.com/zloeber/ai-agent-mixer","last_synced_at":"2026-04-03T17:56:38.168Z","repository":{"id":325360998,"uuid":"1100880707","full_name":"zloeber/ai-agent-mixer","owner":"zloeber","description":"A web-based platform for designing, executing, and monitoring structured conversations between two configurable AI agents. Built on LangGraph and Ollama, it enables developers and researchers to simulate multi-agent interactions, test persona behaviors, and validate tool integrations through a unified YAML-driven configuration system.","archived":false,"fork":false,"pushed_at":"2025-11-20T22:53:34.000Z","size":34394,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-21T00:15:03.369Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zloeber.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-20T22:15:38.000Z","updated_at":"2025-11-20T22:39:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zloeber/ai-agent-mixer","commit_stats":null,"previous_names":["zloeber/ai-agent-mixer"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/zloeber/ai-agent-mixer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zloeber%2Fai-agent-mixer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zloeber%2Fai-agent-mixer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zloeber%2Fai-agent-mixer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zloeber%2Fai-agent-mixer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zloeber","download_url":"https://codeload.github.com/zloeber/ai-agent-mixer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zloeber%2Fai-agent-mixer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31367749,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T17:53:18.093Z","status":"ssl_error","status_checked_at":"2026-04-03T17:53:17.617Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-03T17:56:37.283Z","updated_at":"2026-04-03T17:56:38.121Z","avatar_url":"https://github.com/zloeber.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI Agent Mixer - Synthetic AI Conversation Orchestrator \n\n[![Phase 1](https://img.shields.io/badge/Phase%201-Complete-brightgreen.svg)](docs/PHASE1_COMPLETE.md)\n[![Phase 2](https://img.shields.io/badge/Phase%202-Complete-brightgreen.svg)](PHASE2_SUMMARY.md)\n[![Backend](https://img.shields.io/badge/Backend-FastAPI-009688.svg)](backend/)\n[![Frontend](https://img.shields.io/badge/Frontend-React%2BTypeScript-61DAFB.svg)](frontend/)\n[![Tests](https://img.shields.io/badge/Tests-91%20passing-brightgreen.svg)](backend/tests/)\n\nA web-based platform for designing, executing, and monitoring structured conversations between configurable AI agents. Built on LangGraph and Ollama, it enables multi-agent interaction experiments, persona testing, and tool integration validation through declarative YAML configuration.\n\n## ✨ Key Features\n\n- 🤖 **Multi-Agent Orchestration**: Structured turn-taking with configurable termination conditions\n- 🎭 **Dynamic Personas**: Custom system prompts and behavioral constraints per agent\n- 🔧 **MCP Tool Integration**: Global and agent-scoped external capabilities via Model Context Protocol\n- 💭 **Thought Isolation**: Separate internal reasoning from external responses\n- 📊 **Real-Time Observability**: WebSocket streaming of thoughts, responses, and execution telemetry\n- 📝 **YAML Configuration**: Version-controlled, declarative conversation definitions\n- 🐳 **Docker Ready**: Production containerization with health checks and monitoring\n- 📈 **Prometheus Metrics**: Built-in observability for monitoring and alerting\n\n## 🚀 Quick Start (5 minutes)\n\n### Prerequisites\n\n- **Python 3.11+** (for backend)\n- **Node.js 18+** (for frontend)\n- **Ollama** running locally or remotely ([Install Ollama](https://ollama.ai/download))\n- Ollama models pulled: `ollama pull llama2` and `ollama pull mistral`\n\n### Option 1: Local Development\n\n```bash\n# 1. Clone repository\ngit clone https://github.com/zloeber/ai-agent-mixer.git\ncd ai-agent-mixer\n\n# 2. Start backend\ncd backend\npip install -e \".[dev]\"\nuvicorn app.main:app --reload --host 0.0.0.0 --port 8000\n\n# 3. Start frontend (new terminal)\ncd ../frontend\nnpm install\nnpm run dev\n\n# 4. Open browser\n# Frontend: http://localhost:5173\n# API Docs: http://localhost:8000/docs\n```\n\n### Option 2: Docker Compose\n\n```bash\n# 1. Set environment variables (if using MCP tools)\nexport BRAVE_API_KEY=\"your-api-key\"  # Optional\n\n# 2. Start all services\ndocker-compose up --build\n\n# 3. Open browser\n# Frontend: http://localhost:3000\n# Backend: http://localhost:8000\n```\n\n## 📖 First Conversation\n\n1. **Load Example Configuration**\n   - Click \"Import Config\" in the UI\n   - Select `config/example-simple.yaml`\n   - Or upload via API: `curl -F \"file=@config/example-simple.yaml\" http://localhost:8000/api/config/upload`\n\n2. **Verify Configuration**\n   - Check \"Configuration\" panel shows 2 agents\n   - Verify Ollama connections: Green indicators for both agents\n\n3. **Start Conversation**\n   - Click \"Start Conversation\"\n   - Watch real-time messages in center panel\n   - Monitor agent thoughts in left/right consoles (if `thinking: true`)\n\n4. **Export Results**\n   - Click \"Export Conversation\" to save as Markdown\n   - View metrics at `http://localhost:8000/metrics`\n\n## 📚 Documentation\n\n- **[Architecture Overview](docs/architecture.md)** - System design, components, and data flow\n- **[Configuration Guide](docs/configuration-guide.md)** - Complete YAML reference with examples\n- **[API Reference](docs/api.md)** - REST and WebSocket endpoint documentation\n- **[Development Guides](docs/)** - Phase summaries and implementation details\n\n## 🎯 Example Configurations\n\n### Simple Two-Agent Conversation\n```yaml\n# config/example-simple.yaml\nversion: \"1.0\"\nconversation:\n  starting_agent: \"agent_a\"\n  max_cycles: 5\nagents:\n  agent_a:\n    name: \"Agent A\"\n    persona: \"You are friendly and curious.\"\n    model:\n      url: \"http://localhost:11434\"\n      model_name: \"llama2\"\n  agent_b:\n    name: \"Agent B\"\n    persona: \"You are knowledgeable and patient.\"\n    model:\n      url: \"http://localhost:11434\"\n      model_name: \"llama2\"\ninitialization:\n  first_message: \"Hello! Let's discuss artificial intelligence.\"\n```\n\nMore examples in `config/` directory:\n- `philosophy-debate.yaml` - Socratic dialogue between philosophers\n- `tool-using-agents.yaml` - Research agents with MCP tools\n- `example-with-mcp-placeholder.yaml` - Full MCP integration example\n\n## 🛠️ Development\n\n### Running Tests\n\n```bash\ncd backend\npytest tests/ -v                      # Run all tests (91 tests)\npytest tests/test_config_manager.py   # Config tests (38 tests)\npytest tests/test_conversation_flow.py # Integration tests (26 tests)\npytest --cov=app --cov-report=term   # With coverage\n```\n\n### Code Quality\n\n```bash\n# Linting\nruff check app/\nblack app/ --check\n\n# Type checking\nmypy app/\n```\n\n### Building Docker Images\n\n```bash\n# Backend\ndocker build -t ai-agent-mixer-backend:latest ./backend\n\n# Frontend\ndocker build -t ai-agent-mixer-frontend:latest ./frontend\n```\n\n## Project Overview\n\n**Synthetic AI Conversation Orchestrator** is a web-based platform for designing, executing, and monitoring structured conversations between two configurable AI agents. Built on LangGraph and Ollama, it enables developers and researchers to simulate multi-agent interactions, test persona behaviors, and validate tool integrations through a unified YAML-driven configuration system.\n\n---\n\n## Core Purpose\n\n### Problem Statement\nModern AI development lacks a standardized environment for orchestrating and observing synthetic conversations between autonomous agents. Testing agent behaviors, comparing model performance, and validating tool-use patterns requires manual scripting and ad-hoc monitoring, making reproducible experiments and systematic debugging impractical.\n\n### Solution\nProvide a turnkey platform that transforms conversation design into declarative configuration, enabling:\n- **Rapid Prototyping**: Launch complex agent interactions with a single YAML file\n- **Observable Execution**: Real-time visibility into internal reasoning vs. external responses\n- **Reproducible Research**: Version-controlled conversation definitions with deterministic execution\n- **Tool Integration**: Seamless MCP server support for both global and agent-scoped tools\n\n---\n\n## Technical Architecture\n\n### Platform Stack\n- **Backend**: FastAPI + Python 3.11 orchestrating LangGraph state machines\n- **Agent Framework**: LangGraph for conversation flow management, LangChain for LLM abstraction\n- **LLM Integration**: Ollama with dynamic endpoint configuration per agent\n- **Tool Protocol**: Model Context Protocol (MCP) for standardized tool access\n- **Frontend**: React 18 + TypeScript + WebSockets for real-time streaming\n- **Configuration**: Pydantic-validated YAML with environment variable substitution\n\n### Key Design Principles\n1. **Separation of Concerns**: Agent logic, orchestration, and presentation are independently testable\n2. **State-Driven**: LangGraph checkpoint system ensures conversation state is always recoverable\n3. **Streaming-First**: Real-time token streaming for both thoughts and responses minimizes latency\n4. **Configuration as Code**: Entire conversation topology is exportable as a single YAML artifact\n\n---\n\n## Primary Capabilities\n\n### Multi-Agent Orchestration\n- **Turn-Based Conversations**: Strict cycle counting with configurable termination conditions\n- **Dynamic Personas**: Per-agent system prompts and behavioral constraints\n- **Model Flexibility**: Each agent connects to independent Ollama instances/models\n- **Starting Agent Control**: Explicit configuration of which agent initiates interaction\n\n### Thought Isolation \u0026 Observability\n- **Dual-Channel Output**: Thinking models stream internal reasoning to dedicated agent consoles\n- **Sanitized Responses**: Final agent responses exclude thought artifacts before transmission\n- **Three-Column Interface**: Real-time separation of Agent A console, conversation exchange, and Agent B console\n- **Execution Telemetry**: Comprehensive logging of tool calls, cycle timing, and token usage\n\n### MCP Server Management\n- **Global Tool Registry**: MCP servers available to all agents (e.g., filesystem, search)\n- **Agent-Scoped Tools**: Private MCP server instances for individual agent capabilities\n- **Lifecycle Automation**: Automatic startup, health monitoring, and graceful shutdown\n- **Configuration Merging**: Agent tools extend global toolset without conflict\n\n### YAML-Driven Configuration\n- **Single-File Definition**: Export/import entire conversation topology including agents, models, MCP servers, and termination logic\n- **Version Migration**: Schema versioning with backward compatibility\n- **Validation**: Runtime Pydantic validation with IDE-friendly JSON schema\n- **Parameterization**: Environment variable substitution for secrets and endpoints\n\n---\n\n## Target Use Cases\n\n1. **Agent Behavior Research**: Study emergent behaviors in synthetic social interactions\n2. **Model Comparison**: A/B test different LLMs on identical conversation scenarios\n3. **Tool Integration Testing**: Validate MCP server functionality in multi-agent contexts\n4. **Persona Development**: Iterate on agent personalities and system prompts\n5. **Educational Simulations**: Create Socratic dialogues or expert consultations\n6. **AI Safety Testing**: Observe agent interactions in controlled, reproducible environments\n\n---\n\n## Success Metrics\n\n- **Latency**: \u003c100ms WebSocket streaming latency for thoughts\n- **Throughput**: Support 100+ cycle conversations without memory degradation\n- **Reliability**: 99.9% conversation completion rate under normal conditions\n- **Flexibility**: Zero-code deployment of new conversation types via YAML\n- **Observability**: Complete conversation traceability from configuration to execution\n\n---\n\n## Development Status\n\nThis platform is designed for production use in research and development environments, providing a foundational layer for:\n- Multi-agent system experimentation\n- LLM benchmarking frameworks\n- Tool-use validation pipelines\n- Conversational AI safety research\n\nThe architecture supports horizontal scaling via Redis-backed state management and is extensible to multi-agent scenarios beyond the initial two-agent design.\n\n---\n\n## Current Implementation Status\n\n### ✅ Phase 1: Foundation \u0026 Core Infrastructure (COMPLETE)\n\nAll Phase 1 features have been successfully implemented:\n\n1. **Project Structure \u0026 Dependency Setup**\n   - Monorepo structure with backend (Python/FastAPI) and frontend (React/TypeScript)\n   - All dependencies installed and tested\n   - Docker support with docker-compose.yml\n\n2. **Configuration Schema \u0026 Pydantic Models**\n   - Complete Pydantic models for all configuration types\n   - JSON schema generation for IDE support\n   - Comprehensive validation\n\n3. **YAML Import/Export Service**\n   - Load/save configuration from YAML files\n   - Environment variable substitution\n   - Configuration validation with detailed errors\n\n4. **Basic FastAPI Application Skeleton**\n   - Health check and configuration endpoints\n   - CORS middleware for frontend\n   - JSON structured logging\n   - Global exception handling\n\n5. **React Three-Column Layout Shell**\n   - Responsive three-column layout (Agent A | Conversation | Agent B)\n   - Dark theme with TailwindCSS\n   - Shell components for all major UI sections\n\n6. **WebSocket Manager \u0026 Connection Handler**\n   - Backend WebSocket manager with connection pooling\n   - Frontend WebSocket service with auto-reconnection\n   - Heartbeat/ping-pong for connection monitoring\n\nSee [Phase 1 Complete Documentation](docs/PHASE1_COMPLETE.md) for detailed information.\n\n### ✅ Phase 2: Agent Engine \u0026 LangGraph Integration (COMPLETE)\n\nAll Phase 2 features have been successfully implemented:\n\n1. **Ollama Integration Layer**\n   - OllamaClient service with connection verification\n   - Streaming and non-streaming response generation\n   - Model availability checking\n   - Connection testing API endpoint\n\n2. **Thought Suppression Callback Mechanism**\n   - ThoughtSuppressingCallback for separating internal reasoning\n   - Real-time thought streaming to agent consoles\n   - Multiple thought pattern detection (XML, markdown, etc.)\n   - ConversationLoggingCallback for telemetry\n\n3. **LangGraph State Definition**\n   - AgentMessage model with metadata\n   - ConversationState TypedDict\n   - ConversationStateManager for state operations\n   - Serialization and persistence support\n\n4. **Agent Node Factory**\n   - create_agent_node() for LangGraph-compatible nodes\n   - Persona injection and timeout handling\n   - Streaming and non-streaming variants\n   - Comprehensive error handling\n\n5. **Conversation Orchestrator Graph**\n   - ConversationOrchestrator with LangGraph workflow\n   - Dynamic agent node creation\n   - Cycle check and routing logic\n   - State persistence with checkpointing\n\n6. **Cycle Detection \u0026 Termination Logic**\n   - CycleManager for tracking conversation cycles\n   - Max cycles termination\n   - Keyword trigger detection\n   - Silence detection\n\n7. **Initialization \u0026 First Message Handling**\n   - PromptBuilder with Jinja2 template rendering\n   - ConversationInitializer for state setup\n   - System prompt construction\n   - Configuration validation\n\nSee [Phase 2 Summary](PHASE2_SUMMARY.md) for detailed information.\n\n### 🚧 Coming Next: Phase 3 - MCP Server Integration\n\n- MCP Server Manager\n- Global MCP configuration\n- Per-agent MCP server scoping\n- Tool routing and execution\n\n## Installation\n\n### Prerequisites\n\n- Python 3.11+\n- Node.js 18+\n- uv (Python package manager)\n- Ollama (for running LLM models)\n\n### Backend Setup\n\n```bash\ncd backend\nuv venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\nuv pip install -e .\n\n# Copy and configure environment\ncp .env.template .env\n# Edit .env with your settings\n\n# Run backend\nuvicorn app.main:app --reload --host 0.0.0.0 --port 8000\n```\n\n### Frontend Setup\n\n```bash\ncd frontend\nnpm install\n\n# Copy and configure environment\ncp .env.template .env\n# Edit .env with your settings\n\n# Run frontend dev server\nnpm run dev\n\n# Build for production\nnpm run build\n```\n\n### Docker Setup\n\n```bash\n# Build and start all services\ndocker-compose up --build\n\n# Access the application\n# Frontend: http://localhost:3000\n# Backend: http://localhost:8000\n```\n\n## Configuration\n\n### Sample Configuration\n\nA sample configuration is provided at `config/example-simple.yaml`:\n\n```yaml\nversion: \"1.0\"\nconversation:\n  starting_agent: \"agent_a\"\n  max_cycles: 5\n  turn_timeout: 120\n\nagents:\n  agent_a:\n    name: \"Agent A\"\n    persona: \"You are a friendly AI assistant\"\n    model:\n      provider: \"ollama\"\n      url: \"http://localhost:11434\"\n      model_name: \"llama2\"\n      \n  agent_b:\n    name: \"Agent B\"\n    persona: \"You are a knowledgeable AI assistant\"\n    model:\n      provider: \"ollama\"\n      url: \"http://localhost:11434\"\n      model_name: \"llama2\"\n\ninitialization:\n  first_message: \"Hello! Let's have a conversation.\"\n\nlogging:\n  level: \"INFO\"\n```\n\n## API Documentation\n\n### Backend Endpoints\n\n**Configuration Management**:\n- `GET /health` - Health check\n- `GET /api/config/schema` - Get configuration JSON schema\n- `POST /api/config/import` - Import configuration from JSON\n- `GET /api/config/export` - Export current configuration\n- `POST /api/config/validate` - Validate YAML configuration\n- `POST /api/config/upload` - Upload YAML configuration file\n\n**Ollama Management**:\n- `POST /api/ollama/test-connection` - Test Ollama connection and model availability\n\n**Conversation Control**:\n- `POST /api/conversation/start` - Start a new conversation\n- `POST /api/conversation/stop` - Stop the current conversation\n- `GET /api/conversation/status` - Get conversation status\n\n**WebSocket**:\n- `GET /api/ws/status` - WebSocket connection status\n- `WS /ws/{client_id}` - WebSocket endpoint for real-time updates\n\n### Testing\n\n```bash\n# Backend\ncd backend\nsource .venv/bin/activate\npytest\n\n# Frontend\ncd frontend\nnpm test\n\n# End-to-end tests\nnpm run test:e2e\n```\n\n## Development\n\n### Project Structure\n\n```\nai-agent-mixer/\n├── backend/           # FastAPI backend\n│   ├── app/\n│   │   ├── schemas/   # Pydantic models\n│   │   ├── services/  # Business logic\n│   │   ├── core/      # Core infrastructure\n│   │   └── agents/    # Agent implementations\n│   └── tests/\n├── frontend/          # React frontend\n│   ├── src/\n│   │   ├── components/\n│   │   └── services/\n│   └── public/\n├── config/            # Configuration files\n├── docs/              # Documentation\n└── tests/             # Integration tests\n```\n\n### Contributing\n\nThis project is developed following the specifications in `PROJECT_SPECS.md`. Each phase builds upon the previous one:\n\n1. Phase 1: Foundation \u0026 Core Infrastructure (✅ Complete)\n2. Phase 2: Agent Engine \u0026 LangGraph Integration (✅ Complete)\n3. Phase 3: MCP Server Integration (🚧 Next)\n4. Phase 4: Web Interface \u0026 Real-Time Features\n5. Phase 5: Testing, Polish \u0026 Deployment\n\n## License\n\nSee LICENSE file for details.\n\n## Support\n\nFor questions or issues:\n- Review the [Phase 1 Documentation](docs/PHASE1_COMPLETE.md)\n- Check [PROJECT_SPECS.md](PROJECT_SPECS.md) for detailed specifications\n- Open an issue on GitHub","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzloeber%2Fai-agent-mixer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzloeber%2Fai-agent-mixer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzloeber%2Fai-agent-mixer/lists"}