Formato de Especificação de Agente

Os agentes Tajo são definidos em ficheiros markdown. Cada ficheiro contém frontmatter YAML (identidade, ferramentas, restrições) e um corpo markdown (instruções, estratégia, regras). Este formato é inspirado em padrões de agentes em produção usados em sistemas de orquestração multi-agente.

Estrutura do Ficheiro

---
name: agent-name
description: O que este agente faz (máx. 160 chars)
version: 1.0.0
temperature: 0.2
max_tokens: 4096
tools:
  - brevo_contacts
  - brevo_email_campaign_management
  - brevo_sms_campaigns
triggers:
  - event: cart_abandoned
  - schedule: "0 */4 * * *"
permissions:
  - contacts:read
  - email:send
  - sms:send
---

# Nome do Agente

Instruções para o agente em linguagem natural...

Campos de Frontmatter

Campos Obrigatórios

Campo	Tipo	Descrição
`name`	string	Identificador único em kebab-case (ex.: `cart-recovery-agent`)
`description`	string	O que este agente faz (máx. 160 chars)
`version`	string	Versão semântica (ex.: `1.0.0`)
`tools`	array	Módulos do servidor MCP Brevo a que este agente pode aceder

Campos de Comportamento

Campo	Tipo	Padrão	Descrição
`temperature`	float	`0.3`	Temperatura do LLM. Menor = mais determinístico. Use 0.1-0.2 para operações de dados, 0.3-0.5 para design de campanhas
`max_tokens`	integer	`4096`	Comprimento máximo de resposta por turno
`model`	string	`claude-sonnet-4-6`	Modelo LLM a usar

Campos de Acionador

Campo	Tipo	Padrão	Descrição
`triggers`	array	`[]`	Eventos, agendamentos ou webhooks que ativam este agente
`triggers[].event`	string	-	Nome do evento (ex.: `cart_abandoned`, `customer_created`)
`triggers[].schedule`	string	-	Expressão cron (ex.: `0 9 * * *` para 9h diárias)
`triggers[].webhook`	string	-	Caminho do webhook (ex.: `/agents/cart-recovery/trigger`)
`triggers[].conditions`	array	`[]`	Condições de filtro para o acionador
`triggers[].debounce`	string	-	Janela de debounce (ex.: `5m`, `1h`)

Campos de Permissão

Campo	Tipo	Padrão	Descrição
`permissions`	array	`[]`	Âmbitos de permissão necessários para trilha de auditoria
`related_agents`	array	`[]`	IDs de agentes para os quais este agente pode delegar
`escalation`	string	-	Para onde encaminhar quando o agente estiver incerto (`human`, `supervisor-agent`)

Ferramentas: Mapeamento para Servidores MCP Brevo

O campo tools referencia nomes de módulos do servidor MCP Brevo. Cada módulo mapeia para um endpoint específico em mcp.brevo.com:

tools:
  # Contactos e Segmentação
  - brevo_contacts                    # /v1/brevo_contacts/mcp
  - brevo_lists                       # /v1/brevo_lists/mcp
  - brevo_segments                    # /v1/brevo_segments/mcp
  - brevo_attributes                  # /v1/brevo_attributes/mcp

  # Campanhas e Mensagens
  - brevo_email_campaign_management   # /v1/brevo_email_campaign_management/mcp
  - brevo_templates                   # /v1/brevo_templates/mcp
  - brevo_sms_campaigns               # /v1/brevo_sms_campaigns/mcp
  - brevo_whatsapp_campaigns          # /v1/brevo_whatsapp_campaigns/mcp

  # Análise
  - brevo_campaign_analytics          # /v1/brevo_campaign_analytics/mcp

  # CRM de Vendas
  - brevo_deals                       # /v1/brevo_deals/mcp
  - brevo_companies                   # /v1/brevo_companies/mcp
  - brevo_tasks                       # /v1/brevo_tasks/mcp
  - brevo_pipelines                   # /v1/brevo_pipelines/mcp
  - brevo_notes                       # /v1/brevo_notes/mcp

Tip

Use o conjunto mínimo de ferramentas de que o seu agente precisa. Menos ferramentas = melhor raciocínio de IA e respostas mais rápidas. Veja Servidor MCP Brevo para todos os módulos disponíveis.

Acionadores

Acionadores de Evento

Ative o agente quando algo acontece no seu sistema:

