Tasks - Agentbase Docs

Tasks enable agents to break down complex objectives into manageable units of work, track progress, and coordinate execution across multiple steps and agents.

Overview

The Tasks primitive provides a structured way to define, assign, execute, and monitor discrete units of work. Unlike workflows which define processes, tasks represent individual actionable items that can be tracked, prioritized, and completed independently or as part of larger objectives. Tasks are essential for:

Work Breakdown: Decompose complex goals into manageable chunks
Progress Tracking: Monitor completion status and progress
Prioritization: Organize work by importance and urgency
Delegation: Assign tasks to specific agents or humans
Dependencies: Define task relationships and execution order
Accountability: Track who did what and when

Task Creation

Agents can create tasks autonomously or from user requests

Status Tracking

Track task lifecycle from creation to completion

Dependencies

Define task relationships and execution order

Collaboration

Assign tasks to agents or human team members

How Tasks Work

When you enable tasks for an agent:

Creation: Tasks are created with description, priority, and metadata
Assignment: Tasks assigned to agents or humans with appropriate context
Execution: Assigned party works on and completes task
Tracking: Status updates tracked throughout lifecycle
Completion: Task marked complete with results and artifacts
Review: Optional review and approval processes

Persistent State: Tasks persist across sessions and can be resumed at any time, making them ideal for long-running work.

Task States

Lifecycle States

{
  status: "pending" | "in_progress" | "blocked" | "completed" | "cancelled"
}

pending: Task created but not started
in_progress: Actively being worked on
blocked: Waiting for dependency or external input
completed: Successfully finished
cancelled: Abandoned or no longer needed

Priority Levels

{
  priority: "critical" | "high" | "medium" | "low"
}

Code Examples

Basic Task Creation

import { Agentbase } from '@agentbase/sdk';

const agentbase = new Agentbase({
  apiKey: process.env.AGENTBASE_API_KEY
});

// Agent creates tasks autonomously
const result = await agentbase.runAgent({
  message: "Plan the launch of our new product next month",
  capabilities: {
    tasks: {
      enabled: true
    }
  },
  system: `Break down the product launch into specific tasks.

  For each task:
  - Clear, actionable description
  - Appropriate priority
  - Estimated duration
  - Required resources
  - Dependencies on other tasks`
});

// Agent creates structured task list
console.log('Tasks created:', result.tasks);

Create Task Manually

// Explicitly create a task
const task = await agentbase.createTask({
  title: "Review Q4 financial reports",
  description: "Analyze Q4 financials and prepare summary for board meeting",
  priority: "high",
  assignee: "finance_agent",
  dueDate: "2024-02-15",
  tags: ["finance", "quarterly-review"],
  metadata: {
    department: "finance",
    estimatedHours: 4
  }
});

console.log('Task created:', task.id);

Task with Dependencies

// Create tasks with dependencies
const task1 = await agentbase.createTask({
  title: "Design database schema",
  priority: "high"
});

const task2 = await agentbase.createTask({
  title: "Implement API endpoints",
  priority: "high",
  dependencies: [task1.id], // Depends on task1
  blockedUntil: task1.id
});

const task3 = await agentbase.createTask({
  title: "Write API documentation",
  priority: "medium",
  dependencies: [task2.id] // Depends on task2
});

// Tasks execute in order: task1 → task2 → task3

Assign Task to Agent

// Assign task and let agent complete it
const result = await agentbase.runAgent({
  message: "Complete task: Write blog post about new features",
  taskId: task.id,
  capabilities: {
    tasks: {
      enabled: true,
      autoUpdate: true // Automatically update task status
    }
  }
});

// Agent works on task and updates status
console.log('Task status:', result.task.status);
console.log('Task result:', result.task.result);

Query Tasks

// Get all pending tasks
const pendingTasks = await agentbase.getTasks({
  status: "pending",
  priority: ["high", "critical"],
  sortBy: "priority",
  limit: 20
});

// Get tasks by tag
const financeTasks = await agentbase.getTasks({
  tags: ["finance"],
  status: ["pending", "in_progress"]
});

