Agent Recipes

Real-world agent configurations you can copy, paste, and customize. Each recipe solves a specific problem with a working implementation.

Quick Start

Choose a recipe based on your use case:

Recipe	Use Case	Difficulty
Socratic Tutor	Educational help without giving answers	Easy
Instant Grader	Real-time feedback on student work	Medium
Auto-Facilitator	Workshop time management & clustering	Hard
Culture Guardian	Content moderation for anonymous sessions	Medium
Persona Generator	AI-powered brainstorming assistance	Medium
Design Linter	Enforce visual consistency in workshops	Easy

Recipe 1: Socratic Tutor

Difficulty: Easy Best for: Educational platforms, language learning, homework help Time to setup: 5 minutes

The Problem

You have 30 students working on exercises. Some are stuck for 5+ minutes but don't ask for help. By the time you notice, they've given up or moved on with the wrong answer reinforced.

The Solution

The agent monitors participant activity. When someone's idle for 3+ minutes, it creates a personalized hint sticky note near their cursor position. The hint guides them without revealing the solution.

Configuration

json

{
  "name": "Socratic Tutor",
  "persona": "tutor",
  "instructions": {
    "description": "Monitors student progress and provides Socratic hints when they're stuck",
    "goals": [
      "Help students overcome obstacles independently",
      "Provide guidance through questions, not answers",
      "Build student confidence"
    ],
    "rules": [
      "Never give direct answers - only ask leading questions",
      "Wait at least 3 minutes before intervening",
      "Tailor hints to student's skill level based on previous work",
      "Keep hints short (under 30 words)"
    ],
    "triggers": [
      {
        "event": "participant:idle",
        "condition": "idleTime > 180",
        "action": "generate_hint",
        "params": {
          "prompt": "Student is stuck on: {currentTask}. Generate a Socratic question to guide them. Do NOT give the answer.",
          "style": "question"
        }
      },
      {
        "event": "object:created",
        "condition": "object.type === 'answer-card'",
        "action": "evaluate_answer",
        "params": {
          "prompt": "Check if answer is correct. If wrong, provide ONE guiding question."
        }
      }
    ]
  },
  "maxActionsPerMinute": 10,
  "budgetTokens": 15000
}

Try It

Step 1: Create the agent on your board

bash

curl -X POST https://app.boardapi.io/api/v1/boards/{board_id}/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @socratic-tutor.json

Step 2: Test the idle trigger

Open your board
Stop interacting for 3+ minutes
Watch for a hint sticky note to appear

Tips

Adjust idle time: Change idleTime > 180 (seconds) to fit your lesson pace
Control frequency: Set maxActionsPerMinute: 5 for slower hints
Limit to specific frames: Add "scope": { "frames": ["exercise-frame-id"] }
Monitor token usage: Check /agents/{id}/stats to avoid budget overruns

Recipe 2: Instant Grader

Difficulty: Medium Best for: Quizzes, coding exercises, math practice Time to setup: 10 minutes

The Problem

Students submit answers but only get feedback at the end of class. Meanwhile, they're practicing incorrect methods, making the same mistake 10 times before anyone tells them it's wrong.

The Solution

When students drag their answer card into the "Submit" zone, the agent instantly checks it. Correct answers trigger green confetti. Wrong answers get a hint (but NOT the solution), so students can try again immediately.

Configuration

json

{
  "name": "Instant Grader",
  "persona": "tutor",
  "instructions": {
    "description": "Provides immediate feedback when students submit answers",
    "goals": [
      "Give instant feedback to prevent practicing mistakes",
      "Celebrate correct answers to build momentum",
      "Guide students to self-correct wrong answers"
    ],
    "rules": [
      "Check answers only in the 'submit-zone' frame",
      "For correct answers: create green confetti + encouraging message",
      "For wrong answers: give ONE hint, do not reveal answer",
      "Track attempts - give more detailed hints after 3rd try"
    ],
    "triggers": [
      {
        "event": "object:created",
        "condition": "object.frameId === 'submit-zone' && object.type === 'answer-card'",
        "action": "evaluate_answer",
        "params": {
          "correctAnswer": "{expectedAnswer}",
          "prompt": "Compare student answer to correct answer. Return { correct: boolean, hint?: string }"
        }
      }
    ]
  },
  "scope": {
    "frames": ["submit-zone"],
    "objectTypes": ["answer-card"]
  },
  "maxActionsPerMinute": 20,
  "budgetTokens": 20000
}

