O Que São Agentes de Agência?

A Agency é uma coleção de código aberto de 147 agentes de IA especializados para Claude Code, Cursor, Aider, Windsurf, GitHub Copilot e muito mais. Cada agente tem uma personalidade distinta, entregas técnicas e métricas de sucesso. Este aprofundamento técnico aborda a arquitetura do agente, integração multi-ferramentas, memória MCP e os scripts bash que alimentam tudo isso.

Você provavelmente conhece a rotina: "Atue como um desenvolvedor sênior" seguido de conselhos genéricos que poderiam se aplicar a qualquer tarefa de codificação. A Agency adota uma abordagem diferente. Em vez de um prompt tentando fazer tudo, ela oferece 147 especialistas organizados em 12 divisões.

Pense nisso como montar uma agência de serviço completo, exceto que são agentes de IA que nunca dormem, nunca reclamam e sempre entregam.

O Que É A Agency?

A versão curta: A Agency substitui "Atue como um desenvolvedor" por "Ativar modo Desenvolvedor Frontend" — e o agente Desenvolvedor Frontend realmente conhece React, Vue, Angular, Core Web Vitals e conformidade de acessibilidade.

Estrutura do Repositório: 12 Divisões, 147 Agentes

A Agency reside em github.com/msitarzewski/agency-agents. Os agentes são organizados em 12 divisões espelhando um organograma de agência real:

agency-agents/
├── engineering/          # 20+ agentes: Frontend, Backend, DevOps, AI, Mobile, Segurança
├── design/               # 8 agentes: Designer de UI, Pesquisador de UX, Guardião da Marca, Injetor de Humor
├── marketing/            # 20+ agentes: Growth Hacker, SEO, TikTok, Reddit, LinkedIn
├── sales/                # 8 agentes: Coach de Descoberta, Estrategista de Negócios, Engenheiro de Vendas
├── product/              # 5 agentes: Gerente de Produto, Pesquisador de Tendências, Sintetizador de Feedback
├── project-management/   # 6 agentes: Produtor de Estúdio, Pastor de Projetos, Rastreador de Experimentos
├── testing/              # 8 agentes: Verificador de Realidade, Coletor de Evidências, Testador de API
├── support/              # 6 agentes: Responsável por Suporte, Analista de Relatórios, Conformidade Legal
├── spatial-computing/    # 6 agentes: Arquiteto XR, Engenheiro visionOS, Desenvolvedor Metal
├── specialized/          # 30+ agentes: Construtor de MCP, Auditor de Blockchain, Auditor de Conformidade
├── game-development/     # 20+ agentes: Arquiteto Unity, Sistemas Unreal, Scripter Godot, Roblox
└── academic/             # 5 agentes: Antropólogo, Historiador, Psicólogo, Narratologista

Cada divisão contém agentes com profunda expertise. A divisão de Engenharia sozinha abrange Desenvolvedores Frontend, Arquitetos Backend, Automatizadores DevOps, Engenheiros de Segurança e até Engenheiros de Firmware Embutido.

Anatomia do Agente: Por Dentro de um Especialista em IA de 400 Linhas

Todo agente segue a mesma estrutura. Aqui está a análise usando o agente Arquiteto Backend como exemplo:

Frontmatter (YAML)

---
name: Backend Architect
description: Arquiteto backend sênior especializado em design de sistemas escaláveis, arquitetura de banco de dados, desenvolvimento de API e infraestrutura em nuvem
color: blue
emoji: 🏗️
vibe: Projeta os sistemas que sustentam tudo — bancos de dados, APIs, nuvem, escala.
---

Essa metadados não são decorativos. Ferramentas como Cursor e Claude Code usam os campos name e description para descoberta de agentes. O emoji fornece identificação visual em interfaces de chat.

Identidade e Memória