// Get overdue tasks
const overdueTasks = await agentbase.getTasks({
  overdue: true,
  assignee: "current_user"
});

console.log('Pending tasks:', pendingTasks);

Update Task Status

// Update task progress
await agentbase.updateTask(taskId, {
  status: "in_progress",
  progress: 0.5, // 50% complete
  notes: "Completed research phase, starting implementation"
});

// Mark task complete
await agentbase.updateTask(taskId, {
  status: "completed",
  progress: 1.0,
  result: {
    output: "Blog post draft",
    artifacts: ["blog-post.md"],
    metrics: {
      wordCount: 1500,
      timeSpent: "3 hours"
    }
  }
});

Recurring Tasks

// Create recurring task
const recurringTask = await agentbase.createTask({
  title: "Generate weekly analytics report",
  description: "Compile and send weekly performance metrics",
  priority: "medium",
  recurring: {
    enabled: true,
    schedule: "0 9 * * 1", // Every Monday at 9 AM
    timezone: "America/New_York"
  },
  assignee: "analytics_agent"
});

// Agent automatically creates new instance each week

Task Templates

// Create task template
const template = await agentbase.createTaskTemplate({
  name: "onboard_new_customer",
  title: "Onboard new customer: {{customerName}}",
  tasks: [
    {
      title: "Send welcome email",
      priority: "high",
      assignee: "email_agent"
    },
    {
      title: "Create account in CRM",
      priority: "high",
      assignee: "crm_agent",
      dependencies: [0] // Depends on welcome email
    },
    {
      title: "Schedule kickoff call",
      priority: "medium",
      assignee: "scheduling_agent",
      dependencies: [1]
    }
  ]
});

// Use template to create tasks
const tasks = await agentbase.createTasksFromTemplate("onboard_new_customer", {
  customerName: "Acme Corp",
  customerEmail: "[email protected]"
});

Use Cases

1. Project Management

Break down projects into trackable tasks:

const projectAgent = await agentbase.runAgent({
  message: "Plan the development of our mobile app",
  capabilities: {
    tasks: {
      enabled: true
    }
  },
  system: `Create a comprehensive task breakdown for mobile app development.

  Include tasks for:
  - Requirements gathering
  - Design (UI/UX)
  - Frontend development
  - Backend API development
  - Testing (unit, integration, E2E)
  - Deployment
  - Documentation

  For each task:
  - Assign to appropriate team/agent
  - Set realistic estimates
  - Define dependencies
  - Specify acceptance criteria`
});

// Agent creates structured project plan with tasks

2. Content Creation Pipeline

Manage content creation workflow:

const contentTasks = await agentbase.runAgent({
  message: "Create tasks for this month's blog content",
  capabilities: {
    tasks: {
      enabled: true
    }
  },
  system: `Create tasks for 4 blog posts this month.

  For each post:
  1. Research topic (priority: high)
  2. Draft content (depends on research)
  3. Create graphics (depends on draft)
  4. SEO optimization (depends on draft)
  5. Editorial review (depends on all above)
  6. Publish (depends on review approval)

  Stagger due dates throughout the month.`
});

3. Customer Onboarding

Automate onboarding task creation:

const onboardingAgent = await agentbase.runAgent({
  message: "Create onboarding tasks for new customer: Acme Corp",
  context: {
    customer: {
      name: "Acme Corp",
      plan: "enterprise",
      employees: 500
    }
  },
  capabilities: {
    tasks: {
      enabled: true
    }
  },
  system: `Create onboarding task list:

  Day 1:
  - Send welcome email
  - Create accounts
  - Send access credentials

  Week 1:
  - Schedule kickoff call
  - Complete setup call
  - Share documentation

  Week 2:
  - Check-in call
  - Address questions
  - Gather feedback

  Assign tasks to appropriate team members.`
});

4. Incident Response

Create incident resolution tasks:

const incidentAgent = await agentbase.runAgent({
  message: "Critical: Production database is down",
  capabilities: {
    tasks: {
      enabled: true
    }
  },
  system: `Create incident response tasks:

  Immediate (Priority: Critical):
  - Alert on-call engineer
  - Create status page update
  - Start incident war room

  Investigation (Priority: High):
  - Check database logs
  - Review recent deployments
  - Analyze error patterns

  Resolution (Priority: High):
  - Identify root cause
  - Implement fix
  - Verify service restored

  Follow-up (Priority: Medium):
  - Write post-mortem
  - Document lessons learned
  - Create prevention tasks

  Track all tasks in incident ticket.`
});

5. Daily Standup Automation

Generate daily task summaries:

const standupAgent = await agentbase.runAgent({
  message: "Generate my standup update",
  capabilities: {
    tasks: {
      enabled: true
    }
  },
  system: `Create standup update based on my tasks:

  Yesterday:
  - List completed tasks
  - Note any blockers

  Today:
  - List in-progress tasks
  - Highlight priorities

  Blockers:
  - List any blocked tasks
  - Identify what's needed to unblock

  Format as concise standup message.`
});

6. Sales Pipeline Tasks

Track sales activities:

const salesAgent = await agentbase.runAgent({
  message: "Create follow-up tasks for new lead: Jane Smith",
  context: {
    lead: {
      name: "Jane Smith",
      company: "Tech Startup Inc",
      interest: "Enterprise plan"
    }
  },
  capabilities: {
    tasks: {
      enabled: true
    }
  },
  system: `Create sales follow-up tasks:

  Day 1:
  - Send personalized intro email
  - Connect on LinkedIn

  Day 3:
  - Follow-up call
  - Send product demo video

  Day 7:
  - Schedule live demo
  - Send pricing information

  Day 14:
  - Check-in email
  - Share case studies

  Set reminders and track completion.`
});

Best Practices

Task Design

Keep Tasks Atomic

// Good: Specific, single-purpose tasks
await agentbase.createTask({
  title: "Write introduction section",
  description: "Draft the introduction for the blog post (200-300 words)"
});

await agentbase.createTask({
  title: "Create featured image",
  description: "Design featured image for blog post (1200x630px)"
});

// Avoid: Overly broad tasks
await agentbase.createTask({
  title: "Complete blog post",
  description: "Do everything for the blog post"
});

Use Clear Descriptions

// Good: Clear, actionable description
{
  title: "Review pull request #1234",
  description: `Review PR #1234:
  - Check code quality and style
  - Verify tests pass
  - Ensure documentation updated
  - Approve or request changes`
}

// Avoid: Vague description
{
  title: "Check PR",
  description: "Look at the code"
}

Set Realistic Due Dates

// Include estimated duration
{
  title: "Implement user authentication",
  dueDate: "2024-02-15",
  estimatedHours: 8,
  metadata: {
    complexity: "high",
    dependencies: ["database-setup", "api-framework"]
  }
}

Use Tags for Organization

// Organize tasks with tags
{
  title: "Fix login bug",
  tags: ["bug", "auth", "high-priority", "frontend"],
  priority: "high"
}

// Query by tags later
const authTasks = await agentbase.getTasks({
  tags: ["auth"]
});

Task Management

Review Tasks Regularly: Set up periodic reviews of task lists to update priorities and remove obsolete tasks.

Prioritize Effectively

system: `Prioritize tasks using:

Critical: System down, security breach, data loss
High: Blocking other work, customer-facing issues
Medium: Important but not urgent
Low: Nice to have, future improvements

Consider:
- Business impact
- Dependencies
- Deadlines
- Resource availability`

Handle Blocked Tasks

// Mark task as blocked
await agentbase.updateTask(taskId, {
  status: "blocked",
  blockReason: "Waiting for design approval",
  blockedBy: designTaskId,
  blockedUntil: "2024-02-10"
});

// Automatically unblock when dependency completes

Track Time and Progress

// Update progress regularly
await agentbase.updateTask(taskId, {
  progress: 0.75,
  timeSpent: 6, // hours
  notes: "API implementation complete, working on tests"
});

