On this page

Formato de Especificación de Agentes

Los agentes de Tajo se definen en archivos markdown. Cada archivo contiene frontmatter YAML (identidad, herramientas, restricciones) y un cuerpo markdown (instrucciones, estrategia, reglas). Este formato está inspirado en patrones de agentes de producción usados en sistemas de orquestación multi-agente.

Estructura del Archivo

---
name: agent-name
description: What this agent does (max 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
---

# Agent Name

Instructions for the agent in natural language...

Campos del Frontmatter

Campos Requeridos

Campo	Tipo	Descripción
`name`	string	Identificador único en kebab-case (ej., `cart-recovery-agent`)
`description`	string	Lo que hace este agente (máx. 160 caracteres)
`version`	string	Versión semántica (ej., `1.0.0`)
`tools`	array	Módulos del servidor MCP de Brevo a los que este agente puede acceder

Campos de Comportamiento

Campo	Tipo	Defecto	Descripción
`temperature`	float	`0.3`	Temperatura del LLM. Menor = más determinista. Usa 0.1-0.2 para operaciones de datos, 0.3-0.5 para diseño de campañas
`max_tokens`	integer	`4096`	Longitud máxima de respuesta por turno
`model`	string	`claude-sonnet-4-6`	Modelo LLM a usar

Campos de Desencadenadores

Campo	Tipo	Defecto	Descripción
`triggers`	array	`[]`	Eventos, horarios o webhooks que activan este agente
`triggers[].event`	string	-	Nombre del evento (ej., `cart_abandoned`, `customer_created`)
`triggers[].schedule`	string	-	Expresión cron (ej., `0 9 * * *` para diariamente a las 9am)
`triggers[].webhook`	string	-	Ruta del webhook (ej., `/agents/cart-recovery/trigger`)
`triggers[].conditions`	array	`[]`	Condiciones de filtro para el desencadenador
`triggers[].debounce`	string	-	Ventana de debounce (ej., `5m`, `1h`)

Campos de Permisos

Campo	Tipo	Defecto	Descripción
`permissions`	array	`[]`	Alcances de permisos requeridos para rastro de auditoría
`related_agents`	array	`[]`	IDs de agentes a los que este agente puede delegar
`escalation`	string	-	Dónde enrutar cuando el agente tiene incertidumbre (`human`, `supervisor-agent`)

Herramientas: Mapeando a Servidores MCP de Brevo

El campo tools hace referencia a los nombres de módulos del servidor MCP de Brevo. Cada módulo se mapea a un endpoint específico en mcp.brevo.com:

tools:
  # Contactos y Segmentación
  - brevo_contacts                    # /v1/brevo_contacts/mcp
  - brevo_lists                       # /v1/brevo_lists/mcp
  - brevo_segments                    # /v1/brevo_segments/mcp
  - brevo_attributes                  # /v1/brevo_attributes/mcp

  # Campañas y Mensajería
  - 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

  # Analíticas
  - brevo_campaign_analytics          # /v1/brevo_campaign_analytics/mcp

  # CRM de Ventas
  - 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

Usa el mínimo conjunto de herramientas que tu agente necesita. Menos herramientas = mejor razonamiento de IA y respuestas más rápidas. Consulta Servidor MCP de Brevo para todos los módulos disponibles.

Desencadenadores

Desencadenadores de Eventos

Activa el agente cuando algo sucede en tu sistema:

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

Desencadenadores de Horario

Ejecuta el agente en un horario recurrente:

triggers:
  - schedule: "0 9 * * MON"        # Cada lunes a las 9am
    timezone: "America/New_York"
  - schedule: "0 */4 * * *"        # Cada 4 horas
  - schedule: "0 0 1 * *"          # Primer día de cada mes

Desencadenadores de Webhook

Invoca el agente vía HTTP:

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

Cuerpo Markdown: Instrucciones

El cuerpo de la especificación del agente son instrucciones en lenguaje natural. Escríbelo como si estuvieras informando a un marketero experto.

Estructura

# Agent Name

Context paragraph, what this agent does and why.

## Strategy

Step-by-step approach the agent should follow.

## Decision Framework

Rules for making choices (e.g., which channel to use based on cart value).

## Rules

Hard constraints, things the agent must ALWAYS or NEVER do.

## Templates

References to Brevo template IDs, SMS copy, WhatsApp templates.

## Metrics

Events to track for measuring success.

Cadenas Multi-Agente

Para flujos de trabajo complejos, compón múltiples agentes en una cadena:

name: quarterly-retention-campaign
steps:
  - agent: customer-intelligence
    input: |
      Analyze customer segments for Q2 retention campaign.
      Goal: {task}

      Identify:
      1. At-risk customers (declining purchase frequency)
      2. VIP customers (top 10% by LTV)
      3. Win-back candidates (90+ days since last order)

  - agent: campaign-designer
    input: |
      Design retention campaigns for these segments:
      {previous}

      Create differentiated approaches per segment:
      - At-risk: gentle nudge with product recommendations
      - VIP: exclusive early access or loyalty reward
      - Win-back: aggressive discount with urgency

  - agent: campaign-executor
    input: |
      Execute these campaigns via Brevo:
      {previous}

      Use appropriate channels per segment preference.
      Set up A/B tests for subject lines.
      Schedule sends for optimal times.

  - agent: campaign-reporter
    input: |
      Generate the retention campaign launch report:
      {previous}

      Include: segments targeted, campaigns created,
      expected reach, A/B test configurations.

Despliegue

Ejecutar un Agente Programáticamente

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",
  // Solo conecta los servidores MCP listados en el campo tools del 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);    // Rastro de auditoría completo
console.log(result.metrics);      // Eventos rastreados

Ejecutar con Claude Code

# Apunta a tu especificación de agente y deja que Claude la ejecute
claude "Run the agent defined in ./agents/cart-recovery-agent.md for today's abandoned carts"

Programar con Cron

# Ejecutar el agente de inteligencia de cliente cada lunes a las 6am
0 6 * * MON claude --print "Run ./agents/customer-intelligence.md weekly analysis" >> /var/log/tajo-agents.log 2>&1

Próximos Pasos

Servidor MCP de Brevo, Herramientas disponibles y configuración del servidor
Construcción de Tu Primer Agente, Tutorial práctico
Referencia de Skills, Skills de Tajo que se componen con agentes
Descripción General de Arquitectura MCP, Cómo encaja todo

Formato de Especificación de Agentes