convez.ai
SkillAutomaçãoAvançado
niallyoung

Agentic Engineers

niallyoung/agentic-engineers

Orquestrador de agentes especializados com gates de qualidade e otimização de tokens

Ver no GitHub
InicialPluginScore · de 0 a 100

Framework 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-engineers

1 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

Estrelas
4
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 1 semana
Versão
v0.46.2
Issues abertas
2
Contribuidores
1

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:

  1. All work enters a queue as DELEGATE tasks (SPEC-compliant YAML)[1]
  2. Orchestrator polls and routes to the right specialist
  3. Each agent returns a HANDBACK with results + metrics
  4. Quality gates validate all work before moving to done
  5. Metrics feed back into model selection and routing optimization

[1] oops, soon with "actually works again" 🤦‍♂️ 20260609 PR on its way

Key Benefits

  1. 90+/100 Quality — Structured DELEGATE/HANDBACK protocol enforces clarity
  2. 65% Cost Savings — Smart model selection (Haiku for execution, Opus for architecture)
  3. 40-60% Faster — Parallel sub-agent execution at scale
  4. 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

RoleModelEffortPurpose
Orchestratorclaude-haiku-4.5LowRoutes all work via decision tree; never does work itself
Engineerclaude-haiku-4.5HighExecutes well-scoped, pre-planned tasks
Model Engineerclaude-sonnet-4.5MediumAnalyzes metrics; optimizes routing and model selection
Quality Engineerclaude-sonnet-4.6MediumPost-implementation validation; model suitability assessment
Lead Engineerclaude-sonnet-4.6HighCode review (8-point checklist); architectural guidance
Senior Engineerclaude-sonnet-4.6HighAnalyzes unscoped work; produces detailed plans
Principal Engineerclaude-opus-4.7HighCross-service architecture; major refactors
Security Engineerclaude-opus-4.8MaxThreat 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:

  1. Parse the task
  2. Route to the appropriate specialist agent(s)
  3. Monitor progress via queue
  4. Aggregate results and metrics
  5. 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

TopicDocumentDescription
Architecturedocs/ARCHITECTURE.mdDetailed framework architecture and decision rationale
Protocoldocs/PROTOCOL.mdDELEGATE/HANDBACK protocol specification
Harness Setupdocs/guides/harness-setup/Detailed setup guides for each harness
Agent Creationdocs/guides/agent-creation.mdHow to create new agent roles
Skill Creationdocs/guides/skill-creation.mdHow to create new skills
Cost Optimizationdocs/COST-QUALITY-MATRIX.mdCost-quality trade-offs and optimization strategies
Testingdocs/guides/troubleshooting.mdTesting strategy and troubleshooting
Market Comparisondocs/market-comparison.mdComparison with CrewAI, LangGraph, AutoGen, etc.
ContributingCONTRIBUTING.mdHow 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)
Bitcoin QRLightning QR
Pay what you likeZero 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)

RoleCanonicalClaude (Anthropic)GitHub CopilotOpenAIGoogleMeta / Llama
OrchestratorHaikuclaude-haiku-4.5claude-haiku-4.5gpt-4o-minigemini-2.0-flashllama-3-8b
EngineerHaikuclaude-haiku-4.5claude-haiku-4.5gpt-4o-minigemini-2.0-flashllama-3-8b
Quality EngineerSonnetclaude-sonnet-4.6claude-sonnet-4.6gpt-4-turbogemini-1-5-prollama-3-70b
Model EngineerSonnetclaude-sonnet-4.5claude-sonnet-4.5gpt-4-turbogemini-1-5-prollama-3-70b
Lead EngineerSonnetclaude-sonnet-4.6claude-sonnet-4.6gpt-4gemini-1-5-prollama-3-70b
Senior EngineerSonnetclaude-sonnet-4.6claude-sonnet-4.6gpt-4-turbogemini-1-5-prollama-3-70b
Principal EngineerOpusclaude-opus-4.7claude-opus-4.7gpt-4ogemini-2-prollama-3-405b
Security EngineerOpusclaude-opus-4.8claude-opus-4.8gpt-4ogemini-2-prollama-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:

FeatureClaude (Anthropic)GitHub CopilotOpenAIGoogleMeta/Llama
Extended Thinking✅ Native✅ Native⚠️ Limited❌ Not supported❌ Not supported
Structured Output✅✅✅✅❌ Not guaranteed
Max Context200K tokens200K tokens128K tokens1M tokens128K tokens
Cost TierPremiumPremiumPremiumStandardBudget/Free

⚠️ Thinking mode on non-Claude providers: When deploying to OpenAI, Google, or Meta, thinking: true roles 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

HarnessDescriptionBest ForStatus
OpenCodePrimary harness for autonomous coordinationProduction use, dark factory mode✅ Recommended
GitHub CopilotGitHub's official CLI with CI/CD integrationGitHub workflows, team collaboration✅ Stable
Claude CodeClaude's native IDE and code editorInteractive development, prototyping✅ Stable
π.devExperimental harness with emerging featuresEarly 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!

Ver o original no GitHub

Bom para

Relacionados