Workflow: Novo Agente (Tipo Novo)

Como criar um tipo de agente completamente novo (ex: agent-recuperacao, agent-prospeccao). Diferente de criar tenant — aqui é estrutura do produto.

Quando usar

“Vamos criar o agent-recuperacao”
“Preciso de um agente novo do tipo X”
Após decisão arquitetural de adicionar Tier ao catálogo

Não use para criar cliente novo. Para isso, use .claude/workflows/novo-cliente.md.

Pré-requisitos

Antes de iniciar, confirme com o Alex:

Tipo do agente (slug em kebab-case, ex: recuperacao)
Tier (1, 2, 3, 4)
Casos de uso principais (3-5 cenários típicos)
Diferencial vs agentes existentes (por que precisa de tipo novo?)
Integrações específicas necessárias
Pricing inicial (setup, mensal, tempo de implementação)

Passo 1: Criar spec do agente

Antes de escrever uma linha de código, crie a documentação técnica.

cp .claude/agents/_template.md .claude/agents/{tipo}.md

Preencher seguindo o padrão dos agentes existentes (.claude/agents/sdr.md é referência). Estrutura obrigatória:

# Agent {Tipo}

## ICP — para quem é

## Casos de uso

## Tools necessárias

## Flows do LangGraph

## System prompt template

## Default config.yaml

## KPIs

## Dataset eval inicial

## Pricing

## Tempo de implementação

## Diferencial vs concorrência

Passo 2: Criar repositório

Via GitHub CLI:

gh repo create triadeflow-ia/agent-{tipo} \
  --template triadeflow-ia/agent-template \
  --private \
  --description "Agent {Tipo} - Triadeflow"

git clone git@github.com:triadeflow-ia/agent-{tipo}.git
cd agent-{tipo}

Passo 3: Adaptar código do template

O agent-template vem com estrutura genérica. Adapte:

`pyproject.toml`

Atualizar name, description
Adicionar dependências específicas (ex: google-api-python-client para agendamento)

`src/agent.py`

Definir LangGraph workflow específico do tipo
Importar nodes específicos de flows/

`src/flows/`

Criar nodes específicos do tipo
Padrão: cada node em arquivo separado
Ver .claude/agents/{tipo}.md para nodes esperados

`src/tools/`

Implementar tools específicas do tipo
Tools comuns ficam em triadeflow-core (consultar_kb, handoff_humano)
Tools específicas ficam aqui

`src/prompts/system.md`

Template Jinja2 herdando estrutura padrão
Fragmentos de tom, regras, tools, lgpd
Variáveis específicas do tipo

`tenants/_defaults.yaml`

Default config para qualquer tenant deste tipo
Será mergeado com tenants/{tenant_id}/config.yaml

Passo 4: CLAUDE.md do agente

Criar CLAUDE.md curto na raiz do agente:

# CLAUDE.md — agent-{tipo}

Este repositório implementa o agente {Tipo} da plataforma Triadeflow.

## Contexto da plataforma

Toda documentação arquitetural está em:
https://github.com/triadeflow-ia/triadeflow-docs

Antes de qualquer alteração, leia:
- triadeflow-docs/CLAUDE.md
- triadeflow-docs/.claude/agents/{tipo}.md  ← spec deste agente
- triadeflow-docs/.claude/conventions.md

## Especificidades

{2-3 bullets do que é único deste tipo}

## Tenants ativos

Listados em `tenants/_active.txt` — atualizado automaticamente
ao executar `scripts/create_tenant.py`.

## Comandos comuns

- `make dev` — roda local com hot-reload
- `make eval` — roda dataset golden
- `make deploy ENV=prod` — deploy em produção
- `python scripts/create_tenant.py {tenant_id}` — cria tenant novo
- `python scripts/ingest_kb.py --tenant {tenant_id}` — vetoriza KB

## Estado atual

