Todo Lists

Todo Lists let agents track their progress through multi-step tasks. Agents can add, complete, and manage todo items, giving you visibility into what they're working on and what remains to be done.

What are Todo Lists?

Todo Lists are a structured way for agents to plan and track their work. Instead of executing tasks blindly, agents can create a todo list, check off items as they complete them, and provide visibility into their progress.

Note: Todo Lists are automatically managed by the agent loop when enabled. You can also manually create and manage todo lists for custom workflows.

Enabling Todo Lists

Configure agents to use Todo Lists for task tracking.

Managing Todo Lists

Access and manipulate todo lists through the result object or session.

Manual Todo Management

Create and manage todo lists manually for custom workflows.

Streaming Todo Updates

Monitor todo list changes in real-time during agent execution.

Use Cases

  • Progress tracking: Monitor agent progress on long-running tasks
  • Task breakdown: Agents can plan complex work by creating a todo list first
  • Resume capability: Save todo lists to resume interrupted tasks
  • UI integration: Display progress bars and task lists in web UIs
  • Debugging: Understand what an agent is working on when it gets stuck
  • Reporting: Generate reports of completed vs. remaining tasks

Best Practices

  • Enable for complex tasks: Use todo lists for multi-step operations
  • Monitor progress: Use streaming to get real-time progress updates
  • Save todo lists: Persist todo lists for long-running tasks to enable resumption
  • Review completed items: Check what the agent completed to verify correctness
  • Adjust granularity: Balance between too many and too few todo items
  • Handle failures gracefully: Check which items remain when a task fails