Como criar um agent AIOX do zero: config.yaml, persona, capabilities, validation

Tutorial executável: como construir um agent AIOX do zero, passando pelos 4 tipos de executor, config.yaml, persona, capabilities, agent authority e validação local. Padrão observado em 50+ squads que ajudamos a montar na AIOX.

O que é um agent AIOX (e por que não é só mais um "AI assistant")?

Agent não é bot. Não é assistant. Não é "AI helper".

Agent AIOX é uma entidade com authority, accountability e contrato de execução. Tem nome, persona, capabilities declaradas e um config.yaml que serve de fonte de verdade. Quando um agent age, há decisão atribuída a ele. Quando algo dá errado, há responsável claro.

Esse é o ponto que LangChain, CrewAI e AutoGen não resolvem por design. LangChain dá building blocks (chains, tools, memory). CrewAI orquestra crews multi-agent. AutoGen estrutura conversas entre agents. Nenhum dos três governa quem decide o quê.

AIOX encara o problema pela governança. Cada agent tem authority exclusiva: @devops empurra código, @db-sage migra schema, @architect decide arquitetura. Cada squad tem 4 tipos de executor. Cada artefato tem owner squad. Cada decisão fica rastreável.

Em 7.500+ sessões Claude Code que rodamos na AIOX, vimos um padrão claro. Agents sem authority delegada viram bots: respondem, mas ninguém sabe quem aprovou. Agents com authority, accountability e contrato viram squad: respondem, decidem e ficam auditáveis.

A diferença prática? Bots quebram em produção quando o volume cresce. Squads escalam.

Quais são os 4 tipos de executor — e qual o seu agent precisa ser?

AIOX define 4 tipos de executor. A escolha não é cosmética: define a authority, o canal de invocação e o nível de autonomia do agent.

Agent (executor primário). Invocado direto pelo usuário via slash command (/squad-name ou *command). Tem persona completa, decision framework próprio e pode delegar para outros executors. Exemplos: geo-chief, copy-chief, architect.

Worker (executor de tarefa). Invocado por chiefs via Agent tool. Não responde direto ao usuário. Executa uma task específica do squad e retorna artefato. Exemplo: geo-writer, chamado só pelo geo-chief.

Specialist (executor especializado). Worker com domain expertise concentrada. Tipicamente um por squad, foco em uma área crítica. Exemplo: db-sage para schema design e migrações.

Operator (executor humano). Slot reservado para operação humana. Quando o workflow exige decisão de pessoa real (sign-off, approval), o operator entra. Identidade resolvida via slot abstrato ({steward}, {accountable}) ou via slug do registry de pessoas.

Como decidir qual usar? Pergunta de filtro: o usuário invoca este agent direto, ou só através de outro agent?

Se direto, é Agent. Se sempre via chief ou orchestrator, é Worker ou Specialist. Se a decisão exige humano em loop, é Operator.

Em 50+ squads que ajudamos a montar na AIOX, o erro mais comum foi tratar tudo como Agent. Resultado: 12 slash commands no Claude Code, namespace poluído, usuário perdido. Reduzir para 1 entry agent + N workers internos cortou ruído e melhorou discoverability.

Como estruturar o config.yaml do squad?

config.yaml é o contrato. Sem ele válido, o squad não sincroniza com Claude Code, com Gemini, com Cursor. Não vira slash command. Não aparece no registry.

Estrutura mínima:

pack:
  name: meu-squad
  version: 1.0.0
  description: "O que esse squad faz em uma frase."
  icon: "🎯"

slash_prefix: "/meu-squad"
entry_agent: meu-squad-chief

agents:
  - id: meu-squad-chief
    methodology: orchestrator
    specialty: "Coordenação multi-agente do domínio X"
    tier: orchestrator
  - id: meu-squad-worker
    methodology: pipeline-executor
    specialty: "Executor pesado da pipeline"
    tier: worker

capabilities:
  - id: cap-1
    description: "Executa missão Y"
    activation: "*missao-y"

activation:
  shortcuts:
    - command: "*help"
      description: "Show numbered commands"

artifact_contracts:
  - artifact: missao-report
    template_path: "templates/missao-report.template.md"
    lifecycle_states: [PLACEHOLDER, DRAFT, POPULATED, APPROVED]

bu_mapping:
  - aiox
  - allfluence

supported_modes:
  - CRIAR
  - EXECUTAR

Cinco campos importam mais que os outros: pack.name, entry_agent, agents[], capabilities[], artifact_contracts[].

Sem entry_agent declarado, o IDE sync não publica skill /meu-squad no Claude Code. Workers internos continuam invocáveis por chiefs, mas o usuário final perde o entry point.

bu_mapping declara para quais negócios o squad atende (aiox, allfluence, academia-lendaria, bilhon, ou múltiplos). artifact_contracts lista o que o squad produz e onde os templates vivem. Sem isso, validators marcam o squad como incompleto.