Atualizar conforme evoluir:
- [ ] Estrutura base (template) — em construção
- [ ] Tools específicas — pendente
- [ ] System prompt template — pendente
- [ ] Eval dataset golden — pendente
- [ ] Deploy infra — pendente
- [ ] Primeiro tenant — pendente

Passo 5: Eval dataset inicial

Toda nova spec exige dataset de eval antes de ir pra produção.

mkdir -p eval/datasets
touch eval/datasets/golden.json

Estrutura de cada caso:

{
  "id": "case-001",
  "category": "qualificacao_basica",
  "input": {
    "history": [],
    "user_message": "Mensagem do usuário"
  },
  "expected": {
    "intent": "{intenção esperada}",
    "tools_called": ["{tool1}", "{tool2}"],
    "response_must_contain": ["palavra-chave1", "palavra-chave2"],
    "response_must_not_contain": ["palavra a evitar"],
    "tone": "{esperado}"
  },
  "criticality": "high"
}

Mínimo: 30 casos cobrindo:

5 cenários comuns (60% do tráfego)
5 edge cases
3 casos de tom/empatia
3 casos de handoff
2 casos de erro/recuperação

Passo 6: Deploy infra

Adicionar ao stack do Hetzner:

# docker-compose.yml em /opt/triadeflow/
services:
  agent-{tipo}:
    image: registry.triadeflow.com/agent-{tipo}:latest
    container_name: agent-{tipo}
    restart: unless-stopped
    environment:
      - REDIS_URL=redis://redis:6379
      - QDRANT_URL=http://qdrant:6333
      - LANGFUSE_HOST=http://langfuse:3000
      - DATABASE_URL=postgres://...
    networks:
      - triadeflow-net
    labels:
      caddy: {tipo}.triadeflow.com
      caddy.reverse_proxy: "{{upstreams 8000}}"

Passo 7: Atualizar documentação central

No triadeflow-docs:

Adicionar entrada em .claude/agents/README.md (catálogo)
Atualizar tabela de agentes no CLAUDE.md raiz
Atualizar CHANGELOG.md com a nova versão (minor bump: 1.x → 1.x+1)
Atualizar arquivo .claude/reference/decisoes.md com ADR justificando o tipo

Passo 8: Atualizar materiais comerciais

Se o agente é Tier 1-2 (vai ser comercializado ativamente):

Atualizar Catálogo Word (catalogo-agentes-triadeflow.docx)
Atualizar Central de Templates HTML
Atualizar Painel de Operação (cards de tipos)
Atualizar página comercial em https://triadeflow.com.br

Tier 3-4 podem ficar apenas na documentação interna até prova de conceito.

Passo 9: Primeiro tenant piloto

Antes de comercializar, valide com tenant piloto:

Selecionar cliente parceiro disposto a ser piloto
Implementar usando .claude/workflows/novo-cliente.md
Operar 30 dias
Coletar feedback estruturado
Iterar na spec se necessário
Promover para “comercializável” no catálogo

Saída para o Alex

✓ Agente {Tipo} criado

Repositório: https://github.com/triadeflow-ia/agent-{tipo}
Spec: triadeflow-docs/.claude/agents/{tipo}.md

Estado:
- Estrutura base: pronta
- Tools: {N} implementadas
- System prompt: template pronto
- Eval dataset: {N} casos golden criados
- Deploy infra: configurado em /opt/triadeflow/

Pendências para go-live:
1. Ingerir primeiros 30+ casos no eval
2. Identificar tenant piloto
3. Configurar primeiro tenant
4. Operar 30 dias
5. Promover para catálogo comercial

Próximo passo recomendado: {sugestão concreta}

Erros comuns a evitar

Pular criação da spec — código antes de doc gera retrabalho garantido
Não usar agent-template — divergência entre agentes complica manutenção
Reimplementar tools que existem no core — duplica e quebra padrões
Comercializar sem piloto — risco alto de descobrir problemas no primeiro cliente real
Não atualizar docs centrais — agente novo vira fantasma, time não sabe que existe

Versão: 1.0 Relacionado: .claude/workflows/novo-cliente.md, .claude/agents/