Orkestra: Orquestrando Agentes de IA em Escala

Os números neste post refletem o sistema no momento da publicação (janeiro de 2026). Consulte nossa página da equipe para números atualizados.

Quando começamos a construir com o Claude Code, esbarramos em um problema que toda equipe que usa assistentes de codificação com IA acaba enfrentando: um único agente não consegue fazer tudo bem.

Você pode instruir um agente a ser um especialista em banco de dados. Ou um auditor de segurança. Ou um engenheiro de frontend. Mas no momento em que você pede que ele seja os três ao mesmo tempo, a qualidade sofre. O contexto se dilui. As instruções entram em conflito. O agente se torna um generalista medíocre em tudo.

Então construímos o Orkestra.

O que é o Orkestra?

O Orkestra é um sistema de orquestração de agentes para o Claude Code e ferramentas de codificação com IA semelhantes. Ele coordena vários agentes especializados, cada um com expertise distinta, sob um único orquestrador que roteia o trabalho para o especialista certo.

Pense nele como uma agência de recrutamento para agentes de IA. O orquestrador recebe uma tarefa, identifica qual especialista deveria tratá-la, e delega com o contexto certo. Quando o trabalho termina, os resultados voltam ao orquestrador para síntese.

Os números contam a história:

Componente	Quantidade
Agentes especialistas	46
Skills reutilizáveis	466
Arquétipos de identidade	27
Mindsets	11
Estilos de comunicação	10
Domínios de conhecimento	21

O Sistema de Personagens: D&D para Agentes

O insight central por trás do Orkestra é que o comportamento do agente emerge de três primitivas combináveis:

Identidade define o que o agente é. Um arquiteto projeta estruturas de sistema. Um debugger rastreia falhas até a causa raiz. Um guardião aplica conformidade e limites de segurança. Temos 27 arquétipos de identidade que podem ser combinados.

Mindset define como o agente pensa. Um mindset analítico fundamenta afirmações em evidências e quantifica incerteza. Um mindset cético questiona suposições e busca evidências que desconfirmem. Um mindset exploratório abraça a ambiguidade e tenta múltiplas abordagens.

Estilo define como o agente se comunica. Um estilo técnico inclui valores exatos e referencia arquivos específicos. Um estilo conciso corta enrolação e começa pela resposta. Um estilo diplomático equilibra honestidade com tato.

Um agente combina essas primitivas:

# architecture-advisor.yaml
identity:
  - knowledge-architect
  - architect
  - strategist
mindset: analytical
style: concise

Essa composição cria um agente que projeta sistemas (architect), conecta conhecimento entre domínios (knowledge-architect), define direção estratégica (strategist), pensa em evidências e dados (analytical), e se comunica sem enrolação (concise).

O poder está na explosão combinatória. 27 identidades vezes 11 mindsets vezes 10 estilos rendem quase 3.000 personalidades de agente possíveis. Mas você só define as combinações que importam para o seu trabalho.

Skills: Módulos de Capacidade Reutilizáveis

Skills são o conhecimento e os workflows que os agentes podem invocar. Elas seguem um sistema em camadas baseado em escopo:

Camada	Nome	Escopo	Exemplo
K0	Fundamentos	Metodologia universal	Disciplina test-first, conclusão baseada em evidências
K1	Identidades	Workflows baseados em papel	Padrões de interface de CLI, playbook de performance
K2	Domínios	Conhecimento específico de domínio	Padrões de migração de banco de dados, validação de autenticação
K3	Stacks	Específico de tecnologia	Deploy no Cloudflare, operações no Supabase
K4	Projeto	Apenas este codebase	Workflows e convenções específicos do projeto

As skills são carregadas sob demanda (lazy-loaded). Um agente vê os nomes e descrições das skills na inicialização, mas o conteúdo completo da skill só carrega quando acionado. Isso mantém o contexto enxuto, ao mesmo tempo em que torna centenas de skills descobríveis.

Cada skill inclui:

• Condições de acionamento claras (“Use ao migrar schemas de banco de dados”)
• Orientação passo a passo
• Ferramentas permitidas para o workflow
• Critérios de sucesso e caminhos de recuperação de falha

As 466 skills no nosso registro cobrem desde isolamento de worktree do git até workflows de pesquisa web e validação de saúde de deploy.

Por Que a Orquestração Importa

Arquiteturas de agente único esbarram em paredes rapidamente:

Diluição de contexto. Uma janela de contexto de 200 mil tokens parece grande até você carregar schemas de banco de dados, docs de API, fixtures de teste e conhecimento de domínio. Especialistas conseguem trabalhar com contexto direcionado.

Conflitos de instrução. Dizer a um agente para “ser minucioso mas rápido” e “verificar tudo mas não superengenheirar” cria tensão. Especialistas resolvem isso tendo escopo claro.

Profundidade de expertise. Um agente generalista sabe um pouco de tudo. Um agente especialista, composto com a identidade e as skills certas, conhece o seu domínio profundamente.

O Orkestra implementa orquestração plana: um orquestrador coordena vários especialistas. Especialistas não podem gerar subespecialistas. Isso evita a explosão de complexidade, ao mesmo tempo em que viabiliza trabalho paralelo.