## 🧠 Sua Identidade e Memória
- **Função**: Especialista em arquitetura de sistema e desenvolvimento server-side
- **Personalidade**: Estratégico, focado em segurança, com mentalidade de escalabilidade, obcecado por confiabilidade
- **Memória**: Você se lembra de padrões de arquitetura bem-sucedidos, otimizações de desempenho e frameworks de segurança
- **Experiência**: Você viu sistemas terem sucesso através de arquitetura adequada e falharem através de atalhos técnicos

Esta seção estabelece a persona do agente e os limites de sua expertise. Não é apenas texto de preenchimento — ele prepara o LLM para adotar uma mentalidade específica.

Missão Principal

## 🎯 Sua Missão Principal

### Excelência em Engenharia de Dados/Esquemas
- Definir e manter esquemas de dados e especificações de índice
- Projetar estruturas de dados eficientes para conjuntos de dados em larga escala (100k+ entidades)
- Implementar pipelines ETL para transformação e unificação de dados
- Criar camadas de persistência de alto desempenho com tempos de consulta abaixo de 20ms

Cada item da missão inclui metas mensuráveis. Observe "tempos de consulta abaixo de 20ms" e "100k+ entidades" — não são objetivos vagos.

Regras Críticas

## 🚨 Regras Críticas Que Você Deve Seguir

### Arquitetura de Segurança em Primeiro Lugar
- Implementar estratégias de defesa em profundidade em todas as camadas do sistema
- Usar o princípio do menor privilégio para todos os serviços e acesso a bancos de dados
- Criptografar dados em repouso e em trânsito usando os padrões de segurança atuais

As regras são restrições não negociáveis. Elas se sobrepõem ao comportamento geral do LLM.

Entregas Técnicas

É aqui que os agentes se separam dos prompts genéricos. O Arquiteto Backend fornece código completo e executável:

-- E-commerce Database Schema Design
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    deleted_at TIMESTAMP WITH TIME ZONE NULL
);

CREATE INDEX idx_users_email ON users(email) WHERE deleted_at IS NULL;
CREATE INDEX idx_users_created_at ON users(created_at);

// Express.js API com middleware de segurança
const helmet = require('helmet');
const rateLimit = require('express-rate-limit');

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000,
  max: 100,
  message: 'Too many requests from this IP, please try again later.',
});

Métricas de Sucesso

## 🎯 Suas Métricas de Sucesso

Você é bem-sucedido quando:
- Os tempos de resposta da API permanecem abaixo de 200ms para o percentil 95
- O tempo de atividade do sistema excede 99,9% de disponibilidade
- As consultas ao banco de dados são executadas em menos de 100ms em média
- Auditorias de segurança não encontram vulnerabilidades críticas

Cada agente define resultados mensuráveis. Isso não é uma afirmação terapêutica — é responsabilidade de engenharia.

Integração Multi-Ferramentas: Um Agente, 10 IDEs

A Agency funciona em mais de 10 ferramentas de codificação de IA. Veja como a camada de integração funciona:

Ferramentas Suportadas

O Script de Conversão (convert.sh)

O script bash scripts/convert.sh lida com a tradução de formato. Aqui está a arquitetura:

#!/usr/bin/env bash
# convert.sh — Converte arquivos .md de agentes da agency em formatos específicos de ferramenta

set -euo pipefail

AGENT_DIRS=(
  academic design engineering game-development marketing paid-media
  sales product project-management testing support spatial-computing specialized
)

# Extrai campos do frontmatter
get_field() {
  local field="$1" file="$2"
  awk -v f="$field" '
    /^---$/ { fm++; next }
    fm == 1 && $0 ~ "^" f ": " { sub("^" f ": ", ""); print; exit }
  ' "$file"
}

# Remove frontmatter, retorna o corpo
get_body() {
  awk 'BEGIN{fm=0} /^---$/{fm++; next} fm>=2{print}' "$1"
}

Para o Cursor, o script converte arquivos .md para o formato de regra .mdc:

convert_cursor() {
  local agent_file="$1"
  local slug=$(to_kebab "$(get_field 'name' "$agent_file")")
  local output_file="$OUT_DIR/cursor/.cursor/rules/agency-${slug}.mdc"

  cat > "$output_file" << EOF
---
description: Agente da Agency: $(get_field 'description' "$agent_file")
---
$(get_body "$agent_file")
EOF
}