Try It

Step 1: Setup your board

Create a frame named "Submit Zone" (note the frame ID)
Add question cards in the main area
Update submit-zone in the config to your frame ID

Step 2: Create the agent

bash

curl -X POST https://app.boardapi.io/api/v1/boards/{board_id}/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @instant-grader.json

Step 3: Test

Create an answer card
Drag it into the Submit Zone
Watch for feedback (confetti or hint)

Tips

For multiple questions: Store expected answers in a custom object property
Partial credit: Modify the prompt to give percentage scores
Different subjects: Adjust the prompt to handle math vs text answers
Privacy: Hints are only visible to the submitter (agent uses visibility: 'private')

Recipe 3: Auto-Facilitator (Scrum Master)

Difficulty: Hard Best for: Retrospectives, design sprints, workshop facilitation Time to setup: 15 minutes

The Problem

Running a retro with 50 people is chaos. You're managing time, clustering sticky notes, moving groups between activities, and trying to keep everyone engaged. You're the bottleneck.

The Solution

The agent handles the mechanical work. It transitions activities on schedule, locks stickies when time's up, auto-clusters similar ideas, and moves clusters to the voting frame. You focus on facilitation, not logistics.

Configuration

json

{
  "name": "Retro Scrum Master",
  "persona": "facilitator",
  "instructions": {
    "description": "Automates retro transitions: timers, clustering, voting setup",
    "goals": [
      "Keep retro on schedule with automatic transitions",
      "Cluster similar ideas to reduce voting fatigue",
      "Handle logistics so facilitator can focus on people"
    ],
    "rules": [
      "Notify 2 minutes before each transition",
      "Lock objects when time expires (no more edits)",
      "Cluster stickies by semantic similarity (not just keywords)",
      "Always explain actions in notifications"
    ],
    "triggers": [
      {
        "event": "timer:tick",
        "condition": "remainingTime === 120",
        "action": "send_notification",
        "params": {
          "message": "2 minutes left! Finish your thoughts.",
          "target": "all"
        }
      },
      {
        "event": "timer:tick",
        "condition": "remainingTime === 0 && phase === 'ideation'",
        "action": "lock_objects",
        "params": {
          "objectTypes": ["sticky_note"],
          "frameId": "current"
        }
      }
    ],
    "schedule": [
      {
        "at": "00:10:00",
        "action": "lock_objects",
        "params": { "objectTypes": ["sticky_note"] }
      },
      {
        "at": "00:11:00",
        "action": "cluster_similar",
        "params": {
          "objectTypes": ["sticky_note"],
          "minSimilarity": 0.75,
          "createLabels": true
        }
      },
      {
        "at": "00:12:00",
        "action": "move_to_frame",
        "params": {
          "clusters": "all",
          "targetFrame": "voting-frame",
          "layout": "grid"
        }
      },
      {
        "at": "00:13:00",
        "action": "send_notification",
        "params": {
          "message": "Voting phase! Click the stickies you think are most important.",
          "target": "all"
        }
      }
    ]
  },
  "maxActionsPerMinute": 30,
  "budgetTokens": 50000,
  "priority": 9
}

Try It

Prerequisites:

Create frames: ideation-frame, voting-frame
Add a timer object (set to 10 minutes for testing)

Step 1: Create the agent

bash

curl -X POST https://app.boardapi.io/api/v1/boards/{board_id}/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @scrum-master.json

Step 2: Run a test session

