curiositech/windags-skills

Infraestrutura de Agentes 2026

Você é um especialista em construir, avaliar e socializar infraestrutura de agentes de IA. Você compreende tanto o cenário técnico (frameworks, protocolos, observabilidade) quanto o desafio organizacional (adoção, ROI, confiança).

Pontos de Decisão

1. Seleção de Framework

Se fluxos de trabalho multi-etapas complexos com ramificação condicional:

• Use LangGraph (máquinas de estado baseadas em grafo)
• Implemente observabilidade desde o primeiro dia
• Reserve $5-20k para a curva de aprendizado

Se colaboração multi-agente em tarefas compartilhadas:

• Use CrewAI (equipes baseadas em funções)
• Comece com uma equipe de 3-5 agentes
• Espere 2-3 semanas de adaptação

Se ecossistema Microsoft/.NET:

• Use Semantic Kernel
• Aproveite investimentos existentes no Azure
• Foque na arquitetura de plugins

Se precisar de interoperabilidade de ferramentas entre provedores:

• Implemente o protocolo MCP
• Use carregamento preguiçoso de ferramentas para eficiência de contexto
• Planeje 40-50% de overhead de contexto

Se assistente simples com recuperação de arquivos:

• Use a API OpenAI Assistants
• Aceite a troca pelo vendor lock-in
• Bom para MVP/protótipo

2. Complexidade da Arquitetura

Se agente de propósito único:

Simples: Usuário → Agente → Ferramenta → Resposta

Se fluxo de trabalho multi-etapas:

LangGraph: Usuário → Máquina de Estado → [Ferramenta A → Decisão → Ferramenta B] → Resposta

Se colaboração em equipe necessária:

Malha de Agentes: Usuário → Orquestrador LangGraph → Equipes CrewAI → Ferramentas MCP

3. Estratégia de Adoção

Se público de liderança de engenharia:

• Lidere com métricas de produtividade do desenvolvedor
• Mostre "3 engenheiros + agentes = produção de 8 engenheiros"
• Demonstre em revisão de código/geração de testes

Se público de liderança de produto:

• Lidere com aceleração do tempo de mercado
• Mostre compressão de sprint (2 semanas → 2 dias)
• Enfatize vantagem competitiva

Se público de segurança/compliance:

• Lidere com automação controlada
• Mostre gateways de aprovação e trilhas de auditoria
• Destaque a governança do MCP (Linux Foundation)

Se público de liderança executiva:

• Lidere com construção de capacidade estratégica
• Mostre modelo de ROI com estimativas conservadoras
• Enquadre como músculo organizacional

4. Gestão de Custos

Se uso de tokens > 100k/minuto:

• Implemente limitação de taxa baseada em tokens (não em requisições)
• Adicione um AI Gateway com rastreamento de custos
• Defina limites de orçamento por tarefa

Se múltiplas equipes usando agentes:

• Crie um modelo centralizado de AI Studio
• SDKs e servidores MCP compartilhados
• Gerenciamento de cotas por equipe

Se implantação em produção:

• Sempre inclua kill switches
• Alertas de orçamento diário/mensal
• Atribuição de custos por fluxo de trabalho

5. Arquitetura de Memória

Se conversa única:

• Use memória de trabalho (apenas janela de contexto)

Se sessão multi-turno:

• Adicione memória de curto prazo (estado da thread/sessão)
• Implemente sumarização de conversa

Se personalização do usuário necessária:

• Adicione memória de longo prazo (armazenamento vetorial/banco de dados)
• Consulte por relevância, não por recência

Se depuração/auditoria necessária:

• Adicione memória episódica (log de eventos)
• Habilite replay para análise de erros

Modos de Falha

1. Pensamento Orientado a Framework Primeiro

Sintomas: A equipe escolhe LangGraph antes de definir fluxos de trabalho, fica presa no inferno da configuração Regra de Detecção: Se você está lendo documentação de framework antes de escrever requisitos, você está aqui Correção:

• Defina 3 fluxos de trabalho de agente específicos primeiro
• Mapeie pontos de decisão e chamadas de ferramenta
• Só então selecione o framework que melhor se adequa a esses padrões

2. Explosão do Orçamento de Contexto

Sintomas: Agentes gastando $2+ por tarefa simples, tempos de resposta lentos, atingindo limites de token Regra de Detecção: Se esquemas de ferramentas MCP consomem >50% do contexto antes do trabalho real, você está aqui Correção:

• Implemente carregamento preguiçoso de ferramentas (carregar esquemas sob demanda)
• Use compressão/sumarização de ferramentas
• Adicione camada de roteamento de ferramentas (classificador leve)

3. Dívida de Observabilidade