triggers:
  - event: cart_abandoned
    conditions:
      - cart_value: "> 50"
      - items_count: ">= 1"
      - time_since_activity: "> 30m"
    debounce: 5m

Acionadores de Agendamento

Execute o agente num agendamento recorrente:

triggers:
  - schedule: "0 9 * * MON"        # Toda segunda-feira às 9h
    timezone: "America/New_York"
  - schedule: "0 */4 * * *"        # A cada 4 horas
  - schedule: "0 0 1 * *"          # Primeiro dia de cada mês

Acionadores de Webhook

Invoque o agente via HTTP:

triggers:
  - webhook: /agents/win-back/trigger
    method: POST
    authentication: api_key

Corpo Markdown: Instruções

O corpo da especificação do agente são instruções em linguagem natural. Escreva como se estivesse a dar instruções a um profissional de marketing experiente:

Estrutura

# Nome do Agente

Parágrafo de contexto, o que este agente faz e porquê.

## Estratégia

Abordagem passo a passo que o agente deve seguir.

## Estrutura de Decisão

Regras para tomar escolhas (ex.: qual canal usar com base no valor do carrinho).

## Regras

Restrições rígidas, coisas que o agente deve SEMPRE ou NUNCA fazer.

## Templates

Referências a IDs de template Brevo, cópia SMS, templates WhatsApp.

## Métricas

Eventos a rastrear para medir o sucesso.

Escrever Instruções Eficazes

Seja específico sobre a estratégia, não apenas sobre os objetivos:

## Mau
Reengaje clientes perdidos.

## Bom
Quando um cliente não compra há 90+ dias:
1. Verificar os seus últimos 3 pedidos para preferências de categoria de produto
2. Criar um desconto personalizado com base no AOV (10% se AOV > $100, 15% se < $100)
3. Enviar e-mail com linha de assunto que referencia a sua categoria preferida
4. Aguardar 72 horas, se sem abertura, enviar SMS com código de desconto
5. Aguardar 7 dias, se sem compra, marcar como churn profundo e parar sequência

Definir barreiras de proteção explicitamente:

## Regras
- NUNCA enviar mais de 3 mensagens por sequência
- NUNCA contactar clientes que cancelaram a subscrição
- SEMPRE verificar se o cliente converteu antes de enviar o próximo passo
- SEMPRE respeitar horários de silêncio (sem SMS 21h-9h hora local)
- Em caso de dúvida sobre uma decisão, escalar para revisão humana

Cadeias Multi-Agente

Para fluxos de trabalho complexos, componha múltiplos agentes numa cadeia. Cada agente trata uma fase, passando contexto para o seguinte:

name: quarterly-retention-campaign
steps:
  - agent: customer-intelligence
    input: |
      Analise segmentos de clientes para campanha de retenção Q2.
      Objetivo: {task}

      Identifique:
      1. Clientes em risco (frequência de compra a diminuir)
      2. Clientes VIP (top 10% por LTV)
      3. Candidatos win-back (90+ dias desde o último pedido)

  - agent: campaign-designer
    input: |
      Projete campanhas de retenção para estes segmentos:
      {previous}

      Crie abordagens diferenciadas por segmento:
      - Em risco: sugestão suave com recomendações de produto
      - VIP: acesso antecipado exclusivo ou recompensa de fidelidade
      - Win-back: desconto agressivo com urgência

  - agent: campaign-executor
    input: |
      Execute estas campanhas via Brevo:
      {previous}

      Use canais adequados por preferência de segmento.
      Configure testes A/B para linhas de assunto.
      Agende envios para horários ótimos.

  - agent: campaign-reporter
    input: |
      Gere o relatório de lançamento da campanha de retenção:
      {previous}

      Inclua: segmentos visados, campanhas criadas,
      alcance esperado, configurações de teste A/B.

Variáveis de Cadeia

Variável	Descrição
`{task}`	O objetivo/pedido original
`{previous}`	Saída do passo anterior
`{step_N}`	Saída do passo N (indexado em 0)
`{artifacts_dir}`	Diretório para saídas de ficheiros

Especificações de Agentes Pré-construídos

Orquestrador de Campanhas

---
name: campaign-orchestrator
description: Design and execute multi-channel campaigns from natural language prompts
version: 2.0.0
temperature: 0.3
tools:
  - brevo_contacts
  - brevo_segments
  - brevo_email_campaign_management
  - brevo_templates
  - brevo_sms_campaigns
  - brevo_whatsapp_campaigns
  - brevo_campaign_analytics