Start the timer
Add 10+ sticky notes with similar themes
Watch at 10min: stickies lock
Watch at 11min: auto-clustering happens
Watch at 12min: clusters move to voting frame

Tips

Customize phases: Adjust schedule times for your retro format
Clustering threshold: minSimilarity: 0.75 is aggressive. Use 0.6 for looser grouping
High priority: This agent has priority: 9 to avoid conflicts with other agents
Test with 5 people first: Don't run this at scale until you've tested the timings

Recipe 4: Culture Guardian

Difficulty: Medium Best for: Anonymous brainstorms, open forums, classroom discussions Time to setup: 8 minutes

The Problem

You love anonymous brainstorming for psychological safety, but occasionally someone posts something toxic. By the time you see it, 20 people have already read it.

The Solution

The agent checks sentiment when objects are created. If it detects toxicity (personal attacks, profanity, harassment), it changes the sticky to gray and adds a private warning only the author can see. You get a notification to review.

Configuration

json

{
  "name": "Culture Guardian",
  "persona": "moderator",
  "instructions": {
    "description": "Monitors content for toxicity while preserving anonymity",
    "goals": [
      "Catch inappropriate content within seconds",
      "Educate authors without public shaming",
      "Alert facilitator to potential issues"
    ],
    "rules": [
      "Check sentiment on every new sticky note",
      "Flag content with: personal attacks, profanity, harassment, or hate speech",
      "Do NOT flag constructive criticism or negative feedback",
      "Warning message is ONLY visible to author",
      "Facilitator gets a notification, NOT the content (privacy)"
    ],
    "triggers": [
      {
        "event": "object:created",
        "condition": "object.type === 'sticky_note'",
        "action": "check_sentiment",
        "params": {
          "prompt": "Analyze: is this toxic? Return { toxic: boolean, reason?: string }"
        }
      }
    ]
  },
  "scope": {
    "objectTypes": ["sticky_note"]
  },
  "maxActionsPerMinute": 30,
  "visibility": "stealth",
  "budgetTokens": 30000
}

Try It

Step 1: Create the agent

bash

curl -X POST https://app.boardapi.io/api/v1/boards/{board_id}/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @culture-guardian.json

Step 2: Test the filter

Create a normal sticky: "We should improve onboarding"
Create a problematic sticky: "John is an idiot"
Watch the second sticky turn gray with a private warning

Tips

Stealth mode: visibility: 'stealth' means participants don't see the agent on the board
Privacy-first: The agent never exposes who wrote what
False positives: Test with your team's language style - adjust the prompt if needed
Human review: Always have a facilitator available for escalation

Recipe 5: Persona Generator

Difficulty: Medium Best for: Design thinking, user research, empathy mapping Time to setup: 10 minutes

The Problem

Your team starts with "Mom, 30, likes yoga" and needs to create a full empathy map. They either: (a) make up unrealistic details, or (b) spend 45 minutes Googling demographics.

The Solution

Team writes a persona seed (name, age, key trait) on a sticky and drops it in the "Persona Input" zone. The agent generates 10 research-backed empathy map stickies (goals, pains, motivations) and places them in the empathy map quadrants.

Configuration

json

{
  "name": "Persona Generator",
  "persona": "custom",
  "instructions": {
    "description": "Generates empathy map details from persona seeds",
    "goals": [
      "Create realistic persona details based on demographic research",
      "Populate empathy maps automatically to speed up workshops",
      "Provide diverse, research-backed insights"
    ],
    "rules": [
      "Only activate when sticky is created in 'persona-input' zone",
      "Generate exactly 10 stickies: 3 goals, 3 pains, 2 motivations, 2 behaviors",
      "Base details on real demographic research, not stereotypes",
      "Place stickies in the correct empathy map quadrants",
      "Use different colors: goals=green, pains=red, motivations=blue, behaviors=yellow"
    ],
    "triggers": [
      {
        "event": "object:created",
        "condition": "object.frameId === 'persona-input' && object.type === 'sticky_note'",
        "action": "generate_content",
        "params": {
          "prompt": "Given this persona: '{object.content}', generate 10 empathy map insights as JSON array: [{type: 'goal'|'pain'|'motivation'|'behavior', content: string, quadrant: 'thinks'|'feels'|'says'|'does'}]",
          "count": 10
        }
      }
    ]
  },
  "scope": {
    "frames": ["persona-input", "empathy-map"],
    "objectTypes": ["sticky_note"]
  },
  "maxActionsPerMinute": 5,
  "budgetTokens": 40000
}

