Nuxt 3 + Flask + Socket.IO"] O_CORE["Core Engine
Workflow Manager
Task Manager"] O_ADAPT["Adapters
Claude | Codex | Gemini
Copilot | Ollama | llama.cpp"] O_RESIL["Resilience
Retry | Fallback | Offline"] O_OBS["Observability
Prometheus | Logging | Health"] O_SEC["Security Module
Validation | Rate Limiting | Audit"] O_INFRA["Infra
Cache | Async Executor | Config Manager"] O_CONF["orchestrator/config/agents.yaml"] end subgraph AgenticTeam["agentic_team/"] A_CLI["CLI REPL"] A_UI["Web UI
Nuxt 3 + Flask + Socket.IO"] A_ENGINE["Engine
Free Communication
Lead-Gated Output"] A_ADAPT["Adapters
Claude | Codex | Gemini
Copilot | Ollama | llama.cpp"] A_FALLBACK["Fallback + Offline"] A_CONF["orchestrator/config/agents.yaml"] end end O_CLI --> O_CORE O_UI --> O_CORE O_CORE --> O_ADAPT O_CORE --> O_RESIL O_CORE --> O_OBS O_CORE --> O_SEC O_CORE --> O_INFRA O_ADAPT --> ExtCloud["Cloud CLIs
claude | codex | gemini | copilot"] O_ADAPT --> ExtLocal["Local Backends
Ollama | llama.cpp"] A_CLI --> A_ENGINE A_UI --> A_ENGINE A_ENGINE --> A_ADAPT A_ENGINE --> A_FALLBACK A_ADAPT --> ExtCloud A_ADAPT --> ExtLocal style Orchestrator fill:#1a1a2e,stroke:#16213e,color:#e0e0e0 style AgenticTeam fill:#1a2e1a,stroke:#162e16,color:#e0e0e0 ``` ### Orchestrator Workflow Execution The Orchestrator processes tasks through a configurable pipeline of AI agents. Each step in a workflow maps to a specific agent and role. ```mermaid sequenceDiagram participant User participant CLI as CLI / Web UI participant Engine as Core Engine participant WF as Workflow Manager participant Codex as Codex Adapter participant Gemini as Gemini Adapter participant Claude as Claude Adapter participant FB as Fallback Manager User->>CLI: Submit task CLI->>Engine: execute(task, workflow="default") Engine->>WF: load workflow steps WF->>Codex: Step 1 -- implement alt Codex unavailable Codex-->>FB: error FB->>FB: route to local-code end Codex-->>WF: implementation WF->>Gemini: Step 2 -- review Gemini-->>WF: review feedback WF->>Claude: Step 3 -- refine Claude-->>WF: refined code WF-->>Engine: final result Engine-->>CLI: display output CLI-->>User: code + report ``` ### Agentic Team Communication Flow The Agentic Team uses free role-to-role communication. Agents speak in turns, address each other by role, and the team lead decides when the task is complete. ```mermaid sequenceDiagram participant User participant PM as Project Manager (Lead) participant Arch as Software Architect participant Dev as Software Developer participant QA as QA Engineer participant DevOps as DevOps Engineer User->>PM: "Build a REST API with auth" PM->>Arch: Define architecture and constraints Arch->>Dev: Provide interface specs Dev->>Dev: Implement code Dev->>QA: Request quality review QA->>Dev: Report edge cases Dev->>Dev: Fix issues Dev->>DevOps: Request deployment review DevOps->>PM: Confirm operational readiness PM->>User: Final consolidated response ``` ### Adapter Resolution Flow Both systems resolve which AI backend to use at runtime. The adapter layer abstracts cloud CLIs and local model servers behind a common interface. ```mermaid flowchart TD REQ[Incoming Task Step] --> CHECK{Agent Enabled?} CHECK -->|Yes| HEALTH{Health Check} CHECK -->|No| SKIP[Skip Agent] HEALTH -->|Healthy| EXEC[Execute via Adapter] HEALTH -->|Unhealthy| FB{Fallback Configured?} FB -->|Yes| LOCAL[Route to Local Adapter
Ollama / llama.cpp] FB -->|No| ERR[Raise AgentUnavailableError] EXEC --> PARSE[Parse CLI Output] LOCAL --> PARSE PARSE --> RESULT[Return AgentResponse] style EXEC fill:#2b6cb0,stroke:#2c5282,color:#fff style LOCAL fill:#276749,stroke:#22543d,color:#fff style ERR fill:#9b2c2c,stroke:#742a2a,color:#fff ``` ### Local model execution semantics and limitation Local models are deeply integrated for routing, offline mode, and fallback, but they are **not direct workspace editors** in the current implementation. | Path | How it runs | Direct file edits | |---|---|---| | Cloud CLI adapters (Codex/Claude/Gemini/Copilot) | CLI process + workspace execution path | Yes (tool-dependent) | | Local adapters (Ollama/llama.cpp/OpenAI-compatible) | HTTP prompt-completion (`/api/generate` or `/v1/completions`) | No (text output only) | Best use for local models: offline drafting, review feedback, and cloud-to-local fallback continuity. > [!CAUTION] > While it is possible to make local LLMs directly edit files (e.g., via a `file-editor` tool), this approach is currently disabled to prevent unintended destructive changes. Local adapters are advisory β they provide text output that the Orchestrator can use to inform the next steps, but they do not have direct write access to the workspace. This design choice prioritizes safety and predictability while still leveraging local models for their strengths in drafting and feedback. The hard part is not feasibility, itβs safety and reliability: permissions, diff constraints, validation/tests before write, rollback, and preventing bad edits. ### Technology Stack Overview ```mermaid graph LR subgraph Backend PY[Python 3.8+] FL[Flask 3.x] SIO[Socket.IO 4.x] PD[Pydantic 2.x] CL[Click 8.x] end subgraph Frontend VUE[Vue 3] NUXT[Nuxt 3] TW[Tailwind CSS 3.x] MON[Monaco Editor] PIN[Pinia] end subgraph Observability PROM[Prometheus] GRAF[Grafana] SL[structlog] end subgraph Infrastructure DOCK[Docker] K8S[Kubernetes] TF[Terraform] end PY --> FL --> SIO PY --> PD PY --> CL VUE --> NUXT --> TW VUE --> MON VUE --> PIN PROM --> GRAF DOCK --> K8S style Backend fill:#1a1a2e,stroke:#16213e,color:#e0e0e0 style Frontend fill:#1a2e1a,stroke:#162e16,color:#e0e0e0 style Observability fill:#2e1a1a,stroke:#2e1616,color:#e0e0e0 style Infrastructure fill:#1a1a2e,stroke:#16213e,color:#e0e0e0 ``` ## System Comparison The two systems serve different collaboration models. Choose based on your use case. | Dimension | Orchestrator (`orchestrator/`) | Agentic Team (`agentic_team/`) | |---|---|---| | **Collaboration model** | Step-based pipeline (sequential) | Free role-to-role communication (turns) | | **Agent identity** | Tool names (codex, gemini, claude) | Roles (PM, Architect, Developer, QA, DevOps) | | **Control flow** | Dynamic metrics-based planner or workflow YAML step order | Team lead (PM) gates completion dynamically | | **When to use** | Dynamic planning, or repeatable pipelines: implement, review, refine | Open-ended tasks needing discussion and consensus | | **CLI entry point** | `ai-orchestrator shell` | `ai-orchestrator agentic-shell` | | **Web UI port** | `:5001` | `:5002` | | **Config file** | `orchestrator/config/agents.yaml` | `agentic_team/config/agents.yaml` | | **Built-in workflows** | Dynamic planner (metrics-based routing), plus 7 static (default, quick, thorough, review-only, document, offline-default, hybrid) | N/A (turn-based, no fixed pipeline) | | **Fallback strategy** | Per-step cloud-to-local routing | Independent fallback manager | | **Observability** | Prometheus metrics, structured logging, health probes, report generation | Health and readiness probes | | **Security module** | Input validation, rate limiting, audit logging | N/A (inherits from adapter layer) | | **Shared code** | None | None | ## Feature Highlights ### Orchestrator (`orchestrator/`) | Category | Features | |---|---| | **Workflows** | 7 built-in workflows (default, quick, thorough, review-only, document, offline-default, hybrid); define custom ones in YAML | | **Agents** | Claude, Codex, Gemini, Copilot (cloud); Ollama, llama.cpp (local) | | **CLI** | Interactive REPL shell, one-shot commands, context-aware follow-ups, readline support | | **Web UI** | Nuxt 3 + Vue 3 frontend, Flask + Socket.IO backend, Monaco code editor, Pinia state management | | **Local model behavior** | Local adapters are advisory (text output); direct file edits come from CLI-backed agents | | **Resilience** | Retry with exponential backoff, circuit breakers, cloud-to-local fallback, offline detection | | **Observability** | Prometheus metrics, structured logging via structlog, health and readiness probes | | **Reports** | Execution summaries, agent performance, workflow analytics, config audits, HTML dashboard with Chart.js charts | | **Security** | Input validation, rate limiting, secret management, audit logging | | **Infra** | Async executor, response caching, connection pooling, config manager | ### Agentic Team (`agentic_team/`) | Category | Features | |---|---| | **Runtime** | Free role-to-role communication, configurable turn limits, lead-gated final responses | | **Roles** | Project Manager, Software Architect, Software Developer, QA Engineer, DevOps Engineer | | **CLI** | Dedicated REPL (`agentic-shell`) with `--max-turns` and `--offline` flags | | **Web UI** | Dedicated Nuxt 3 + Flask UI with Config Studio, real-time turn streaming, team communication view | | **Local model behavior** | Local adapters contribute role outputs and fallback text, but do not directly write files | | **Fallback** | Independent fallback manager and offline detector | | **Configuration** | Separate `agents.yaml` with `agentic_team.roles` section for role-to-agent mapping | ### Graphify (`graphify/`) | Category | Features | |---|---| | **Analysis** | Python AST (classes, functions, imports, calls, decorators, docstrings), JS/TS, Go, Rust, Java, C++, Markdown, YAML/JSON/TOML | | **Graph** | SQLite + FTS5, WAL mode, schema migrations (v1βv2βv3), thread-local connections, context manager | | **Search** | Full-text search, node explanation, path finding (BFS), community detection, god node analysis, complexity hotspots | | **Cache** | SHA-256 content-addressable cache, incremental scans (only changed files) | | **Export** | JSON, DOT (Graphviz), Markdown, GraphML, interactive HTML (vis.js), **Obsidian vault** | | **API** | Flask REST API with CORS, structured error handling, metrics/snapshot/diff endpoints | | **Operations** | File watching (watchdog + polling), graph snapshots & diffing, scan metrics collection | | **Security** | Path traversal protection, input sanitization, bounded parameters, no debug mode | ## Quick Start ### Prerequisites - **Operating System**: Linux, macOS, or Windows (WSL recommended) - **Python**: 3.8 or higher - **Node.js**: 20+ (for Web UI) - **Memory**: Minimum 4GB RAM - **Disk Space**: 1GB for installation + workspace - **Network**: Required for AI CLI tools and updates - **Claude Code**: Installed, setup, and signed in on your machine (Required for any workflows using Claude Code - if you run `claude` in terminal and it works, you're good) - **OpenAI Codex**: Installed and authenticated (if using Codex agent, try running `codex` and see if it responds) - **Google Gemini CLI**: Installed and authenticated (if using Gemini agent, try `gemini --version` to verify) - **GitHub Copilot CLI**: Installed and authenticated (if using Copilot agent, try `copilot --version` to verify) - **Llama.cpp or Ollama**: If using local LLM agents, ensure they are installed and configured properly (try running `ollama list` or `llamacpp --help` to verify) - **Optional**: Docker and Docker Compose for containerized setup ### Install ```bash git clone https://github.com/hoangsonww/AI-Agents-Orchestrator.git cd AI-Agents-Orchestrator python3 -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate pip install -r requirements.txt chmod +x ai-orchestrator ``` ### Run the Orchestrator ```bash # Interactive shell ./ai-orchestrator shell # One-shot task ./ai-orchestrator run "Create a Python REST API" --workflow default # Start the Web UI make run-ui # Then open http://localhost:5001 ``` ### Run the Agentic Team ```bash # Interactive REPL ./ai-orchestrator agentic-shell # With options ./ai-orchestrator agentic-shell --max-turns 16 --offline # Start the Web UI make run-agentic-ui # Then open http://localhost:5002 ``` ### Verify Installation ```bash ./ai-orchestrator --help # Show all commands ./ai-orchestrator agents # List available agents ./ai-orchestrator workflows # List available workflows ./ai-orchestrator validate # Validate configuration ``` ## Project Structure ``` AI-Coding-Tools/ | |-- .claude/ # Claude Code agentic infrastructure | |-- CLAUDE.md # Main Claude instructions (imports AGENTS.md) | |-- settings.json # Project settings and permissions | |-- agents/ # 11 specialized agent definitions | | |-- web-frontend.md | | |-- backend-api.md | | |-- security-specialist.md | | |-- devops-infrastructure.md | | |-- ai-ml-engineer.md | | |-- database-architect.md | | |-- mobile-developer.md | | |-- performance-engineer.md | | |-- documentation-writer.md | | |-- code-reviewer.md | | +-- test-runner.md | |-- skills/ # 23 reusable skill templates | | |-- development/ # 6 skills (react, REST, async, DB, GraphQL, errors) | | |-- testing/ # 4 skills (unit, integration, TDD, perf) | | |-- security/ # 4 skills (validation, auth, secure-coding, vuln) | | |-- devops/ # 3 skills (Docker, CI/CD, K8s) | | |-- ai-ml/ # 3 skills (embeddings, LLM, RAG) | | |-- documentation/ # 3 skills (API docs, arch docs, code docs) | | |-- generate-reports/ # Standalone: report generation | | |-- health-check/ # Standalone: system health checks | | |-- run-tests/ # Standalone: test suite execution | | +-- context-graph-builder/ # Standalone: context graph operations | +-- rules/ # 11 domain rule files | |-- adapters.md | |-- api-design.md | |-- testing.md | |-- performance.md | |-- config.md | |-- ai-ml.md | |-- observability.md | |-- frontend.md | |-- ci-cd.md | |-- security.md | +-- database.md | |-- .codex/ # Codex agentic infrastructure | |-- config.toml # Codex project configuration | |-- agents/ # 13 specialized agent definitions (.toml) | | |-- code-reviewer.toml | | |-- explorer.toml | | |-- security-specialist.toml | | |-- web-frontend.toml | | |-- devops-infrastructure.toml | | |-- implementer.toml | | |-- database-architect.toml | | |-- performance-engineer.toml | | |-- test-runner.toml | | |-- ai-ml-engineer.toml | | |-- backend-api.toml | | |-- documentation-writer.toml | | +-- mobile-developer.toml | |-- hooks/ # Git hook integrations | +-- rules/ # Codex-specific rules | |-- mcp_server/ # MCP server (FastMCP 3.x) β 34+ tools | |-- server.py # Server entry point + core tools | |-- engines.py # Engine adapters for both systems | |-- repl.py # Interactive REPL mode | |-- tools/ # Tool modules by category | | |-- orchestrator_tools.py # Orchestrator execution tools | | |-- agentic_team_tools.py # Agentic team execution tools | | |-- shared_tools.py # Shared utility tools | | |-- code_analysis.py # 4 code analysis tools | | |-- security_tools.py # 4 security scanning tools | | |-- testing_tools.py # 4 testing tools | | |-- devops_tools.py # 5 DevOps tools | | +-- context_tools.py # 7 context memory tools | +-- resources/ # MCP resource definitions | |-- orchestrator/ # Self-contained orchestrator system | |-- __init__.py | |-- adapters/ # AI agent adapters | | |-- base.py # Abstract base adapter | | |-- claude_adapter.py # Claude Code CLI | | |-- codex_adapter.py # OpenAI Codex CLI | | |-- gemini_adapter.py # Google Gemini CLI | | |-- copilot_adapter.py # GitHub Copilot CLI | | |-- ollama_adapter.py # Ollama local models | | |-- llama_cpp_adapter.py # llama.cpp / OpenAI-compatible | | +-- cli_communicator.py # Robust CLI subprocess handling | |-- core/ # Core orchestration logic | | |-- engine.py # Main orchestration engine | | |-- workflow.py # Workflow definitions and runner | | |-- task_manager.py # Task lifecycle management | | +-- exceptions.py # Custom exception hierarchy | |-- resilience/ # Fault tolerance | | |-- retry.py # Retry with exponential backoff | | |-- fallback.py # Cloud-to-local fallback routing | | +-- offline.py # Offline detection | |-- observability/ # Monitoring, logging, and reports | | |-- metrics.py # Prometheus metrics | | |-- logging_config.py # Structured logging setup | | |-- health.py # Health and readiness probes | | +-- report_generator.py # Execution, performance, and HTML reports | |-- security_module/ # Security layer | | +-- security.py # Validation, rate limiting, audit | |-- infra/ # Infrastructure utilities | | |-- cache.py # Response caching | | |-- async_executor.py # Async task execution | | +-- config_manager.py # Configuration loading | |-- cli/ # CLI interface | | +-- shell.py # Interactive REPL shell | |-- context/ # Graph-based context memory | | |-- memory_manager.py # High-level memory API | | |-- models/ # Node and edge schemas | | | +-- schemas.py | | |-- store/ # Graph persistence layer | | | +-- graph_store.py | | |-- search/ # Search engines | | | |-- bm25_index.py # BM25 keyword search | | | |-- embeddings.py # Embedding generation | | | |-- hybrid_search.py # Hybrid BM25 + semantic | | | +-- advanced_search.py # Advanced query support | | +-- ops/ # Operational utilities | | |-- analytics.py # Graph analytics | | |-- export.py # Data export | | |-- pruning.py # Node/edge pruning | | |-- versioning.py # Version tracking | | +-- project_scanner.py # Project directory scanning | |-- config/ | | +-- agents.yaml # Agents, workflows, settings | |-- ui/ # Web UI | | |-- app.py # Flask + Socket.IO backend | | |-- frontend/ # Nuxt 3 + Vue 3 + Tailwind | | |-- static/ | | +-- templates/ | +-- README.md # Orchestrator-specific docs | |-- agentic_team/ # Self-contained agentic team system | |-- __init__.py | |-- engine.py # Role-based communication engine | |-- shell.py # Agentic team REPL | |-- decision_parser.py # Turn decision parsing | |-- config_utils.py # Config loading utilities | |-- constants.py # Shared constants | |-- fallback.py # Independent fallback manager | |-- offline.py # Independent offline detector | |-- adapters/ # Own copy of AI agent adapters | | |-- base.py | | |-- claude_adapter.py | | |-- codex_adapter.py | | |-- gemini_adapter.py | | |-- copilot_adapter.py | | |-- ollama_adapter.py | | |-- llama_cpp_adapter.py | | +-- cli_communicator.py | |-- context/ # Independent graph-based context memory | | |-- memory_manager.py # High-level memory API | | |-- models/ # Node and edge schemas | | |-- store/ # Graph persistence layer | | |-- search/ # BM25 + FTS5 hybrid search | | +-- ops/ # Analytics, export, pruning, project scanning | |-- config/ | | +-- agents.yaml # Agents, roles, team settings | |-- ui/ # Dedicated Web UI | | |-- app.py # Flask + Socket.IO backend | | |-- frontend/ # Nuxt 3 + Vue 3 + Tailwind | | |-- static/ | | +-- templates/ | +-- README.md # Agentic team-specific docs | |-- tests/ # Unified test suite | |-- conftest.py | |-- test_orchestrator.py | |-- test_adapters.py | |-- test_adapter_execution.py | |-- test_agentic_team_engine.py | |-- test_agentic_ui_backend.py | |-- test_integration.py | |-- test_functional_e2e.py | |-- test_enterprise_hardening.py | |-- test_production_hardening.py | +-- ... | |-- reports/ # Generated reports (JSON + HTML dashboard) | |-- INDEX.json # Report catalog | |-- exec_*.json # Per-task execution summaries | |-- perf_*.json # Agent performance analytics | |-- workflow_*.json # Workflow-level analytics | |-- health_*.json # System health snapshots | |-- config_*.json # Configuration audits | +-- dashboard_*.html # Interactive HTML dashboard with charts | |-- deployment/ # Deployment configurations | |-- kubernetes/ | |-- azure/ | |-- systemd/ | |-- load-balancer/ | +-- scripts/ | |-- docs/ # Documentation | |-- images/ # Screenshots | |-- orchestrator-architecture.md | |-- orchestrator-api-reference.md | |-- agentic-team-architecture.md | |-- agentic-team-api-reference.md | |-- configuration-guide.md | |-- testing-guide.md | |-- security.md | +-- offline-mode.md | |-- examples/ # Usage examples | |-- orchestrator/ | +-- agentic_team/ | |-- context_dashboard/ # Unified context visualization (port 5003) | |-- app.py # Flask app aggregating both context stores | |-- templates/ | | +-- dashboard.html # Interactive graph visualization | +-- README.md # Dashboard-specific docs | |-- scripts/ # Helper scripts | |-- install.sh | |-- start-ui.sh | |-- start-agentic-ui.sh | |-- start-mcp-server.sh | |-- start-all.sh | |-- seed_context_graphs.py | |-- health-check.sh | |-- format.sh | |-- lint.sh | +-- test.sh | |-- ai-orchestrator # Main CLI entry point |-- Dockerfile # Multi-stage production image |-- docker-compose.yml # Both UIs + monitoring stack |-- Makefile # Development commands |-- pyproject.toml # Project metadata and tool config |-- requirements.txt # Python dependencies |-- AGENTS.md # Shared instructions for all AI coding agents |-- AGENTIC_INFRA.md # Full agentic infrastructure documentation |-- SETUP.md # Installation and setup guide |-- ARCHITECTURE.md |-- FEATURES.md |-- AGENTIC_TEAM.md |-- OFFLINE_MODE.md |-- DEPLOYMENT.md +-- LICENSE ``` > [!IMPORTANT] > **Key design decision:** `orchestrator/` and `agentic_team/` are fully self-contained. Each carries its own `adapters/`, `config/`, and `ui/` directories. There are no shared root-level `adapters/`, `ui/`, or `config/` directories. The two systems share zero code and zero imports. ## Configuration Both systems read their configuration from their own `orchestrator/config/agents.yaml` file. The files follow the same schema but are independent. ```mermaid graph LR subgraph Orchestrator Config OC["orchestrator/config/agents.yaml"] OC --> OA["agents: codex, gemini, claude, ..."] OC --> OW["workflows: default, quick, thorough, ..."] OC --> OS["settings: max_iterations, output_dir, ..."] OC --> OAT["agentic_team: roles (shared schema)"] end subgraph Agentic Team Config AC["agentic_team/config/agents.yaml"] AC --> AA["agents: codex, gemini, claude, ..."] AC --> AW["workflows: (same schema)"] AC --> AS["settings: (same schema)"] AC --> AAT["agentic_team: lead_role, max_turns, roles"] end style OC fill:#2d3748,stroke:#4a5568,color:#e2e8f0 style AC fill:#22543d,stroke:#276749,color:#e2e8f0 ``` ### Available Workflows | Workflow | Pipeline | Use Case | |---|---|---| | `default` | Codex --> Gemini --> Claude | Production-quality code with full review | | `quick` | Codex only | Fast prototyping | | `thorough` | Codex --> Copilot --> Gemini --> Claude --> Gemini | Mission-critical code | | `review-only` | Gemini --> Claude | Analyzing existing code | | `document` | Claude --> Gemini | Documentation generation | | `offline-default` | local-code --> local-instruct | Local-only, no cloud dependency | | `hybrid` | local-code --> Claude (fallback: local-instruct) | Local drafts with cloud review | ## Deployment ### Docker Compose (Recommended) Both systems are packaged in a single multi-stage Docker image. The `docker-compose.yml` runs each as a separate service. ```mermaid graph TD subgraph Docker Compose direction TB OUI["orchestrator-ui
:5001"] AUI["agentic-team-ui
:5002"] PROM["prometheus
:9091
(monitoring profile)"] GRAF["grafana
:3000
(monitoring profile)"] end OUI --> SHARED_VOL["Shared Volumes
output/ workspace/ logs/ sessions/"] AUI --> SHARED_VOL PROM --> OUI PROM --> AUI GRAF --> PROM style OUI fill:#2b6cb0,stroke:#2c5282,color:#fff style AUI fill:#276749,stroke:#22543d,color:#fff style PROM fill:#c05621,stroke:#9c4221,color:#fff style GRAF fill:#6b46c1,stroke:#553c9a,color:#fff ``` ```bash # Start both UIs docker compose up --build -d # Start with monitoring (Prometheus + Grafana) docker compose --profile monitoring up --build -d # Stop everything docker compose down ``` ### Kubernetes ```bash kubectl create namespace ai-coding-tools kubectl apply -f deployment/kubernetes/ kubectl get pods -n ai-coding-tools ``` See [DEPLOYMENT.md](DEPLOYMENT.md) for systemd, Azure, load balancer, and production hardening guides. ## Testing The unified test suite (386 tests across 60+ modules) covers both systems independently. ```mermaid flowchart LR subgraph "make all" FMT[format
black + isort] --> LINT[lint
flake8 + pylint] LINT --> TYPE[type-check
mypy] TYPE --> TEST[test
314 tests] TEST --> SEC[security
bandit + safety] end subgraph "Test Targets" TEST --> T_ORCH[test-orchestrator] TEST --> T_AGENT[test-agentic] TEST --> T_UNIT[test-unit] TEST --> T_INT[test-integration] TEST --> T_E2E[test-e2e] end style FMT fill:#2b6cb0,stroke:#2c5282,color:#fff style TEST fill:#276749,stroke:#22543d,color:#fff style SEC fill:#9b2c2c,stroke:#742a2a,color:#fff ``` ```bash # Run all tests make test # Orchestrator tests only make test-orchestrator # Agentic team tests only make test-agentic # Unit tests only make test-unit # Integration tests only make test-integration # Tests with coverage report make test-coverage ``` ### Code Quality The codebase maintains a **perfect 10.00/10 pylint score** with zero warnings across the entire project, enforced by 15 pre-commit hooks (black, isort, flake8, mypy, bandit, pyupgrade, and more). | Metric | Value | |--------|-------| | **Pylint Score** | 10.00 / 10 | | **Warnings** | 0 | | **Tests Passing** | 386 | | **Pre-commit Hooks** | 15 / 15 passing | ```bash make lint # Lint all Python source (flake8 + pylint) make format # Format with black + isort make type-check # Run mypy on both subsystems make security # Run bandit + safety make all # Run everything (format, lint, type-check, test, security) ``` ## Monitoring Prometheus metrics are exposed by the orchestrator UI backend on port 9090. | Metric | Description | |---|---| | `orchestrator_tasks_total` | Total tasks executed | | `orchestrator_task_duration_seconds` | Task execution time | | `orchestrator_agent_calls_total` | Agent invocations | | `orchestrator_agent_errors_total` | Agent error count | | `orchestrator_cache_hits_total` | Cache performance | ### Reports The orchestrator automatically generates reports in `reports/` when `create_reports: true` is set in `agents.yaml`. Reports include: | Report Type | Description | |---|---| | **Execution Summary** | Per-task results: steps, agents used, fallbacks, suggestions, duration | | **Agent Performance** | Aggregated success rates, call counts, task type distribution | | **Workflow Analytics** | Per-workflow run counts, success rates, average iterations | | **System Health** | Health check results, disk/memory, Python version, platform | | **Config Audit** | Agent availability, workflow structure, settings snapshot | | **HTML Dashboard** | Interactive Chart.js dashboard with KPI cards, bar/line/doughnut charts | Reports are also generated programmatically via: ```python from orchestrator.observability import ReportGenerator gen = ReportGenerator(reports_dir="./reports") gen.seed_reports(config=config) # Generate all report types with sample data ``` Health checks: - Orchestrator: `http://localhost:5001/health`, `http://localhost:5001/ready` - Agentic Team: `http://localhost:5002/health`, `http://localhost:5002/ready` ## Documentation | Document | Description | |------------------------------------------------------|------------------------------------------------------------------| | **[SETUP.md](SETUP.md)** | Prerequisites, installation, environment setup, troubleshooting | | **[ARCHITECTURE.md](ARCHITECTURE.md)** | System architecture and design patterns | | **[FEATURES.md](FEATURES.md)** | Comprehensive feature documentation | | **[AGENTIC_TEAM.md](AGENTIC_TEAM.md)** | Agentic team runtime details | | **[OFFLINE_MODE.md](OFFLINE_MODE.md)** | Offline mode and local model guide | | **[DEPLOYMENT.md](DEPLOYMENT.md)** | Docker, Kubernetes, systemd, Azure deployment | | **[ADD_AGENTS.md](ADD_AGENTS.md)** | Guide for adding new AI agents | | **[orchestrator/README.md](orchestrator/README.md)** | Orchestrator subsystem documentation | | **[agentic_team/README.md](agentic_team/README.md)** | Agentic team subsystem documentation | | **[docs/](docs/)** | API references, architecture deep-dives, testing guide, security | ## Screenshots Some screenshots of the Web UIs and CLI interfaces:
Orchestrator Web UI β real-time task execution dashboard with agent status and workflow controls
Agentic Team Web UI β role-based multi-agent collaboration with live communication view
Context Graph Dashboard β interactive knowledge graph visualization with node inspection and hybrid search
Orchestrator CLI β command-line interface for task execution and agent management
Agentic Shell REPL β interactive shell for direct agent communication and debugging
MCP Tools REPL β interactive console for exploring and testing 34+ MCP tools across both engines
orchestrator_execute, agentic_team_execute,
list_engines, health, config, validate"] CODE["Code Analysis (4)
code_complexity, find_patterns,
analyze_deps, code_summary"] SEC["Security (4)
secrets_scan, security_headers_check,
dependency_audit, injection_scan"] TEST["Testing (4)
suggest_tests, test_coverage_analysis,
parse_tests, create_test_stub"] DEVOPS["DevOps (5)
dockerfile_analysis, compose_analysis,
ci_config_check, deploy_checklist, env_config_analysis"] CTX["Context (7)
context_store_conversation, context_store_task,
context_log_mistake, context_store_pattern,
context_search, context_get_relevant, context_stats"] end subgraph "Engines" O[Orchestrator :5001] A[Agentic Team :5002] D[Context Dashboard :5003] end CD & LA & PY & REPL -->|MCP Protocol| CORE & CODE & SEC & TEST & DEVOPS & CTX CORE --> O & A CTX --> D ``` **34+ MCP tools** organized across 6 categories: | Category | Count | Tools | |----------|-------|-------| | **Core Orchestration** | 10 | `orchestrator_execute`, `agentic_team_execute`, `list_engines`, `orchestrator_health`, `agentic_team_health`, `list_workflows`, `list_agents`, `validate_config`, `team_config`, `agentic_team_validate` | | **Code Analysis** | 4 | `code_complexity`, `find_patterns`, `analyze_deps`, `code_summary` | | **Security** | 4 | `secrets_scan`, `security_headers_check`, `dependency_audit`, `injection_scan` | | **Testing** | 4 | `suggest_tests`, `test_coverage_analysis`, `parse_tests`, `create_test_stub` | | **DevOps** | 5 | `dockerfile_analysis`, `compose_analysis`, `ci_config_check`, `deploy_checklist`, `env_config_analysis` | | **Context Memory** | 7 | `context_store_conversation`, `context_store_task`, `context_log_mistake`, `context_store_pattern`, `context_search`, `context_get_relevant`, `context_stats` | See [`mcp_server/tools/`](mcp_server/tools/) for the full tool implementations. > [!TIP] > The MCP server is entirely optional. Both the Orchestrator and Agentic Team work fully via their own CLIs and Web UIs without it. Use `python -m mcp_server repl` for an interactive REPL to explore and test tools from the terminal. ## Contributing Contributions are welcome. Please see [CONTRIBUTING.md](.github/CONTRIBUTING.md) for guidelines. 1. Fork the repository. 2. Create a feature branch: `git checkout -b feature/your-feature` 3. Make your changes and add tests. 4. Run checks: `make all` 5. Commit using [conventional commits](https://www.conventionalcommits.org/): `git commit -m "feat: add amazing feature"` 6. Push and open a Pull Request. ## Security For security issues, please email hoangson091104@gmail.com. Do not open public issues for security vulnerabilities. See [SECURITY.md](SECURITY.md) for the full security policy. ## License This project is licensed under the MIT License. See [LICENSE](LICENSE) for details. ## Support - **Maintainer**: [@hoangsonww](https://github.com/hoangsonww) - **Issues**: [GitHub Issues](https://github.com/hoangsonww/AI-Agents-Orchestrator/issues) - **Discussions**: [GitHub Discussions](https://github.com/hoangsonww/AI-Agents-Orchestrator/discussions) ---
**Made with care and love by [Son Nguyen](https://github.com/hoangsonww) for the AI development community π€**
[Back to Top](#ai-coding-tools-orchestrator-and-agentic-team-runtime)
> **Easter egg:** Go to our [wiki page](https://hoangsonww.github.io/AI-Agents-Orchestrator/) and enter Konami code (β β β β β β β β B A) for a surprise!