Archive Completed Tasks

// Periodically archive old completed tasks
async function archiveOldTasks() {
  const oldTasks = await agentbase.getTasks({
    status: "completed",
    completedBefore: "2024-01-01" // Older than 30 days
  });

  for (const task of oldTasks) {
    await agentbase.archiveTask(task.id);
  }
}

Collaboration

Assign Tasks Appropriately

// Assign based on expertise
const task = await agentbase.createTask({
  title: "Optimize database queries",
  assignee: "database_specialist_agent",
  ccUsers: ["team_lead", "backend_team"]
});

// Or let agent decide
message: "Assign this task to the best team member",
system: "Consider workload, expertise, and availability"

Add Context and Resources

{
  title: "Fix checkout page error",
  description: "...",
  resources: [
    { type: "error_log", url: "..." },
    { type: "screenshot", url: "..." },
    { type: "documentation", url: "..." }
  ],
  context: {
    errorMessage: "Payment gateway timeout",
    affectedUsers: 127,
    firstOccurred: "2024-01-15T10:30:00Z"
  }
}

Enable Comments and Updates

// Add comments to tasks
await agentbase.addTaskComment(taskId, {
  author: "agent_123",
  text: "Completed initial investigation. Root cause identified.",
  timestamp: new Date().toISOString()
});

// Subscribe to task updates
await agentbase.subscribeToTask(taskId, {
  userId: currentUser.id,
  notifications: ["status_change", "comments", "completion"]
});

Integration with Other Primitives

With Workflow

Combine tasks with workflows:

const workflow = {
  name: "feature_development",
  steps: [
    {
      id: "create_tasks",
      type: "agent_task",
      config: {
        message: "Break down feature into development tasks",
        capabilities: { tasks: { enabled: true } }
      }
    },
    {
      id: "assign_tasks",
      type: "agent_task",
      config: {
        message: "Assign tasks to team members"
      }
    },
    {
      id: "monitor_progress",
      type: "agent_task",
      config: {
        message: "Monitor task completion",
        schedule: "0 9 * * *" // Check daily
      }
    }
  ]
};

Learn more: Workflow Primitive

With Memory

Remember task preferences:

const result = await agentbase.runAgent({
  message: "Create tasks for the new project",
  memory: {
    namespace: `user_${userId}`,
    enabled: true
  },
  capabilities: {
    tasks: { enabled: true }
  }
});

// Agent remembers user's preferred task structure

Learn more: Memory Primitive

With Scheduling

Schedule task creation:

// Auto-create tasks on schedule
await agentbase.scheduleAgent({
  schedule: "0 9 * * 1", // Every Monday
  message: "Create tasks for this week's sprint",
  capabilities: {
    tasks: { enabled: true }
  }
});

Learn more: Scheduling Primitive

Performance Considerations

Task Volume

Scalability: System handles thousands of active tasks
Query Performance: Index tasks by status, priority, assignee
Archival: Archive completed tasks to maintain performance

// Efficient task querying
const tasks = await agentbase.getTasks({
  status: ["pending", "in_progress"],
  assignee: currentAgent,
  limit: 50, // Paginate results
  offset: 0
});

Real-time Updates

Webhooks: Receive real-time task updates
Polling: Query for task changes periodically
WebSocket: Subscribe to live task updates

// Subscribe to task updates
const subscription = await agentbase.subscribeToTasks({
  filters: {
    assignee: "current_agent"
  },
  onUpdate: (task) => {
    console.log('Task updated:', task);
  }
});

Troubleshooting

Tasks Not Being Created

Problem: Agent doesn’t create tasks as expectedSolutions:

Verify tasks capability is enabled
Check system prompt includes task creation instructions
Ensure agent has permissions to create tasks
Review agent response for task creation attempts

// Debug task creation
const result = await agentbase.runAgent({
  message: "Create tasks for project",
  capabilities: {
    tasks: {
      enabled: true,
      debug: true
    }
  }
});

console.log('Task creation attempts:', result.debug.taskAttempts);

