Agentic Engineers
niallyoung/agentic-engineers
Orquestrador de agentes especializados com gates de qualidade e otimização de tokens
Ver no GitHubFramework de orquestração multi-agentes que coordena especialistas de IA para otimizar uso de tokens (~50% de redução), qualidade e velocidade de entrega. Implementa filas de trabalho, gates de qualidade e feedback contínuo para otimização de custo-benefício, integrando-se com Claude, Copilot, OpenCode e Pi.
Instalação
npx convez-ai niallyoung/agentic-engineers1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Coordenar múltiplos agentes de IA em fluxos complexos de SDLC-CICD
- Reduzir custos de API mantendo qualidade através de seleção inteligente de modelos
- Automatizar revisão de código, auditoria de segurança e otimização de arquitetura em paralelo
Veredito

Solução robusta para engenheiros que precisam coordenar múltiplos agentes de IA em ambientes de produção com restrições de token e custo. Arquitetura baseada em fila com protocol DELEGATE/HANDBACK bem-definido, embora ainda em consolidação (PRs em andamento para validação completa).
README
A tradução para o português deste README ainda está na fila.
Agentic Engineers
A Multi-Agent Orchestration Framework for optimizing token usage, quality, and delivery speed through intelligent work routing, quality gates, and continuous cost-quality optimization feedback loops. Designed for integration with coding CLIs: Claude, Copilot, OpenCode, Pi.
What It Is
Agentic Engineers solves the multi-agent coordination problem:
- How do you coordinate 8+ specialized AI agents without spaghetti code?
- How do you enforce quality gates consistently across all agents?
- How do you optimize cost while maintaining quality?
- How do you stay within token budgets across unlimited work?
The answer: A queue-based ORCHESTRATOR-FIRST architecture:
- All work enters a queue as DELEGATE tasks (SPEC-compliant YAML)[1]
- Orchestrator polls and routes to the right specialist
- Each agent returns a HANDBACK with results + metrics
- Quality gates validate all work before moving to done
- Metrics feed back into model selection and routing optimization
[1] oops, soon with "actually works again" 🤦♂️ 20260609 PR on its way
Key Benefits
- 90+/100 Quality — Structured DELEGATE/HANDBACK protocol enforces clarity
- 65% Cost Savings — Smart model selection (Haiku for execution, Opus for architecture)
- 40-60% Faster — Parallel sub-agent execution at scale
- 80% Fewer Iterations — Clear success criteria prevent rework
See Key Benefits & Discoveries below for details.
Architecture at a Glance
┌─────────────────────────────────────────────────────────────┐
│ AGENTIC-ENGINEERS │
│ Framework & Multi-Harness System │
└─────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────┐
│ make install │
│ (per harness) │
└──────────────────┘
/ │ │ \
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ Claude │ │ Copilot │ │ OpenCode│ │ Pi │
│ Config │ │ Config │ │ Config │ │ Config │
└─────────┘ └─────────┘ └─────────┘ └─────────┘
│ │ │ │
└───────────┼───────────┼───────────┘
▼
┌────────────────────┐
│ Invoke your harness│
│ claude|copilot| │
│ opencode|pi │
└────────────────────┘
Framework → Configure → Deploy → Invoke. Each harness installs customized agents, skills, and routing logic for its provider.
How It Works
┌─────────────────┐
│ YOUR TASK │
└────────┬────────┘
│
▼
┌──────────────────────────┐
│ ORCHESTRATOR Agent │
│ (Haiku 4.5 • Routing) │
└────────┬─────────────────┘
│ DELEGATE
▼
┌──────────────────────────────────┐
│ Specialist Agents (Parallel) │
│ • Engineer (Haiku, impl) │
│ • Lead Eng (Sonnet, review) │
│ • Security Eng (Opus, audit) │
│ • Model Eng (optimize routing) │
└────────┬─────────────────────────┘
│ HANDBACK (results + metrics)
▼
┌──────────────────────────────────┐
│ Quality Gates & Feedback │
│ → Pass/Fail/Escalate │
│ → Cost tracking │
│ → Model optimization │
└────────┬─────────────────────────┘
│
▼
┌─────────────────┐
│ RESULTS │
│ Quality: 94/100│
│ Cost: $0.18 │
│ Time: 4.2s │
└─────────────────┘
Example:
opencode --agent orchestrator "Fix the GitHub Actions timeout in .github/workflows/ci.yml"
→ Orchestrator routes to Engineer (well-scoped fix)
→ Engineer executes, measures quality + cost
→ Returns: HANDBACK {status, quality_score, cost, changes}
→ Quality gate validates (≥92/100 required)
→ Results in ~/.agentic-engineers/queue/done/ ✅
8 Specialized Roles
| Role | Model | Effort | Purpose |
|---|---|---|---|
| Orchestrator | claude-haiku-4.5 | Low | Routes all work via decision tree; never does work itself |
| Engineer | claude-haiku-4.5 | High | Executes well-scoped, pre-planned tasks |
| Model Engineer | claude-sonnet-4.5 | Medium | Analyzes metrics; optimizes routing and model selection |
| Quality Engineer | claude-sonnet-4.6 | Medium | Post-implementation validation; model suitability assessment |
| Lead Engineer | claude-sonnet-4.6 | High | Code review (8-point checklist); architectural guidance |
| Senior Engineer | claude-sonnet-4.6 | High | Analyzes unscoped work; produces detailed plans |
| Principal Engineer | claude-opus-4.7 | High | Cross-service architecture; major refactors |
| Security Engineer | claude-opus-4.8 | Max | Threat modeling; vulnerability assessment |
Cost Breakdown:
- Haiku: $0.03–$0.05 per task — Routing, well-scoped implementation
- Sonnet: $0.09 per task — Planning, review, quality, optimization
- Opus: $0.15 per task — Complex architecture, security analysis
Effort Levels:
- Low: Minimal reasoning, direct execution (Orchestrator routing)
- Medium: Balanced reasoning and exploration (QE validation, Model Engineer analysis)
- High: Deep reasoning, multiple approaches considered (Engineers, Leads, Architects)
- Max: Unconstrained reasoning, full exploration (Security analysis, threat modeling)
💡 Model Selection: Each role maps to provider-specific equivalents (GPT-4o, Gemini, Llama) — see Multi-Model Support below. For thinking mode details, see docs/guides/thinking-modes-and-cost-quality-trade-offs.md.
Quick Start
Installation (Choose Your Harness)
All harnesses are configured by default to use Anthropic Claude models. Install to any or all:
# All harnesses (recommended)
make install
# Or install individual harnesses:
make install-opencode # OpenCode CLI (recommended for production)
make install-copilot # Copilot CLI
make install-claude # Claude Code (IDE)
make install-pi # π.dev (experimental)
By default the framework installs under your home directory ($HOME). To install into an alternate root — for sandboxed or end-to-end testing without touching your real config — pass DESTDIR:
DESTDIR=/tmp/test-install make install-opencode
Using the Orchestrator
The Orchestrator is the single entry point for all work. It routes tasks to specialist agents based on complexity and type:
# OpenCode (recommended)
opencode --agent orchestrator "Your task description"
# Copilot CLI
copilot --agent orchestrator "Your task description"
# Claude Code
# Paste the orchestrator system prompt into Claude's settings, then:
# "Your task description"
Example Tasks:
opencode --agent orchestrator "Fix the CI/CD timeout in .github/workflows/ci.yml"
opencode --agent orchestrator "Add authentication to the API endpoints"
opencode --agent orchestrator "Review PR #42 for security issues"
opencode --agent orchestrator "Optimize token usage across all agents"
The orchestrator will:
- Parse the task
- Route to the appropriate specialist agent(s)
- Monitor progress via queue
- Aggregate results and metrics
- Report back to you
Extend the Framework
Add new agents or skills to customize the framework for your needs:
# Create a new agent role
python3 scripts/agent-creator.py --role "data-engineer" --model "claude-sonnet-4.6" --effort high
# Create a new skill
python3 scripts/skill-creator.py --name "database-migration" --category "infrastructure"
See docs/guides/agent-creation.md and docs/guides/skill-creation.md for detailed guides.
Key Features
- 🎯 Queue-Based Orchestration — Centralized task routing via DELEGATE/HANDBACK protocol
- ⚖️ Multi-Tier Model Selection — Haiku for execution, Sonnet for planning, Opus for architecture
- ✅ Quality Gates (3 Layers) — DELEGATE structure, task routing, HANDBACK validation
- 📊 Real-Time Metrics — Token tracking, quality scores, cost per task
- 🔄 Self-Improving Feedback Loops — Model Engineer optimizes routing based on metrics
- 🌐 Multi-Harness Support — OpenCode, Copilot, Claude, π.dev
- 🔐 Security by Default — Opus-tier Security Engineer for threat modeling
- 📚 Comprehensive Documentation — Protocol specs, guides, troubleshooting
Key Benefits & Discoveries
1. DELEGATE/HANDBACK Protocol Enforces Quality
Discovery: Structured handoff protocol (mandatory scope, plan, success_criteria) dramatically improves output quality and reduces rework.
Benefits:
- ✅ Higher Quality Output: 90+/100 average quality score (vs. 70-80 without protocol)
- ✅ Faster Turnaround: 40-60% reduction in task completion time (clear scope eliminates ambiguity)
- ✅ Fewer Iterations: 80% reduction in rework/escalations (success criteria prevent scope creep)
- ✅ Better Context: Structured context (files, dependencies, constraints) prevents false starts
Why It Works:
- Orchestrator must write clear scope before delegating (forces clarity)
- Engineer receives concrete plan with numbered steps (no guessing)
- Success criteria are testable (no subjective "looks good")
- HANDBACK includes metrics (quality score, tokens, duration) for continuous improvement
2. Token Efficiency: 40-60% Reduction via Smart Model Selection
Discovery: Well-scoped, pre-planned work can be executed by cheaper models (Haiku) with same quality as expensive models (Opus), but 60% cheaper.
Real-World Data:
- Haiku (claude-haiku-4.5): $0.03-$0.05 per task, 90+/100 quality when plan is clear
- Sonnet (claude-sonnet-4.6): $0.09 per task, needed for complex analysis and planning
- Opus (claude-opus-4.6/4.8): $0.15 per task, only for security/architecture decisions
Token Savings Example:
- Without protocol: All tasks → Opus (max reasoning) = $0.15 × 100 tasks = $15.00
- With protocol: Haiku (90 tasks) + Sonnet (8 tasks) + Opus (2 tasks) = $0.05×90 + $0.09×8 + $0.15×2 = $5.22
- Savings: 65% reduction ($9.78 saved)
3. Parallel Sub-Agent Execution at Scale
Discovery: Framework supports tens to hundreds of concurrent sub-agents with automatic result aggregation, enabling massive parallelization. opencode recommended.
Tested Capacity:
- ✅ Tens to hundreds of concurrent agents from single parent (observed in production)
- ✅ 100+ sub-agents in parallel delegation chains
- ✅ 5-tier deep hierarchies (parent → children → grandchildren → etc.)
- ✅ Automatic aggregation of quality scores, tokens, costs
Documentation
| Topic | Document | Description |
|---|---|---|
| Architecture | docs/ARCHITECTURE.md | Detailed framework architecture and decision rationale |
| Protocol | docs/PROTOCOL.md | DELEGATE/HANDBACK protocol specification |
| Harness Setup | docs/guides/harness-setup/ | Detailed setup guides for each harness |
| Agent Creation | docs/guides/agent-creation.md | How to create new agent roles |
| Skill Creation | docs/guides/skill-creation.md | How to create new skills |
| Cost Optimization | docs/COST-QUALITY-MATRIX.md | Cost-quality trade-offs and optimization strategies |
| Testing | docs/guides/troubleshooting.md | Testing strategy and troubleshooting |
| Market Comparison | docs/market-comparison.md | Comparison with CrewAI, LangGraph, AutoGen, etc. |
| Contributing | CONTRIBUTING.md | How to contribute to the project |
Support This Project
If Agentic Engineers saves you time, money, or complexity, consider supporting independent development:
| Bitcoin (On-Chain) | Lightning (Instant) |
|---|---|
![]() | ![]() |
| Pay what you like | Zero fee • Instant |
Support open-source development:
- NOSTR: npub1ydxa9ss3xkps49s2gck7lk6pptpx79uvh78p87ly8zg0setwaxps3edd7d
- LN: bluemouse1@primal.net
- BTC: bc1py8jw0s695nvx9efm7zfejjhxvzfx8m6q2zhxhyt8s6sukdh6wm9sy2nq0n
Every satoshi helps. Thank you for believing in open-source multi-agent systems. 🙏
Installation Verification
# 1. Complete framework verification
make test
# 2. All harness installation status
ls ~/.agentic-engineers/queue/ # Should show: incoming/ processing/ done/
# 3. Protocol docs installed (OpenCode example)
cat ~/.opencode/agents/orchestrator/SYSTEM.md # Should show orchestrator system prompt
# 4. Smoke tests
opencode --agent orchestrator --version # Should show version
opencode --agent orchestrator "echo 'Hello from orchestrator'" # Should route and execute
Multi-Model Support & Provider Routing
Every role has a canonical model tier (the primary recommendation) plus provider-specific equivalents that the render pipeline substitutes automatically. The single source of truth is src/config/models.yaml.
Role → Model Mapping (All Providers)
| Role | Canonical | Claude (Anthropic) | GitHub Copilot | OpenAI | Meta / Llama | |
|---|---|---|---|---|---|---|
| Orchestrator | Haiku | claude-haiku-4.5 | claude-haiku-4.5 | gpt-4o-mini | gemini-2.0-flash | llama-3-8b |
| Engineer | Haiku | claude-haiku-4.5 | claude-haiku-4.5 | gpt-4o-mini | gemini-2.0-flash | llama-3-8b |
| Quality Engineer | Sonnet | claude-sonnet-4.6 | claude-sonnet-4.6 | gpt-4-turbo | gemini-1-5-pro | llama-3-70b |
| Model Engineer | Sonnet | claude-sonnet-4.5 | claude-sonnet-4.5 | gpt-4-turbo | gemini-1-5-pro | llama-3-70b |
| Lead Engineer | Sonnet | claude-sonnet-4.6 | claude-sonnet-4.6 | gpt-4 | gemini-1-5-pro | llama-3-70b |
| Senior Engineer | Sonnet | claude-sonnet-4.6 | claude-sonnet-4.6 | gpt-4-turbo | gemini-1-5-pro | llama-3-70b |
| Principal Engineer | Opus | claude-opus-4.7 | claude-opus-4.7 | gpt-4o | gemini-2-pro | llama-3-405b |
| Security Engineer | Opus | claude-opus-4.8 | claude-opus-4.8 | gpt-4o | gemini-2-pro | llama-3-405b |
Why these model choices:
- Haiku / gpt-4o-mini / gemini-2.0-flash / llama-3-8b — cheapest tier, sufficient for deterministic routing and pre-planned execution
- Sonnet / gpt-4-turbo / gemini-1-5-pro / llama-3-70b — mid-tier, balances cost and capability for planning, review, and validation
- Opus / gpt-4o / gemini-2-pro / llama-3-405b — highest capability tier, required for architecture and security decisions
Provider Feature Deltas
Not all providers support every feature. The framework degrades gracefully:
| Feature | Claude (Anthropic) | GitHub Copilot | OpenAI | Meta/Llama | |
|---|---|---|---|---|---|
| Extended Thinking | ✅ Native | ✅ Native | ⚠️ Limited | ❌ Not supported | ❌ Not supported |
| Structured Output | ✅ | ✅ | ✅ | ✅ | ❌ Not guaranteed |
| Max Context | 200K tokens | 200K tokens | 128K tokens | 1M tokens | 128K tokens |
| Cost Tier | Premium | Premium | Premium | Standard | Budget/Free |
⚠️ Thinking mode on non-Claude providers: When deploying to OpenAI, Google, or Meta,
thinking: trueroles fall back to the best available reasoning of the target model.
See docs/guides/harness-setup/ for detailed harness configuration.
When to Use This System
✅ Use Agentic Engineers when:
- You need coordination across 8+ specialized AI agents
- You want quality gates and cost optimization built-in
- You need parallel sub-agent execution at scale (tens to hundreds concurrent)
- You want structured handoffs (DELEGATE/HANDBACK protocol)
- You need metrics and feedback loops for continuous improvement
❌ Consider alternatives when:
- You only need a single agent (use the provider's native API)
- You don't care about cost optimization (use Opus for everything)
- You don't need quality gates or structured validation
- You're building a chatbot or conversational AI (different problem domain)
See docs/market-comparison.md for detailed comparison with CrewAI, LangGraph, AutoGen, and other frameworks.
Supported Harnesses
| Harness | Description | Best For | Status |
|---|---|---|---|
| OpenCode | Primary harness for autonomous coordination | Production use, dark factory mode | ✅ Recommended |
| GitHub Copilot | GitHub's official CLI with CI/CD integration | GitHub workflows, team collaboration | ✅ Stable |
| Claude Code | Claude's native IDE and code editor | Interactive development, prototyping | ✅ Stable |
| π.dev | Experimental harness with emerging features | Early adopters, experimentation | ⚠️ Beta |
See docs/guides/harness-setup/ for detailed setup guides per harness.
Contributing
We welcome contributions! See CONTRIBUTING.md for guidelines.
Key Areas:
- Harness integrations — Add support for new AI coding harnesses
- Agent roles — Design new specialist agents for specific domains
- Skills — Create reusable skills for common tasks
- Testing — Expand test coverage and evaluation framework
- Documentation — Improve guides, examples, and troubleshooting
License
MIT License — see LICENSE for details.
Acknowledgments
Built with inspiration from:
- CrewAI — Multi-agent orchestration patterns
- LangGraph — State machine design for AI workflows
- AutoGen — Agent communication protocols
- OpenAI Agents SDK — Structured agent design
Special thanks to the open-source AI community for pushing the boundaries of what's possible with multi-agent systems.
⭐ If this project helps you, please star the repository and share with others!