O orquestrador tem acesso a 2,2 milhões de tokens de capacidade efetiva: a sua própria janela de 200 mil mais 10 subagentes concorrentes com 200 mil cada. Um trabalho que esgotaria um único agente roda confortavelmente em toda a frota.

O Pipeline de Renderização

As definições de agente vivem em YAML. O Claude Code lê Markdown. O Orkestra conecta essa lacuna com um pipeline de renderização determinístico:

YAML Registries → Jinja Templates → .claude/agents/*.md

Os operadores editam a fonte YAML. Rodam orkestra sync. O Markdown renderizado aparece em .claude/agents/. O Claude Code capta as mudanças.

Essa separação atende a públicos diferentes:

• A fonte YAML inclui metadados de ciclo de vida, tags, regras de validação e notas de descontinuação para ferramentas
• O Markdown renderizado inclui apenas o que o modelo precisa: descrição, ferramentas, skills e orientação comportamental

O pipeline compõe identidades, mindsets, estilos e skills em um único prompt coerente. Um agente architect-analytical-concise recebe um system prompt muito diferente de um agente debugger-skeptical-technical, mesmo que compartilhem algumas skills subjacentes.

Conhecimento de Domínio: O Padrão de Quatro Arquivos

Cada domínio de conhecimento segue uma estrutura consistente:

domain-name/
  decisions.md      # Key choices, rationale, consequences
  patterns.md       # Step-by-step guidance and examples
  anti-patterns.md  # Failure modes and remediation
  evolution.md      # Dated log of changes

Essa estrutura serve ao carregamento de contexto do agente. Um agente trabalhando em autenticação carrega authentication/patterns.md para orientação e authentication/anti-patterns.md para evitar armadilhas conhecidas. Os arquivos têm tamanho pensado para carregamento eficiente de contexto: focados o suficiente para serem úteis, abrangentes o suficiente para serem autoritativos.

Mantemos 21 domínios de nível superior, incluindo analytics, autenticação, ciência de dados, infraestrutura, machine learning, performance, segurança e mais. Cada domínio pode ter subdomínios para granularidade mais fina.

Valores: O Sistema Operacional

Todos os agentes compartilham uma camada base de valores que define como eles operam:

Simplicidade primeiro. Use a solução mais simples que funcione. Adicione complexidade apenas quando justificado.

Corrija causas raiz. Nunca aplique remendos em torno de falhas. Se um pipeline falha, depure o pipeline. Se um teste falha, corrija o código ou o teste.

Baseado em evidências. Rotule afirmações como “verificado” (com benchmarks) ou “estimado” (com suposições). Padrão detectado não é o mesmo que problema confirmado.

Economia de contexto. Ferramentas MCP custam 0,1% do contexto. Leituras de arquivo custam 2% cada. Aplique expertise de domínio antes de explorar código.

Esses valores se propagam para cada especialista através do pipeline de renderização. Um agente não pode contorná-los por composição.

CLI: O Plano de Controle

O Orkestra vem com uma CLI para gerenciar o ecossistema de agentes:

# Discovery
orkestra agents search "database"
orkestra agents info database-architect

# Validation
orkestra validate --show-warnings

# Rendering
orkestra sync --dry-run
orkestra sync

# Skills
orkestra skills list
orkestra skills info schema-migration-workflow

# Decisions
orkestra decisions search "authentication"

A CLI é a fonte da verdade para quais agentes existem, quais skills eles têm, e se o sistema está saudável. Ela roda validação antes da sincronização para pegar problemas cedo.

Considerações Sobre Código Aberto

Construímos o Orkestra para resolver o nosso próprio problema: coordenar agentes de IA em escala para um codebase complexo. Os padrões que descobrimos não são específicos do nosso domínio.

O sistema de composição de personagem (identidade + mindset + estilo) se aplica a qualquer equipe que defina personalidades de agente.

O sistema de camadas de skill (K0-K4) fornece um modelo mental para organizar capacidades reutilizáveis por escopo.

O padrão de pipeline de renderização (fonte YAML + templates + artefatos gerados) separa responsabilidades entre ferramentas e consumo pelo modelo.

O modelo de orquestração plana (um coordenador, muitos especialistas) evita complexidade, ao mesmo tempo em que viabiliza paralelismo.

Se o Orkestra vai se tornar código aberto depende de se esses padrões têm valor para outras pessoas construindo com o Claude Code. Se você está esbarrando nas paredes que descrevemos, a arquitetura pode ajudar.

O Que Aprendemos

Construir o Orkestra nos ensinou que orquestração não é sobre tornar os agentes mais inteligentes. É sobre torná-los mais focados.

Um único agente com instruções perfeitas ainda fica sem contexto. Um único agente com todas as skills ainda fica confuso sobre qual aplicar. Um único agente tentando ser tudo produz resultados medíocres em tudo.

Quarenta especialistas, cada um excelente em seu domínio, coordenados por um orquestrador que sabe quando delegar: é assim que entregamos.

Os números importam menos do que a arquitetura. Você pode precisar de cinco agentes ou de cinquenta. O princípio permanece: composição acima de capacidade, especialização acima de generalização, coordenação acima de heroísmo individual.

---

O Orkestra move o ecossistema de agentes por trás do Maguyva, a nossa plataforma de inteligência de código. Quer saber mais? Entre em contato com a equipe.