Agent Presets

NOTE

Documentation updated: November 28, 2025

Agent Presets are pre-configured templates that make it easy to add common AI assistants to your boards without writing complex configurations from scratch.

What are Presets?

Presets are ready-to-use agent templates with predefined:

• Persona - Role and behavior (Tutor, Moderator, Timer, etc.)
• Instructions - Goals, rules, and triggers
• Default limits - Rate limiting and token budgets

You can use presets as-is or customize them to fit your specific needs.

Available Presets

Preset	Category	Description	Best For
tutor	Education	Educational assistant that helps students without giving direct answers	Language learning, homework help, Q&A
moderator	Facilitation	Session moderator that monitors rooms and manages time	Large workshops, breakout sessions, classroom management
timer	Productivity	Time management assistant that switches activities on schedule	Workshops, sprints, timed exercises

Tutor Preset

Purpose: Help students learn by providing hints and guidance, not direct answers.

Default Behavior:

• Evaluates student answers
• Provides hints when students are stuck (> 3 minutes idle)
• Gives encouraging feedback
• Adapts difficulty based on performance

Triggers:

• object:created with type answer-card → Evaluate answer
• participant:idle for > 3 minutes → Generate hint

Use Cases:

• Language learning platforms
• Homework assistance
• Educational games
• Interactive tutorials

Moderator Preset

Purpose: Monitor multiple rooms and keep sessions on track.

Default Behavior:

• Tracks activity across all frames/rooms
• Sends time warnings (2 minutes before end)
• Notifies facilitator when rooms go silent (> 5 minutes)
• Summarizes discussions at end of session

Triggers:

• timer:tick at 2 minutes remaining → Send notification
• participant:idle for > 5 minutes → Notify teacher

Schedule:

• 5 minutes before session end → Summarize all frames

Use Cases:

• Large workshops with breakout rooms
• Classroom management
• Multi-team brainstorming
• Conference sessions

Timer Preset

Purpose: Manage activity timing and transitions.

Default Behavior:

• Sends notifications at regular intervals
• Switches between activities automatically
• Keeps sessions on schedule

Schedule:

• Every 10 minutes → Send transition notification

Use Cases:

• Pomodoro timers
• Workshop agendas
• Sprint planning
• Timed exercises

Using Presets

1. List Available Presets

curl -X GET https://app.boardapi.io/api/v1/agent-presets \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

[
  {
    "id": "uuid",
    "persona": "tutor",
    "name": "AI Tutor",
    "description": "Helps students with assignments, gives hints",
    "category": "education",
    "default_instructions": {
      "description": "You are a teaching assistant...",
      "goals": ["Help students fix errors", "Give helpful hints"],
      "rules": ["Never give direct answers", "Be supportive"],
      "triggers": [...]
    },
    "configurable_fields": ["description", "goals", "rules"]
  }
]

2. Get Specific Preset

curl -X GET https://app.boardapi.io/api/v1/agent-presets/tutor \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

3. Create Agent from Preset

Use the preset's default_instructions as a starting point:

curl -X POST https://app.boardapi.io/api/v1/boards/BOARD_ID/agents \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Tutor",
    "persona": "tutor",
    "instructions": {
      "description": "You are a teaching assistant for a language school",
      "goals": [
        "Help students fix errors",
        "Give helpful hints",
        "Adapt difficulty"
      ],
      "rules": [
        "Never give direct answers - only guiding questions",
        "Be polite and supportive",
        "If student is stuck > 3 min - offer hint"
      ],
      "triggers": [
        {
          "event": "object:created",
          "condition": "object.type === '\''answer-card'\''",
          "action": "evaluate_answer"
        }
      ]
    }
  }'

Customizing Presets

Each preset has configurable_fields that indicate which parts can be safely modified:

Override Default Goals

{
  "name": "Math Tutor",
  "persona": "tutor",
  "instructions": {
    "description": "You are a math teaching assistant",
    "goals": [
      "Help students understand math concepts",
      "Check calculations step-by-step",
      "Explain common mistakes"
    ],
    "rules": [...],  // Keep preset rules
    "triggers": [...] // Keep preset triggers
  }
}

Add Custom Triggers

Extend preset triggers with your own:

{
  "persona": "tutor",
  "instructions": {
    "description": "...",
    "goals": [...],
    "rules": [...],
    "triggers": [
      // Preset triggers
      {
        "event": "object:created",
        "condition": "object.type === 'answer-card'",
        "action": "evaluate_answer"
      },
      // Your custom trigger
      {
        "event": "object:deleted",
        "condition": "object.createdBy === 'student'",
        "action": "send_notification",
        "params": { "message": "Student needs help!" }
      }
    ]
  }
}

Adjust Rate Limits

Control how frequently the agent acts:

{
  "name": "Calm Tutor",
  "persona": "tutor",
  "maxActionsPerMinute": 5,  // Slower than default (10)
  "budgetTokens": 5000,       // Limit AI token usage
  "instructions": {...}
}

Scope Limitations

Restrict agent to specific frames or object types:

{
  "name": "Room A Tutor",
  "persona": "tutor",
  "scope": {
    "frames": ["frame-uuid-1", "frame-uuid-2"],
    "objectTypes": ["sticky_note", "text"]
  },
  "instructions": {...}
}

Creating Custom Agents

When presets don't fit your needs, create a fully custom agent:

{
  "name": "Custom Assistant",
  "persona": "custom",
  "instructions": {
    "description": "Your custom agent behavior...",
    "goals": ["Your custom goals..."],
    "rules": ["Your custom rules..."],
    "triggers": [
      {
        "event": "YOUR_EVENT",
        "action": "YOUR_ACTION"
      }
    ]
  }
}

Available Events:

• object:created - New object added to board
• object:updated - Object properties changed
• object:deleted - Object removed
• participant:joined - User joined board
• participant:idle - User inactive for X minutes
• timer:tick - Timer countdown update
• message:sent - Chat message received

Available Actions:

• evaluate_answer - Check student answer
• generate_hint - Create helpful hint
• send_notification - Notify users
• summarize - Create summary
• notify_teacher - Alert facilitator

Best Practices

1. Start with Presets

Always check if a preset matches your use case before creating custom agents. Presets are:

• Battle-tested
• Optimized for common scenarios
• Include sensible defaults

2. Test Incrementally

When customizing:

1. Start with preset defaults
2. Change one field at a time
3. Test on a sample board
4. Monitor agent actions via /agents/:id/actions

3. Monitor Token Usage

Check agent statistics to avoid budget overruns:

curl -X GET https://app.boardapi.io/api/v1/boards/BOARD_ID/agents/AGENT_ID/stats \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

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

4. Use Scope Limitations

Prevent agents from interfering with each other:

{
  "name": "Question Agent",
  "scope": {
    "frames": ["quiz-frame"],
    "objectTypes": ["question-card"]
  }
}

Next Steps

• Agent Recipes - Copy-paste ready configurations for common scenarios
• API Reference - Full endpoint documentation
• Agent Events - Available event types and triggers
• Best Practices - Tips for production use

Need Help?

• Documentation: docs.boardapi.io
• Support: support@boardapi.io