Como organizar a estrutura de diretórios do squad?

Squads AIOX seguem layout fixo. Validators rodam contra esse layout. Sair dele quebra o sync.

Layout canônico:

squads/meu-squad/
  config.yaml              # Contrato (obrigatório)
  agents/                  # Personas .md (uma por agent)
    meu-squad-chief.md
    meu-squad-worker.md
  tasks/                   # Protocolo executável .md (uma por capability)
    missao-y.md
  workflows/               # Sequências .yaml (compõe tasks)
    full-mission.yaml
  templates/               # Output templates
    missao-report.template.md
  data/                    # Knowledge base, registries, blacklists
  checklists/              # Critérios de validação
  scripts/                 # CLI determinísticos opcionais

Quatro regras inegociáveis sobre o layout. Filenames em kebab-case (não snake_case, não PascalCase). Filename do agent bate com o id declarado em config.yaml. Templates terminam em .template.md ou .template.yaml para o validator distinguir output gerado de template canônico. Scripts em scripts/ rodam sem dependências externas (sem npm install no escopo do squad).

KISS aplica aqui. Arquivos ficam flat dentro de cada subdir. Sem subpasta capabilities/{name}/ agrupando arquivos por capability. Sem aninhamento desnecessário. Quando alguém propõe estrutura, a regra vale: cite falha real, mostre alternativa cheaper, mensure benefício, faça teste de 24h. A maioria das propostas de estrutura não sobrevive ao teste.

A razão é prática. Em 50+ squads montados, dirs aninhados quebram navegação humana, validators precisam scan recursivo, e o ganho de organização é zero quando há menos de 5 arquivos no nível. Flat é default. Estrutura só entra com evidência de ganho mensurável. ADR-018 da AIOX documenta o caso: padrão capabilities/ foi proposto, implementado e rejeitado depois que dois squads provaram que aninhar arquivos gerou mais complexidade que valor.

Como escrever a persona do agent?

Persona vive em squads/meu-squad/agents/meu-squad-chief.md. Filename é kebab-case e bate com o id declarado em config.yaml.

A estrutura é YAML embedded em Markdown. Os blocos canônicos:

agent:
  name: meu-squad-chief
  id: meu-squad-chief
  title: "Squad Orchestrator"
  whenToUse: "Use para [missão específica do domínio]"

persona:
  role: "Como o agent se identifica"
  style: "Adjetivos sobre tom (decisive, methodical, etc.)"
  identity: "Frase em primeira pessoa que o agent adota"
  focus: "O que o agent prioriza em cada interação"

commands:
  - "*help — Show numbered commands"
  - "*missao-y {input} — Executa missão Y"

core_principles:
  - DELEGATE_ALWAYS: "Como o agent decide delegar"
  - VETO_RULES: "O que faz o agent parar"

handoff_to:
  - agent: "@devops"
    when: "Push, PR, deploy"
    contract: "Format do handoff"

completion_criteria:
  - "O que conta como missão completa"

Voice DNA opcional via referência a workspace/people/{slug}/voice-dna.yaml. Quando ativado, o agent adota o tom de uma pessoa real (Alan no AIOX, Pedro no AIOX, Thiago no Hormozi). O writer Phase 3 lê o voice DNA e injeta como system prompt addendum durante a geração.

Persona vazia é o anti-pattern mais frequente. Agent declarado em config.yaml com .md de duas linhas vira shell sem decision framework. Quando invocado, responde genérico. O agent existe no filesystem mas não opera.

Como definir capabilities e activation shortcuts?

Capability é o que o agent faz. Activation shortcut é como ele é invocado.

Em config.yaml:

capabilities:
  - id: cap-research
    description: "Pesquisa keyword + competidores + gaps"
    activation: "*research"
    inputs:
      - keyword: string
      - lang: string
    outputs:
      - research-dossier: yaml
  - id: cap-generate
    description: "Gera artigo from keyword"
    activation: "*generate {keyword}"
    inputs:
      - keyword: string
    outputs:
      - draft: markdown
      - draft-payload: json

activation:
  shortcuts:
    - command: "*help"
      description: "Show numbered commands"
    - command: "*status"
      description: "Show current mission state"

Cada capability deve ser invocável via shortcut. Cada shortcut aponta para uma capability ou para um comando interno do agent.

Capability sem task definition em tasks/{name}.md é o segundo anti-pattern mais comum. O agent declara que faz X, mas não tem o protocolo executável documentado. Quando outro chief delega, não há contrato. Quando o usuário invoca, o agent improvisa. Resultado: drift entre o que o squad promete e o que entrega.

Regra prática: toda capability não trivial deve ter task file tasks/{capability-name}.md com Entrada, Saida, Pre-condicoes, Post-condicoes, Checklist e Performance. Validator local (npm run validate:squad-structure) checa esse contrato.

