AI Agents - Getting Started

Add autonomous AI assistants to your boards that react to events and help your users in real-time.

What are AI Agents?

AI Agents are autonomous assistants that live on your boards and react to events automatically. Unlike traditional chatbots, agents observe what's happening on the board and take action based on triggers you define.

Think of them as smart helpers that:

• Watch for specific events (object created, user idle, timer tick)
• Decide when to act based on conditions you set
• Execute actions automatically (create objects, send notifications, analyze content)

Real-world Examples

Language Learning Tutor

• Watches for student answer cards
• Uses AI to evaluate answers
• Gives hints without revealing the solution

Activity Timer

• Triggers every 10 minutes
• Creates reminder notifications
• Highlights the next activity frame

Progress Tracker

• Monitors completion in breakout rooms
• Updates a live dashboard
• Notifies the host when groups finish

Quick Start

Create your first AI agent in 5 minutes.

Prerequisites

• BoardAPI account with API key (get one here)
• An existing board (or create one via API)
• Basic knowledge of REST APIs

Step 1: Create a Simple Timer Agent

Let's start with a timer that reminds participants to switch activities every 10 minutes.

curl -X POST https://app.boardapi.io/api/v1/boards/{board_uuid}/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Activity Timer",
    "persona": "timer",
    "instructions": {
      "description": "Reminds participants to switch activities",
      "goals": ["Keep the session on schedule"],
      "rules": ["Trigger every 10 minutes", "Create visible notifications"],
      "triggers": [
        {
          "event": "timer:tick",
          "action": "send_notification",
          "params": {
            "interval": "10min",
            "message": "Time to move to the next activity!"
          }
        }
      ]
    }
  }'

Response:

{
  "id": "agent-uuid-123",
  "name": "Activity Timer",
  "persona": "timer",
  "status": "active",
  "created_at": "2025-11-28T10:00:00Z"
}

Step 2: See Your Agent in Action

Open your board in the browser. You'll see:

1. An agent object on the canvas (looks like a card with the agent's name)
2. Status indicator showing it's active
3. Notification objects appearing every 10 minutes

Step 3: Pause or Modify

You can pause the agent at any time:

curl -X POST https://app.boardapi.io/api/v1/boards/{board_uuid}/agents/{agent_id}/pause \
  -H "Authorization: Bearer YOUR_API_KEY"

Core Concepts

Personas

Agents have predefined roles that determine their behavior:

Persona	Purpose	AI Required
tutor	Educational assistance, answer checking	Yes
moderator	Monitor activity, enforce rules	Optional
timer	Schedule-based actions	No
facilitator	Guide participants through activities	Optional
custom	Fully customizable behavior	Optional

Instructions

Every agent needs clear instructions with four components:

{
  "description": "What this agent does (1-2 sentences)",
  "goals": ["Primary objective", "Secondary objective"],
  "rules": ["Never do X", "Always do Y"],
  "triggers": [
    {
      "event": "when this happens",
      "action": "do this",
      "params": { /* action parameters */ }
    }
  ]
}

Example - Answer Checker:

{
  "description": "Checks student answers and provides hints",
  "goals": [
    "Help students learn independently",
    "Provide guidance without giving away answers"
  ],
  "rules": [
    "Never reveal the full answer",
    "Give progressive hints",
    "Encourage effort"
  ],
  "triggers": [
    {
      "event": "object:created",
      "condition": "object.type === 'answer_card'",
      "action": "evaluate_answer"
    }
  ]
}

Lifecycle & Status

Agents can be in one of these states:

• active - Running and processing events
• paused - Temporarily stopped (can be resumed)
• error - Failed (check logs for details)

Rate Limiting & Budgets

Protect against runaway agents with built-in limits:

{
  "maxActionsPerMinute": 10,    // Max 10 actions per minute
  "budgetTokens": 10000          // Max 10K AI tokens per session
}

Default limits:

• 10 actions per minute
• Unlimited tokens (but you can set a budget)

When limits are exceeded, the agent pauses automatically and logs an error.

Event Triggers

Agents respond to these event types:

Object Events

• object:created - When any object is added to the board
• object:updated - When an object is modified
• object:deleted - When an object is removed

Participant Events

• participant:joined - User enters the board
• participant:left - User leaves
• participant:idle - No activity for X seconds

Timer Events

• timer:tick - Periodic interval (customizable)
• session:ending - X minutes before session ends

Conditional Triggers

{
  "event": "object:created",
  "condition": "object.type === 'sticky-note' && object.color === 'red'",
  "action": "flag_for_review"
}

Actions

What agents can do:

Create Objects

{
  "action": "create_object",
  "params": {
    "type": "notification",
    "content": "Great job!",
    "position": "center"
  }
}

Send Notifications

{
  "action": "send_notification",
  "params": {
    "message": "Room 2 needs help",
    "target": "host"
  }
}

AI Evaluation (requires AI persona)

{
  "action": "evaluate_answer",
  "params": {
    "prompt": "Check if the answer is correct. Give a hint if wrong."
  }
}

Next Steps

Now that you understand the basics, explore:

• Agent Recipes - Copy-paste ready configurations for common use cases
• Agent Presets - Ready-to-use agent templates
• Trigger Reference - Complete list of events and conditions
• API Reference - Full API documentation
• Best Practices - Tips for building effective agents

Common Use Cases

Educational Platforms

• Tutoring agents that check homework and give hints
• Progress trackers that show completion rates
• Timer agents for timed exercises

Workshops & Facilitation

• Activity timers for breakout sessions
• Room monitors that alert facilitators when groups are stuck
• Summarizers that compile notes at the end

Collaborative Work

• Moderators that flag inappropriate content
• Notification agents that remind users of deadlines
• Analytics agents that track engagement

Ready to build? Check out the Agent Recipes guide for copy-paste ready configurations, or explore Agent Presets for templates you can customize.