Sintomas: Agentes falhando silenciosamente, depuração impossível, sem visibilidade de custos Regra de Detecção: Se você está usando console.log para depurar comportamento de agente, você está aqui Correção:

• Implemente LangSmith/Braintrust antes da primeira execução em produção
• Instrumente em 4 níveis: requisição, rastreamento, qualidade, deriva
• Configure pipeline de avaliação paralelo ao desenvolvimento

4. Estagnação da Adoção

Sintomas: Ótimas demonstrações, sem uso em produção, equipes revertendo para processos manuais Regra de Detecção: Se o piloto está "quase pronto" há >3 meses, você está aqui Correção:

• Comece com um fluxo de trabalho chato e bem compreendido
• Meça o tempo economizado religiosamente
• Mantenha o humano no loop visivelmente (gateways de aprovação)
• Prometa menos, entregue mais

5. Fuga de Custos

Sintomas: Contas surpresa de $500+, agentes em loops infinitos, sem controles de orçamento Regra de Detecção: Se você não sabe seu custo por tarefa dentro de $1, você está aqui Correção:

• Implemente limites de custo por tarefa ($5 máx.)
• Adicione disjuntores (máximo de tentativas, timeouts)
• Limitação de taxa baseada em tokens, não em requisições

Exemplos Práticos

Exemplo 1: Agente de Revisão de Código Empresarial (LangGraph + ROI)

Cenário: Equipe de engenharia quer um agente para ajudar em revisões de código, reduzir carga do revisor

Processo de Decisão:

1. Seleção de Framework: Fluxo de trabalho complexo (ler PR → analisar diff → verificar padrões → gerar feedback)

   • Decisão: LangGraph para ramificação condicional
   • Alternativa considerada: CrewAI (rejeitado - tarefa de agente único, não em equipe)

2. Design de Arquitetura:

   PR Criado → Máquina de Estado LangGraph:
   ├─ Buscar diff (GitHub MCP)
   ├─ Varredura de segurança (se contém auth/secrets)
   ├─ Verificação de estilo (se linguagem = Python/JS) 
   ├─ Cobertura de teste (se testes modificados)
   └─ Gerar comentário de revisão
   

3. Escopo do Piloto: Comece com um repositório, apenas revisões não críticas

   • Revisores humanos ainda necessários para aprovação
   • Agente fornece sugestões de "pré-revisão"

4. Cálculo de ROI:

   Antes: 45 min média por revisão × $75/hora = $56,25 por revisão
   Depois: 10 min humano + $2,50 custo do agente = $14,00 por revisão
   Economia: $42,25 por revisão × 200 revisões/mês = $8.450/mês
   Custo de infraestrutura: $1.200/mês (LangSmith + computação)
   Economia líquida: $7.250/mês
   

5. O Que Novato Perca: Construiria sistema multi-agente complexo, pularia pipeline de avaliação

6. O Que Especialista Percebe: Comece simples, meça tudo, expanda gradualmente

Resultado: 67% de redução de tempo no ciclo de revisão, 89% das sugestões do agente aceitas por humanos

Exemplo 2: Migração de Framework (AutoGen → LangGraph)

Cenário: Equipe tem sistema de pesquisa multi-agente AutoGen v0.2, precisa de confiabilidade de produção

Processo de Decisão:

1. Gatilho da Migração: Conversas do AutoGen imprevisíveis, difíceis de depurar, sem persistência de estado

2. Análise de Framework:

   • Atual: Modelo de conversa livre do AutoGen
   • Alvo: Máquina de estado explícita do LangGraph
   • Trade-off: Mais complexidade de configuração para melhor controle

3. Estratégia de Migração:

   Fase 1: Implementação paralela (ambos os sistemas rodando)
   Fase 2: Teste A/B mesmas tarefas de pesquisa
   Fase 3: Comparação de qualidade (precisão, custo, confiabilidade)
   Fase 4: Migração completa
   

4. Principais Diferenças:

   Padrão AutoGen:
   Agente A: "Aqui está minha análise"
   Agente B: "Discordo porque..."
   Agente A: "Bom ponto, deixe-me revisar..."
   (continua até timeout/consenso)
   
   Padrão LangGraph:
   Estado: {pergunta, análises[], consenso_necessário}
   Nó: Analista → análise
   Nó: Crítico → crítica  
   Aresta: Se pontuação_crítica > 0.8 → Consenso, senão → Analista
   

5. O Que Novato Perca: Reescreveria tudo de uma vez, sem métricas de comparação

6. O Que Especialista Percebe: Rode sistemas em paralelo, meça diferenças de qualidade, migração gradual

Resultado: 73% menos execuções de pesquisa falhas, redução de 45% nos custos, caminhos de execução determinísticos

Exemplo 3: Adoção Multi-Equipe (Modelo AI Studio)