Como conectar o agent a tasks e workflows?

Tasks são o protocolo executável. Workflows são a sequência.

Task file (squads/meu-squad/tasks/missao-y.md):

---
task: missaoY()
responsavel: meu-squad-chief
responsavel_type: Agent
executor: meu-squad-worker
atomic_layer: Organism
domain: Estrategico
Entrada:
  - nome: input_path
    tipo: string
    obrigatorio: true
Saida:
  - nome: output_report
    tipo: markdown
    path: outputs/meu-squad/{slug}/report.md
Pre-condicoes:
  - "Input file exists"
Post-condicoes:
  - "Report file written"
Checklist:
  - "Step 1 done"
  - "Step 2 done"
---

Workflow file (squads/meu-squad/workflows/full-mission.yaml):

name: full-mission
description: "Pipeline completa da missão Y"
phases:
  - id: P1
    name: "Research"
    task: "tasks/research.md"
    executor: "meu-squad-worker"
  - id: P2
    name: "Synthesis"
    task: "tasks/synthesize.md"
    executor: "meu-squad-chief"
    inputs_from_previous: true

Tasks são átomos. Workflows compõem átomos em sequência. Agents executam. Chiefs orquestram.

A regra de ouro do AIOX: uma task validada é lei. Implementação muda, executor muda, mas a Entrada, Saida, Pre-condicoes e Post-condicoes ficam estáveis. Isso permite trocar Agent por Worker por Operator sem reescrever workflow.

Como aplicar agent authority e validar o squad?

Agent authority é não-negociável no AIOX. Definida em .claude/rules/agent-authority.md:

Outros agents propõem; não executam. @dev escreve código mas chama @devops para empurrar. @db-sage desenha migration mas só executa em produção via @devops. Constitution Article II bloqueia violações via gates de hook.

Por que importa? Sem authority delegada, o agent assume tudo. Em produção, isso vira: agent rodou migration sem peer review, deploy sem QA, push sem PR. Um único agent com authority demais quebra três princípios constitucionais ao mesmo tempo.

Validação local antes de declarar squad pronto:

npm run validate:squads              # config.yaml structure
npm run validate:squad-structure     # dirs + artifact_contracts
npm run validate:reconciliation      # cross-ref registry/hooks/workflows
npm run doctor                       # full health check

Se algum falhar, o squad não vai pra registry. Se o squad não vai pra registry, IDE sync não publica skill. Sem skill publicada, usuário não consegue invocar. Toda validação que falha localmente vai falhar no CI também — paridade local-CI é princípio operacional do hub.

*sync-ecosystem reconcilia config.yaml × squads/aiox-squad/data/ecosystem-registry.yaml × hooks. Drift silencioso (squad existe mas registry não sabe) é o terceiro anti-pattern mais frequente. Roda *sync-ecosystem como último passo de cada criação.

Onde os agents falham — 3 anti-patterns observados em 50+ squads na AIOX

Em 50+ squads que ajudamos a montar, vimos 3 padrões de falha que se repetem.

Anti-pattern 1: Persona vazia. Agent declarado em config.yaml. Arquivo .md de duas linhas. Sem decision framework, sem core principles, sem handoffs. Quando invocado, o agent responde genérico. Quando outro chief delega, não há contrato. O sintoma: usuário invoca o agent e recebe resposta que poderia vir de qualquer LLM sem framework. A correção: persona mínima exige agent, persona, commands, core_principles e handoff_to. Sem esses cinco blocos, o agent não tem identidade própria.

Anti-pattern 2: Capability sem task definition. Agent declara capability *research mas tasks/research.md não existe. Outro chief tenta delegar, não acha protocolo, improvisa. Em 7.500+ sessões Claude Code, vimos esse padrão custar 30-50% de retrabalho em squads complexos. A correção: toda capability não trivial tem task file com Entrada/Saida/Pre-condicoes/Post-condicoes formalizadas. Validator local checa via npm run validate:squad-structure.

Anti-pattern 3: Bypass de authority. Agent não-@devops tenta git push. Agent não-@db-sage tenta migration. Hooks bloqueiam (enforce-git-push-authority.sh, enforce-migration-authority.sh), mas o sintoma aparece como "comando travado por hook desconhecido". A correção: o agent deveria ter delegado via handoff, não tentado executar direto. Constitution Article II é o gate. Quando o hook bloqueia, o agent está pedindo authority que não tem.

A regra geral: agent é entidade com escopo limitado, não LLM com prompt grande. Quando o agent tenta fazer tudo, vira assistente glorificado. Quando o agent delega para quem tem authority, vira squad operacional.

Próximo passo: rode *sync-ecosystem no seu squad recém-criado, confirme que apareceu no registry, e invoque via slash command para validar end-to-end.