Para o Aider e Windsurf, todos os agentes são compilados em arquivos únicos:

convert_aider() {
  local output="$OUT_DIR/aider/CONVENTIONS.md"
  echo "# Agentes da Agency para Aider" > "$output"
  echo "" >> "$output"

  for dir in "${AGENT_DIRS[@]}"; do
    for file in "$REPO_ROOT/$dir"/*.md; do
      echo "---" >> "$output"
      cat "$file" >> "$output"
    done
  done
}

O Script de Instalação (install.sh)

Após a conversão, install.sh copia os arquivos para os diretórios específicos da ferramenta:

#!/usr/bin/env bash
# install.sh — Instala os agentes da Agency em sua(s) ferramenta(s) agentica(s) local(is)

install_claude_code() {
  local src="$REPO_ROOT"
  local dest="$HOME/.claude/agents"
  mkdir -p "$dest"
  cp -r "$src"/{engineering,design,marketing,sales,specialized}/*.md "$dest/"
  ok "Claude Code: $(find "$dest" -name '*.md' | wc -l) agentes instalados"
}

install_cursor() {
  local src="$OUT_DIR/cursor/.cursor/rules"
  local dest="./.cursor/rules"
  mkdir -p "$dest"
  cp "$src"/*.mdc "$dest/"
  ok "Cursor: $(find "$dest" -name '*.mdc' | wc -l) regras instaladas"
}

O script suporta seleção interativa:

  +------------------------------------------------+
  |   A Agency — Instalador de Ferramentas         |
  +------------------------------------------------+

  Varredura do sistema: [*] = detectado nesta máquina

  [x]  1)  [*]  Claude Code     (claude.ai/code)
  [x]  2)  [*]  Copilot         (~/.github + ~/.copilot)
  [x]  3)  [*]  Antigravity     (~/.gemini/antigravity)
  [ ]  4)  [ ]  Gemini CLI      (extensão gemini)
  [x]  7)  [*]  Cursor          (.cursor/rules)

  [1-10] alternar   [a] todos   [n] nenhum   [d] detectado
  [Enter] instalar   [q] sair

A execução paralela acelera as instalações multi-ferramentas:

./scripts/install.sh --parallel --jobs 8

Memória MCP: Contexto Persistente Entre Sessões

Por padrão, os agentes de IA iniciam cada sessão do zero. A integração da Memória MCP muda isso.

O Que É MCP?

MCP (Model Context Protocol) é um protocolo para agentes de IA acessarem ferramentas externas e armazenamento persistente. A Agency usa o MCP para permitir:

• Memória entre sessões: Agentes lembram decisões de sessões anteriores
• Transferência de agentes: Um agente pode deixar contexto para outro
• Rollback em caso de falha: Restaurar para estados conhecidos e bons quando o QA falha

O Padrão de Memória

Adicione esta seção a qualquer agente para habilitar a memória MCP:

## Integração de Memória

Ao iniciar uma sessão:
- Relembre o contexto relevante de sessões anteriores usando sua função e projeto como termos de busca
- Revise quaisquer memórias marcadas com o nome do seu agente

Ao tomar decisões-chave ou concluir entregas:
- Lembre-se da decisão com tags descritivas (nome do agente, projeto, tópico)
- Inclua contexto suficiente para que uma sessão futura possa entender o que foi feito e por que

Ao passar para outro agente:
- Lembre-se de suas entregas marcadas para o agente receptor
- Inclua: o que você concluiu, o que está pendente, o que o próximo agente precisa saber

Ferramentas MCP

Qualquer servidor MCP que exponha essas ferramentas funciona:

Exemplo: Fluxo de Trabalho Alimentado por Memória

Sem memória MCP:

Usuário: "Construa a API"
Agente: [Constrói a API, sessão termina]

[Próxima sessão]
Usuário: "Continue de ontem"
Agente: "Não tenho contexto de sessões anteriores. Você pode colar o que fizemos?"

Com memória MCP:

Usuário: "Construa a API"
Agente: [Constrói a API, lembra: "Arquiteto Backend - API de E-commerce - Tabela de Usuários, autenticação JWT, limitação de taxa"]

[Próxima sessão]
Usuário: "Continue de ontem"
Agente: [Relembra: "Ontem projetei a tabela de usuários com chaves primárias UUID, implementei autenticação JWT com hashing bcrypt e adicionei limitação de taxa de 100 requisições por 15 minutos. Próximo passo: esquema do Serviço de Pedidos."]

Consulte integrations/mcp-memory/backend-architect-with-memory.md para um exemplo completo.

Agentes Destaque: Três Análises Aprofundadas

1. Verificador de Realidade (Divisão de Testes)

O Verificador de Realidade impede aprovações fantasiosas. Posição padrão: "PRECISA DE TRABALHO" até que se prove o contrário.

## 🚨 Seu Processo Obrigatório

### PASSO 1: Comandos de Verificação de Realidade (NUNCA PULE)
```bash
# Verificar o que foi realmente construído
ls -la resources/views/ || ls -la *.html

# Cruzar as características alegadas
grep -r "luxury\|premium\|glass\|morphism" . --include="*.html" --include="*.css" || echo "NÃO FORAM ENCONTRADAS CARACTERÍSTICAS PREMIUM"

# Executar captura de tela profissional Playwright
./qa-playwright-capture.sh http://localhost:8000 public/qa-screenshots

PASSO 2: Validação Cruzada de QA

• Revisar as descobertas do agente de QA a partir de testes headless Chrome
• Cruzar as capturas de tela automatizadas com a avaliação do QA
• Confirmar ou contestar a avaliação do QA com evidências adicionais

PASSO 3: Validação Ponta a Ponta

• Analisar responsive-desktop.png, responsive-tablet.png, responsive-mobile.png
• Verificar fluxos de interação: sequências nav--click.png, form-.png
• Revisar dados reais de desempenho (tempos de carregamento, erros, métricas)

Este agente exige **prova visual** antes de aprovar qualquer coisa. Chega de "Parece ótimo!" sem evidências.

---

### 2. Injetor de Humor (Divisão de Design)

O Injetor de Humor adiciona personalidade sem sacrificar a usabilidade.

```css
/* Interações Divertidas de Botão */
.btn-whimsy {
  position: relative;
  overflow: hidden;
  transition: all 0.3s cubic-bezier(0.23, 1, 0.32, 1);

  &::before {
    content: '';
    position: absolute;
    top: 0;
    left: -100%;
    width: 100%;
    height: 100%;
    background: linear-gradient(90deg, transparent, rgba(255, 255, 255, 0.2), transparent);
    transition: left 0.5s;
  }

  &:hover {
    transform: translateY(-2px) scale(1.02);
    box-shadow: 0 8px 25px rgba(0, 0, 0, 0.15);
  }
}

// Sistema de Conquistas com Humor
class WhimsyAchievements {
  unlock(achievementId) {
    const achievement = this.achievements[achievementId];
    this.showCelebration(achievement);
    this.saveProgress(achievementId);
  }

  showCelebration(achievement) {
    const celebration = document.createElement('div');
    celebration.className = `achievement-celebration ${achievement.celebration}`;
    celebration.innerHTML = `
      <div class="achievement-card">
        <div class="achievement-icon">${achievement.icon}</div>
        <h3>${achievement.title}</h3>
        <p>${achievement.description}</p>
      </div>
    `;
    document.body.appendChild(celebration);
    setTimeout(() => celebration.remove(), 3000);
  }
}

Todo elemento divertido deve servir a um propósito funcional ou emocional. O agente inclui uma biblioteca completa de microtextos:

## Mensagens de Erro
**Página 404**: "Ops! Esta página saiu de férias sem nos avisar."
**Validação de Formulário**: "Seu e-mail parece um pouco tímido – que tal adicionar o símbolo @"?
**Erro de Rede**: "Parece que a internet deu um soluço. Tente novamente?"

3. Construtor de MCP (Divisão Especializada)

O Construtor de MCP cria ferramentas personalizadas que estendem as capacidades dos agentes de IA.

// Esqueleto do servidor MCP TypeScript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "my-server", version: "1.0.0" });

server.tool("search_items", { query: z.string(), limit: z.number().optional() },
  async ({ query, limit = 10 }) => {
    const results = await searchDatabase(query, limit);
    return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

Regras críticas:

• Nomes de ferramentas descritivos: search_users e não query1 — agentes escolhem ferramentas pelo nome
• Parâmetros tipados com Zod: Cada entrada validada, parâmetros opcionais têm padrões
• Saída estruturada: Retorne JSON para dados, markdown para conteúdo legível por humanos
• Falha graciosa: Retorne mensagens de erro, nunca trave o servidor

Comunidade e Traduções

A Agency começou a partir de um tópico no Reddit. Agora tem:

• 147 agentes em 12 divisões
• Mais de 10.000 linhas de personalidade, processo e exemplos de código
• Traduções da comunidade: Chinês Simplificado (duas bifurcações independentes), com mais em andamento
• Suporte multi-ferramentas: Mais de 10 integrações mantidas através de scripts de conversão

Bifurcações notáveis:

• agency-agents-zh por @jnMetaCode: 100 agentes traduzidos + 9 originais do mercado chinês
• agent-teams por @dsclca12: Tradução independente com localização para Bilibili, WeChat, Xiaohongshu

Instalação: Início Rápido

Opção 1: Claude Code (Recomendado)

# Copie os agentes para seu diretório Claude Code
cp -r agency-agents/* ~/.claude/agents/

# Ative em qualquer sessão:
"Olá Claude, ative o modo Desenvolvedor Frontend e me ajude a construir um componente React"

Opção 2: Instalação Multi-Ferramentas

# Passo 1: Gere os arquivos de integração
./scripts/convert.sh

# Passo 2: Instale interativamente (detecta ferramentas automaticamente)
./scripts/install.sh

# Ou instale uma ferramenta específica diretamente
./scripts/install.sh --tool cursor
./scripts/install.sh --tool aider

Opção 3: Usar como Referência

Navegue pelos agentes em github.com/msitarzewski/agency-agents e adapte os que você precisa. Cada arquivo contém identidade, fluxos de trabalho, entregas e exemplos de código.

O Que Torna Isso Diferente?

Vs. Prompts de IA Genéricos

Vs. Bibliotecas de Prompts

Vs. Ferramentas de IA

Principais Conclusões Técnicas

1. A especialização supera a generalização: 147 especialistas superam um prompt "faz-tudo"
2. A estrutura impulsiona a saída: Frontmatter + Identidade + Missão + Regras + Entregas + Métricas
3. A integração importa: Scripts Bash convertem agentes para mais de 10 formatos automaticamente
4. A memória permite a continuidade: O protocolo MCP resolve o problema "Não me lembro de ontem"
5. A comunidade escala: Tópico do Reddit → 147 agentes → traduções → suporte multi-ferramentas

Próximos Passos

Quer experimentar a Agency?

1. Navegue pela lista completa de agentes
2. Instale para sua ferramenta preferida (Claude Code, Cursor, Aider, etc.)
3. Ative especialistas pelo nome: "Use o Verificador de Realidade para verificar se isso está pronto para produção"
4. Contribua: Adicione novos agentes, melhore os existentes, compartilhe histórias de sucesso

Construindo seus próprios agentes de IA? Estude a anatomia do agente: frontmatter para descoberta, identidade para persona, missão para escopo, regras para restrições, entregas para saída, métricas para responsabilidade.

A Agency prova que a especialização não é apenas para humanos. Às vezes, a melhor equipe de IA não é um modelo tentando fazer tudo — são 147 especialistas que sabem exatamente o que devem fazer.