Agent Specification Format

Tajo agents are defined in markdown files. Each file contains YAML frontmatter (identity, tools, constraints) and a markdown body (instructions, strategy, rules). This format is inspired by production agent patterns used in multi-agent orchestration systems.

File Structure

---
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...

Frontmatter Fields

Required Fields

Field	Type	Description
`name`	string	Unique identifier in kebab-case (e.g., `cart-recovery-agent`)
`description`	string	What this agent does (max 160 chars)
`version`	string	Semantic version (e.g., `1.0.0`)
`tools`	array	Brevo MCP server modules this agent can access

Behavioral Fields

Field	Type	Default	Description
`temperature`	float	`0.3`	LLM temperature. Lower = more deterministic. Use 0.1-0.2 for data operations, 0.3-0.5 for campaign design
`max_tokens`	integer	`4096`	Maximum response length per turn
`model`	string	`claude-sonnet-4-6`	LLM model to use

Trigger Fields

Field	Type	Default	Description
`triggers`	array	`[]`	Events, schedules, or webhooks that activate this agent
`triggers[].event`	string	-	Event name (e.g., `cart_abandoned`, `customer_created`)
`triggers[].schedule`	string	-	Cron expression (e.g., `0 9 * * *` for daily 9am)
`triggers[].webhook`	string	-	Webhook path (e.g., `/agents/cart-recovery/trigger`)
`triggers[].conditions`	array	`[]`	Filter conditions for the trigger
`triggers[].debounce`	string	-	Debounce window (e.g., `5m`, `1h`)

Permission Fields

Field	Type	Default	Description
`permissions`	array	`[]`	Required permission scopes for audit trail
`related_agents`	array	`[]`	Agent IDs this agent can delegate to
`escalation`	string	-	Where to route when agent is uncertain (`human`, `supervisor-agent`)

Tools: Mapping to Brevo MCP Servers

The tools field references Brevo MCP server module names. Each module maps to a specific endpoint on mcp.brevo.com:

tools:
  # Contacts & Segmentation
  - brevo_contacts                    # /v1/brevo_contacts/mcp
  - brevo_lists                       # /v1/brevo_lists/mcp
  - brevo_segments                    # /v1/brevo_segments/mcp
  - brevo_attributes                  # /v1/brevo_attributes/mcp

  # Campaigns & Messaging
  - 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

  # Analytics
  - brevo_campaign_analytics          # /v1/brevo_campaign_analytics/mcp

  # Sales CRM
  - 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 the minimum set of tools your agent needs. Fewer tools = better AI reasoning and faster responses. See Brevo MCP Server for all available modules.

Triggers

Event Triggers

Activate the agent when something happens in your system:

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

Schedule Triggers

Run the agent on a recurring schedule:

triggers:
  - schedule: "0 9 * * MON"        # Every Monday at 9am
    timezone: "America/New_York"
  - schedule: "0 */4 * * *"        # Every 4 hours
  - schedule: "0 0 1 * *"          # First day of each month

Webhook Triggers

Invoke the agent via HTTP:

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

Markdown Body: Instructions

The body of the agent spec is natural language instructions. Write it as if briefing a skilled marketer:

Structure

# 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.

Writing Effective Instructions

Be specific about strategy, not just goals:

## Bad
Re-engage churned customers.

## Good
When a customer hasn't purchased in 90+ days:
1. Check their last 3 orders for product category preferences
2. Create a personalized discount based on AOV (10% if AOV > $100, 15% if < $100)
3. Send email with subject line referencing their preferred category
4. Wait 72 hours — if no open, send SMS with discount code
5. Wait 7 days — if no purchase, mark as deep-churn and stop sequence

Define guardrails explicitly:

## Rules
- NEVER send more than 3 messages per sequence
- NEVER contact customers who unsubscribed
- ALWAYS check if the customer converted before sending the next step
- ALWAYS respect quiet hours (no SMS 9pm-9am local time)
- If unsure about a decision, escalate to human review

Multi-Agent Chains

For complex workflows, compose multiple agents in a chain. Each agent handles one phase, passing context to the next:

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.

Chain Variables

Variable	Description
`{task}`	The original goal/request
`{previous}`	Output from the previous step
`{step_N}`	Output from step N (0-indexed)
`{artifacts_dir}`	Directory for file outputs

Pre-Built Agent Specs

Campaign Orchestrator

---
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
---

# Campaign Orchestrator

You are a multi-channel marketing campaign specialist.
Given a campaign brief, you design, build, and launch
campaigns across email, SMS, and WhatsApp via Brevo.

## Process
1. Parse the campaign brief (audience, message, goal, timeline)
2. Create or identify the target segment in Brevo
3. Select the best channel(s) based on audience preference data
4. Build campaign content using existing templates or creating new ones
5. Configure send schedule and A/B tests
6. Launch and report initial delivery metrics

## Channel Selection
- Email: default for all campaigns
- SMS: add for time-sensitive offers or cart recovery
- WhatsApp: add for conversational campaigns or high-value segments

## Rules
- ALWAYS preview campaigns before sending
- NEVER send to unsubscribed contacts
- ALWAYS set up tracking for campaign attribution
- Maximum 2 A/B test variants per campaign

Customer Intelligence Agent

---
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"
---

# Customer Intelligence Agent

You analyze customer data in Brevo to generate actionable
segments and insights for marketing teams.

## Weekly Analysis
1. Pull contact activity data from campaign analytics
2. Calculate RFM scores (Recency, Frequency, Monetary)
3. Identify segment shifts (customers moving between tiers)
4. Flag churn risks (declining engagement over 4+ weeks)
5. Generate segment recommendations for upcoming campaigns

## Segment Definitions
- Champions: R=5, F=5, M=5 — recent, frequent, high-value
- Loyal: R>=3, F>=4, M>=3 — consistent buyers
- At Risk: R<=2, F>=3, M>=3 — were loyal, now fading
- Hibernating: R=1, F>=2, M>=2 — long gone, were once active
- New: first purchase in last 30 days

## Output
Produce a markdown report with:
- Segment sizes and week-over-week changes
- Top 10 at-risk customers by LTV
- Recommended actions per segment
- Suggested campaign themes for the week

Deployment

Running an Agent Programmatically

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",
  // Only connect the MCP servers listed in the agent's tools field
  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);    // Full audit trail
console.log(result.metrics);      // Events tracked

Running via Claude Code

# Point to your agent spec and let Claude execute it
claude "Run the agent defined in ./agents/cart-recovery-agent.md for today's abandoned carts"

Scheduling with Cron

# Run the customer intelligence agent every Monday at 6am
0 6 * * MON claude --print "Run ./agents/customer-intelligence.md weekly analysis" >> /var/log/tajo-agents.log 2>&1

Next Steps

Brevo MCP Server — Available tools and server configuration
Building Your First Agent — Hands-on tutorial
Skills Reference — Tajo Skills that compose with agents
MCP Architecture Overview — How it all fits together