triggers:
  - webhook: /agents/campaign/trigger
    method: POST
---

# Orquestrador de Campanhas

É um especialista em campanhas de marketing multicanal.
Dado um brief de campanha, projeta, constrói e lança
campanhas por e-mail, SMS e WhatsApp via Brevo.

## Processo
1. Analisar o brief da campanha (audiência, mensagem, objetivo, timeline)
2. Criar ou identificar o segmento alvo no Brevo
3. Selecionar o(s) melhor(es) canal(is) com base nos dados de preferência da audiência
4. Construir conteúdo da campanha usando templates existentes ou criando novos
5. Configurar agendamento de envio e testes A/B
6. Lançar e reportar métricas iniciais de entrega

## Seleção de Canal
- E-mail: padrão para todas as campanhas
- SMS: adicionar para ofertas urgentes ou recuperação de carrinho
- WhatsApp: adicionar para campanhas conversacionais ou segmentos de alto valor

## Regras
- SEMPRE pré-visualizar campanhas antes de enviar
- NUNCA enviar para contactos não subscritos
- SEMPRE configurar rastreamento para atribuição de campanhas
- Máximo de 2 variantes de teste A/B por campanha

Agente de Inteligência de Cliente

---
name: customer-intelligence
description: Autonomous segmentation, RFM scoring, and churn prediction
version: 1.5.0
temperature: 0.2
tools:
  - brevo_contacts
  - brevo_segments
  - brevo_attributes
  - brevo_lists
  - brevo_campaign_analytics
triggers:
  - schedule: "0 6 * * MON"
    timezone: "UTC"
---

# Agente de Inteligência de Cliente

Analisa dados de clientes no Brevo para gerar segmentos
e insights acionáveis para equipas de marketing.

## Análise Semanal
1. Extrair dados de atividade de contactos da análise de campanhas
2. Calcular scores RFM (Recência, Frequência, Valor Monetário)
3. Identificar mudanças de segmento (clientes a mover entre níveis)
4. Sinalizar riscos de churn (envolvimento a diminuir durante 4+ semanas)
5. Gerar recomendações de segmento para campanhas futuras

## Definições de Segmento
- Campeões: R=5, F=5, M=5, recentes, frequentes, alto valor
- Leais: R>=3, F>=4, M>=3, compradores consistentes
- Em Risco: R&lt;=2, F>=3, M>=3, eram leais, agora a diminuir
- Hibernando: R=1, F>=2, M>=2, há muito ausentes, antes ativos
- Novos: primeira compra nos últimos 30 dias

## Saída
Produzir um relatório markdown com:
- Tamanhos de segmentos e mudanças semana a semana
- Top 10 clientes em risco por LTV
- Ações recomendadas por segmento
- Temas de campanha sugeridos para a semana

Implementação

Executar um Agente Programaticamente

import { TajoAgent } from "@tajo/agent-sdk";

const agent = new TajoAgent({
  specPath: "./agents/cart-recovery-agent.md",
  brevoToken: process.env.BREVO_MCP_TOKEN,
  model: "claude-sonnet-4-6",
  // Ligar apenas os servidores MCP listados no campo tools do agente
  autoConnectServers: true,
});

const result = await agent.run(
  "Recover abandoned carts over $50 from the last 4 hours"
);

console.log(result.summary);
console.log(result.toolCalls);    // Trilha de auditoria completa
console.log(result.metrics);      // Eventos rastreados

Executar via Claude Code

# Apontar para a especificação do seu agente e deixar o Claude executar
claude "Run the agent defined in ./agents/cart-recovery-agent.md for today's abandoned carts"

Agendar com Cron

# Executar o agente de inteligência de cliente toda segunda-feira às 6h
0 6 * * MON claude --print "Run ./agents/customer-intelligence.md weekly analysis" >> /var/log/tajo-agents.log 2>&1

Próximos Passos

Servidor MCP Brevo, Ferramentas disponíveis e configuração do servidor
Construir o Seu Primeiro Agente, Tutorial prático
Referência de Skills, Skills Tajo que se compõem com agentes
Visão Geral da Arquitetura MCP, Como tudo se encaixa

Formato de Especificação de Agente