Dependency Deadlock

Problem: Circular dependencies preventing task completionSolutions:

Review task dependency graph
Identify circular references
Break circular dependencies
Update task dependencies

// Check for circular dependencies
const graph = await agentbase.getTaskDependencyGraph(projectId);
const cycles = detectCycles(graph);

if (cycles.length > 0) {
  console.log('Circular dependencies found:', cycles);
}

Task Overload

Problem: Too many tasks overwhelming assigneesSolutions:

Balance task distribution
Adjust priorities
Delegate or reassign tasks
Extend deadlines

// Rebalance tasks
const overloaded = await agentbase.getTaskStats({
  groupBy: "assignee"
});

for (const agent of overloaded) {
  if (agent.taskCount > threshold) {
    // Reassign low-priority tasks
  }
}

Advanced Patterns

Task Automation

Auto-complete simple tasks:

capabilities: {
  tasks: {
    enabled: true,
    autoComplete: {
      enabled: true,
      conditions: [
        { tag: "automated", confidence: 0.9 }
      ]
    }
  }
}

Task Templates with Variations

Create flexible templates:

const template = await agentbase.createTaskTemplate({
  name: "bug_fix",
  variations: {
    severity: {
      critical: {
        priority: "critical",
        dueInHours: 2
      },
      high: {
        priority: "high",
        dueInHours: 24
      },
      medium: {
        priority: "medium",
        dueInDays: 7
      }
    }
  }
});

Smart Task Routing

Route tasks based on content:

system: `Analyze new tasks and assign to:
- Backend team: API, database, server tasks
- Frontend team: UI, UX, client tasks
- DevOps team: Infrastructure, deployment tasks
- QA team: Testing, bug verification tasks

Consider current workload and expertise.`

Workflow

Orchestrate multi-step processes with tasks

Scheduling

Schedule recurring task creation

Memory

Remember task patterns and preferences

Multi-Agent

Distribute tasks across specialized agents

Additional Resources

API Reference

Complete tasks API documentation

Task Templates

Pre-built task templates library

Best Practices

Task management strategies

Pro Tip: Use task templates for recurring work patterns. This ensures consistency and saves time on task creation.

Getting Started

Build

Deploy

Improve

Agent Primitives

API Reference

Resources

​Overview

Task Creation

Status Tracking

Dependencies

Collaboration

​How Tasks Work

​Task States

​Lifecycle States

​Priority Levels

​Code Examples

​Basic Task Creation

​Create Task Manually

​Task with Dependencies

​Assign Task to Agent

​Query Tasks

​Update Task Status

​Recurring Tasks

​Task Templates

​Use Cases

​1. Project Management

​2. Content Creation Pipeline

​3. Customer Onboarding

​4. Incident Response

​5. Daily Standup Automation

​6. Sales Pipeline Tasks

​Best Practices

​Task Design

​Task Management

​Collaboration

​Integration with Other Primitives

​With Workflow

​With Memory

​With Scheduling

​Performance Considerations

​Task Volume

​Real-time Updates

​Troubleshooting

​Advanced Patterns

​Task Automation

​Task Templates with Variations

​Smart Task Routing

​Related Primitives

Workflow

Scheduling

Memory

Multi-Agent

​Additional Resources

API Reference

Task Templates

Best Practices

Overview

How Tasks Work

Task States

Lifecycle States

Priority Levels

Code Examples

Basic Task Creation

Create Task Manually

Task with Dependencies

Assign Task to Agent

Query Tasks

Update Task Status

Recurring Tasks

Task Templates

Use Cases

1. Project Management

2. Content Creation Pipeline

3. Customer Onboarding

4. Incident Response

5. Daily Standup Automation

6. Sales Pipeline Tasks

Best Practices

Task Design

Task Management

Collaboration

Integration with Other Primitives

With Workflow

With Memory

With Scheduling

Performance Considerations

Task Volume

Real-time Updates

Troubleshooting

Advanced Patterns

Task Automation

Task Templates with Variations

Smart Task Routing

Related Primitives

Additional Resources