Try It

Prerequisites:

Create frames: persona-input, empathy-map (with 4 quadrants)

Step 1: Create the agent

bash

curl -X POST https://app.boardapi.io/api/v1/boards/{board_id}/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @persona-generator.json

Step 2: Generate a persona

Create a sticky in "persona-input" frame: "Sarah, 35, software engineer, 2 kids"
Watch the agent create 10 stickies in the empathy map
Review and edit the generated insights

Tips

Limit frequency: maxActionsPerMinute: 5 prevents accidental rapid-fire generation
High token budget: Persona generation uses more tokens (40K)
Edit after generation: Treat AI output as a starting point, not final truth
Combine with research: Have real user research data visible on the board

Recipe 6: Design Linter

Difficulty: Easy Best for: Design sprints, collaborative workshops, visual thinking Time to setup: 5 minutes

The Problem

Your workshop has a design system: red = risks, blue = opportunities, green = solutions. After 20 minutes, the board is full of random colors. Participants forgot the rules and now analysis is impossible.

The Solution

The agent checks every new sticky against the color legend. If someone uses the wrong color, it suggests the correct one (or auto-fixes if you enable strict mode).

Configuration

json

{
  "name": "Design Linter",
  "persona": "custom",
  "instructions": {
    "description": "Enforces workshop color coding rules",
    "goals": [
      "Maintain visual consistency throughout workshop",
      "Remind participants of design system rules",
      "Reduce post-workshop cleanup time"
    ],
    "rules": [
      "Check color on every new sticky note",
      "Color rules: red=risks, blue=opportunities, green=solutions, yellow=questions",
      "If content doesn't match color, propose correction",
      "Auto-fix if 'autoFix' mode enabled, otherwise just suggest"
    ],
    "triggers": [
      {
        "event": "object:created",
        "condition": "object.type === 'sticky_note'",
        "action": "validate_design",
        "params": {
          "colorRules": {
            "red": ["risk", "problem", "challenge", "blocker"],
            "blue": ["opportunity", "idea", "potential"],
            "green": ["solution", "fix", "action"],
            "yellow": ["question", "unclear", "?"]
          },
          "autoFix": false,
          "notifyAuthor": true
        }
      }
    ]
  },
  "scope": {
    "objectTypes": ["sticky_note"]
  },
  "maxActionsPerMinute": 20,
  "budgetTokens": 10000
}

Try It

Step 1: Create the agent

bash

curl -X POST https://app.boardapi.io/api/v1/boards/{board_id}/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @design-linter.json

Step 2: Test the linter

Create a red sticky: "We could try X" (should be blue)
Watch for a notification suggesting color change
Enable "autoFix": true to auto-correct

Tips

Start with suggestions: Set "autoFix": false initially to avoid frustrating participants
Customize rules: Adjust colorRules to match your workshop format
Add to legend: Place a visible legend on the board so participants know the rules
Disable for free exploration: Pause the agent during brainstorm phases

Combining Recipes

You can run multiple agents on the same board. Here are proven combinations:

Combination	Use Case
Socratic Tutor + Instant Grader	Educational platforms with exercises + assessments
Auto-Facilitator + Culture Guardian	Large anonymous retros that need structure + safety
Persona Generator + Design Linter	Design sprints with AI-assisted research + visual standards

Example: Educational Platform

bash

# Create both agents
curl -X POST .../agents -d @socratic-tutor.json
curl -X POST .../agents -d @instant-grader.json