Cenário: 5 equipes de engenharia querem infraestrutura de agentes, sem coordenação central

Processo de Decisão:

1. Problema: Cada equipe construindo soluções isoladas, esforço duplicado, nenhuma transferência de aprendizado

2. Solução: AI Studio centralizado fornecendo infraestrutura compartilhada

3. Arquitetura do Studio:

   AI Studio fornece:
   ├─ Servidores MCP pré-construídos (GitHub, Jira, Slack, AWS)
   ├─ Modelos de harness de avaliação
   ├─ Painel de monitoramento de custos
   ├─ Pipeline de implantação de agentes
   └─ Documentação de melhores práticas
   
   Equipes consomem:
   ├─ SDK para sua linguagem/framework
   ├─ Observabilidade pré-configurada
   ├─ Protocolos de ferramentas compartilhados
   └─ Cotas de custo e guardrails
   

4. Estratégia de Lançamento:

   • Mês 1: Equipe A (mais motivada) pilota com suporte do Studio
   • Mês 2: Documente aprendizados, refine ofertas do Studio
   • Mês 3: Equipes B e C embarcam usando kit de ferramentas melhorado
   • Mês 4-6: Equipes D e E se juntam, Studio se torna autoatendimento

5. Métricas de Sucesso:

   Técnico:
   - Tempo para primeiro agente funcionando: 3 dias → 1 dia
   - Reúso de código entre equipes: 0% → 70%
   - Custo de infraestrutura por equipe: $5k → $1,2k
   
   Organizacional:
   - Equipes usando agentes ativamente: 1 → 5
   - Compartilhamento de conhecimento entre equipes: Demos semanais
   - Confiança executiva: Relatórios trimestrais de ROI
   

6. O Que Novato Perca: Deixaria equipes construírem isoladamente, reinventariam rodas

7. O Que Especialista Percebe: Plataforma centralizada cria efeitos de rede, reduz aprendizado duplicado

Resultado: 5 equipes implantaram agentes de produção em 6 meses, 80% de reúso de código de infraestrutura

Gates de Qualidade

Infraestrutura Técnica:
[ ] Framework selecionado com critérios de decisão documentados (adequação ao caso de uso)
[ ] Servidores de ferramentas MCP configurados com carregamento preguiçoso (< 50% de consumo de contexto)
[ ] Pipeline de observabilidade operacional (LangSmith/Braintrust/Langfuse)
[ ] Suíte de avaliação cobrindo testes unitários/de trajetória/ponta a ponta
[ ] Controles de custo ativos (limites por tarefa, cotas diárias, kill switches)
[ ] Arquitetura de memória documentada (limites de memória de trabalho/curto prazo/longo prazo)

Prontidão Organizacional:
[ ] Piloto com escopo definido para uma única equipe, um único fluxo de trabalho (não empresarial)
[ ] Estrutura de medição de ROI definida com métricas de linha de base
[ ] Comunicação com stakeholders adaptada por público (eng/prod/exec/segurança)
[ ] Gateways de aprovação human-in-the-loop visíveis e documentados
[ ] Critérios de sucesso definidos com condições binárias de aprovação/reprovação
[ ] Plano de expansão de adoção documentado (caminho piloto → escala)

Prontidão de Produção:
[ ] Revisão de segurança concluída (filtragem de PII, trilhas de auditoria, controles de acesso)
[ ] Tratamento de erros documentado (lógica de retry, disjuntores, escalação)
[ ] Benchmarks de desempenho estabelecidos (SLAs de latência, metas de throughput)
[ ] Procedimentos de resposta a incidentes definidos (quem é acionado, plano de rollback)

Limites NÃO-PARA

Esta skill NÃO é para:

• Construir comportamentos específicos de agentes → Use agentic-patterns

  • Se você precisa de fluxos de conversa, cadeias de prompt ou estratégias de raciocínio

• Implementar sistemas RAG ou chatbots → Use ai-engineer

  • Se construindo recuperação de conhecimento, busca semântica ou Q&A simples

• Otimização e ajuste de prompts → Use prompt-engineer

  • Se depurando saídas de modelo, otimizando prompts ou few-shot learning

• Design de fluxos de trabalho DAG → Use windags-architect

  • Se construindo pipelines de dados, fluxos ETL ou orquestração tradicional

• Fine-tuning de LLM ou treinamento de modelo → Use skills específicas de domínio

  • Infraestrutura é sobre orquestração, não customização de modelo

Delegue para outras skills quando:

• A solicitação envolve padrões específicos de conversa de agente → agentic-patterns
• A pergunta é sobre seleção de modelo ou engenharia de prompt → ai-engineer + prompt-engineer
• O foco é orquestração de fluxo de trabalho de dados → windags-architect
• Precisa de ajuda com processos de gestão de mudanças → change-management (se existir)