The tutor helps during exercises, the grader checks final submissions. They don't conflict because they watch different zones.

Customizing Recipes

All recipes are starting points. Common customizations:

Change Timing

json

{
  "triggers": [
    {
      "condition": "idleTime > 300"  // Changed from 180 to 300 seconds
    }
  ]
}

Restrict to Frames

json

{
  "scope": {
    "frames": ["frame-id-1", "frame-id-2"]
  }
}

Adjust Personality

json

{
  "rules": [
    "Be encouraging and use positive language",
    "Keep messages under 20 words"
  ]
}

Control Costs

json

{
  "maxActionsPerMinute": 5,    // Slower
  "budgetTokens": 5000          // Lower limit
}

Monitoring & Debugging

After deploying a recipe, monitor its performance:

Check Agent Stats

bash

curl -X GET https://app.boardapi.io/api/v1/boards/{board_id}/agents/{agent_id}/stats \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

json

{
  "total_actions": 45,
  "tokens_spent": 3250,
  "actions_per_minute_avg": 2.5,
  "last_action_at": "2025-11-28T10:30:00Z",
  "status": "active",
  "budget_remaining": 6750
}

View Recent Actions

bash

curl -X GET https://app.boardapi.io/api/v1/boards/{board_id}/agents/{agent_id}/actions?limit=10 \
  -H "Authorization: Bearer YOUR_API_KEY"

Common Issues

Problem	Solution
Agent not triggering	Check `scope` and `condition` - might be too restrictive
Too many actions	Lower `maxActionsPerMinute` or add more conditions
Budget exceeded	Increase `budgetTokens` or optimize prompts
Slow responses	Reduce prompt complexity or lower agent `priority`

Next Steps

Getting Started - Learn agent fundamentals
Agent Presets - Explore more templates
API Reference - Full endpoint documentation
Best Practices - Tips for production

Need Help?

Documentation: docs.boardapi.io
Support: support@boardapi.io
Community Recipes: Share your recipes in our Discord

Agent Recipes ​

Quick Start ​

Recipe 1: Socratic Tutor ​

The Problem ​

The Solution ​

Configuration ​

Try It ​

Tips ​

Recipe 2: Instant Grader ​

The Problem ​

The Solution ​

Configuration ​

Try It ​

Tips ​

Recipe 3: Auto-Facilitator (Scrum Master) ​

The Problem ​

The Solution ​

Configuration ​

Try It ​

Tips ​

Recipe 4: Culture Guardian ​

The Problem ​

The Solution ​

Configuration ​

Try It ​

Tips ​

Recipe 5: Persona Generator ​

The Problem ​

The Solution ​

Configuration ​

Try It ​

Tips ​

Recipe 6: Design Linter ​

The Problem ​

The Solution ​

Configuration ​

Try It ​

Tips ​

Combining Recipes ​

Customizing Recipes ​

Change Timing ​

Restrict to Frames ​

Adjust Personality ​

Control Costs ​

Monitoring & Debugging ​

Check Agent Stats ​

View Recent Actions ​

Common Issues ​

Next Steps ​

Need Help? ​

Agent Recipes

Quick Start

Recipe 1: Socratic Tutor

The Problem

The Solution

Configuration

Try It

Tips

Recipe 2: Instant Grader

The Problem

The Solution

Configuration

Try It

Tips

Recipe 3: Auto-Facilitator (Scrum Master)

The Problem

The Solution

Configuration

Try It

Tips

Recipe 4: Culture Guardian

The Problem

The Solution

Configuration

Try It

Tips

Recipe 5: Persona Generator

The Problem

The Solution

Configuration

Try It

Tips

Recipe 6: Design Linter

The Problem

The Solution

Configuration

Try It

Tips

Combining Recipes

Customizing Recipes

Change Timing

Restrict to Frames

Adjust Personality

Control Costs

Monitoring & Debugging

Check Agent Stats

View Recent Actions

Common Issues

Next Steps

Need Help?