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.

TypeScript

import { Agent } from '@autohandai/agent-sdk';

const agent = new Agent({
  name: "Task Agent",
  instructions: "Break down complex tasks and track progress.",
  options: {
    todoLists: {
      enabled: true,
      autoCreate: true,
    },
  },
});

Python

from autohand_agents import Agent, AgentOptions, TodoListConfig

options = AgentOptions(
    todo_lists=TodoListConfig(
        enabled=True,
        auto_create=True,
    ),
)

agent = Agent(
    name="Task Agent",
    instructions="Break down complex tasks and track progress.",
    options=options,
)

Java

import com.autohand.Agent;
import com.autohand.TodoListConfig;

TodoListConfig todoListConfig = new TodoListConfig.Builder()
    .enabled(true)
    .autoCreate(true)
    .build();

Agent agent = new Agent.Builder()
    .name("Task Agent")
    .instructions("Break down complex tasks and track progress")
    .todoLists(todoListConfig)
    .build();

Go

todoListConfig := &agentsdk.TodoListConfig{
    Enabled: true,
    AutoCreate: true,
}

agent := agentsdk.NewAgent("Task Agent", "Break down complex tasks and track progress")
agent.TodoLists = todoListConfig

Swift

let todoListConfig = TodoListConfig(
    enabled: true,
    autoCreate: true
)

let agent = Agent(
    name: "Task Agent",
    instructions: "Break down complex tasks and track progress"
)
agent.todoLists = todoListConfig

Rust

use autohand_agents::{Agent, TodoListConfig};

let todo_list_config = TodoListConfig {
    enabled: true,
    auto_create: true,
};

let mut agent = Agent::new("Task Agent", "Break down complex tasks and track progress");
agent.todo_lists = Some(todo_list_config);

Managing Todo Lists

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

TypeScript

const result = await Runner.run(agent, "Refactor the authentication module");

// Access the todo list
const todoList = result.todoList;
console.log("Todo items:", todoList.items);

// Check completion status
console.log("Completed:", todoList.completedCount);
console.log("Remaining:", todoList.remainingCount);
console.log("Progress:", todoList.progress);

Python

result = Runner.run_sync(agent, "Refactor the authentication module")

# Access the todo list
todo_list = result.todo_list
print("Todo items:", todo_list.items)

# Check completion status
print("Completed:", todo_list.completed_count)
print("Remaining:", todo_list.remaining_count)
print("Progress:", todo_list.progress)

Java

RunResult result = Runner.runSync(agent, "Refactor the authentication module");

// Access the todo list
TodoList todoList = result.getTodoList();
System.out.println("Todo items: " + todoList.getItems());

// Check completion status
System.out.println("Completed: " + todoList.getCompletedCount());
System.out.println("Remaining: " + todoList.getRemainingCount());
System.out.println("Progress: " + todoList.getProgress());

Go

result := agentsdk.RunnerRunSync(agent, "Refactor the authentication module")

// Access the todo list
todoList := result.TodoList
fmt.Println("Todo items:", todoList.Items)

// Check completion status
fmt.Println("Completed:", todoList.CompletedCount)
fmt.Println("Remaining:", todoList.RemainingCount)
fmt.Println("Progress:", todoList.Progress)

Swift

let result = try await Runner.run(agent, prompt: "Refactor the authentication module")

// Access the todo list
let todoList = result.todoList
print("Todo items: (todoList.items)")

// Check completion status
print("Completed: (todoList.completedCount)")
print("Remaining: (todoList.remainingCount)")
print("Progress: (todoList.progress)")

Rust

let result = Runner::run_sync(&agent, "Refactor the authentication module")?;

// Access the todo list
let todo_list = &result.todo_list;
println!("Todo items: {:?}", todo_list.items);

// Check completion status
println!("Completed: {}", todo_list.completed_count);
println!("Remaining: {}", todo_list.remaining_count);
println!("Progress: {}", todo_list.progress);

Manual Todo Management

Create and manage todo lists manually for custom workflows.

TypeScript

import { TodoList, TodoItem } from '@autohandai/agent-sdk';

// Create a todo list
const todoList = new TodoList("Refactoring Task");

// Add items
todoList.addItem(new TodoItem("Analyze current implementation"));
todoList.addItem(new TodoItem("Identify refactoring opportunities"));
todoList.addItem(new TodoItem("Implement changes"));
todoList.addItem(new TodoItem("Run tests"));
todoList.addItem(new TodoItem("Update documentation"));

// Mark items as complete
todoList.completeItem("Analyze current implementation");
todoList.completeItem("Identify refactoring opportunities");

// Get status
console.log("Progress:", todoList.progress); // 0.4 (2/5)

Python

from autohand_agents import TodoList, TodoItem

# Create a todo list
todo_list = TodoList("Refactoring Task")

# Add items
todo_list.add_item(TodoItem("Analyze current implementation"))
todo_list.add_item(TodoItem("Identify refactoring opportunities"))
todo_list.add_item(TodoItem("Implement changes"))
todo_list.add_item(TodoItem("Run tests"))
todo_list.add_item(TodoItem("Update documentation"))

# Mark items as complete
todo_list.complete_item("Analyze current implementation")
todo_list.complete_item("Identify refactoring opportunities")

# Get status
print("Progress:", todo_list.progress)  # 0.4 (2/5)

Java

import com.autohand.TodoList;
import com.autohand.TodoItem;

// Create a todo list
TodoList todoList = new TodoList("Refactoring Task");

// Add items
todoList.addItem(new TodoItem("Analyze current implementation"));
todoList.addItem(new TodoItem("Identify refactoring opportunities"));
todoList.addItem(new TodoItem("Implement changes"));
todoList.addItem(new TodoItem("Run tests"));
todoList.addItem(new TodoItem("Update documentation"));

// Mark items as complete
todoList.completeItem("Analyze current implementation");
todoList.completeItem("Identify refactoring opportunities");

// Get status
System.out.println("Progress: " + todoList.getProgress()); // 0.4 (2/5)

Go

// Create a todo list
todoList := agentsdk.NewTodoList("Refactoring Task")

// Add items
todoList.AddItem(agentsdk.NewTodoItem("Analyze current implementation"))
todoList.AddItem(agentsdk.NewTodoItem("Identify refactoring opportunities"))
todoList.AddItem(agentsdk.NewTodoItem("Implement changes"))
todoList.AddItem(agentsdk.NewTodoItem("Run tests"))
todoList.AddItem(agentsdk.NewTodoItem("Update documentation"))

// Mark items as complete
todoList.CompleteItem("Analyze current implementation")
todoList.CompleteItem("Identify refactoring opportunities")

// Get status
fmt.Println("Progress:", todoList.Progress) // 0.4 (2/5)

Swift

// Create a todo list
var todoList = TodoList(title: "Refactoring Task")

// Add items
todoList.addItem(TodoItem(title: "Analyze current implementation"))
todoList.addItem(TodoItem(title: "Identify refactoring opportunities"))
todoList.addItem(TodoItem(title: "Implement changes"))
todoList.addItem(TodoItem(title: "Run tests"))
todoList.addItem(TodoItem(title: "Update documentation"))

// Mark items as complete
todoList.completeItem(title: "Analyze current implementation")
todoList.completeItem(title: "Identify refactoring opportunities")

// Get status
print("Progress: (todoList.progress)") // 0.4 (2/5)

Rust

use autohand_agents::{TodoList, TodoItem};

// Create a todo list
let mut todo_list = TodoList::new("Refactoring Task");

// Add items
todo_list.add_item(TodoItem::new("Analyze current implementation"));
todo_list.add_item(TodoItem::new("Identify refactoring opportunities"));
todo_list.add_item(TodoItem::new("Implement changes"));
todo_list.add_item(TodoItem::new("Run tests"));
todo_list.add_item(TodoItem::new("Update documentation"));

// Mark items as complete
todo_list.complete_item("Analyze current implementation");
todo_list.complete_item("Identify refactoring opportunities");

// Get status
println!("Progress: {}", todo_list.progress()); // 0.4 (2/5)

Streaming Todo Updates

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

TypeScript

for await (const chunk of Runner.runStream(agent, "Refactor the module")) {
  if (chunk.type === "todo_update") {
    console.log("Todo update:", chunk.item);
    console.log("Progress:", chunk.progress);
  }
}

Python

async for chunk in Runner.run_stream(agent, "Refactor the module"):
    if chunk.type == "todo_update":
        print("Todo update:", chunk.item)
        print("Progress:", chunk.progress)

Java

Runner.runStream(agent, "Refactor the module")
    .forEach(chunk -> {
        if (chunk.getType() == StreamChunk.Type.TODO_UPDATE) {
            System.out.println("Todo update: " + chunk.getItem());
            System.out.println("Progress: " + chunk.getProgress());
        }
    });

Go

agentsdk.RunnerRunStream(agent, "Refactor the module",
    func(chunk string) {
        if strings.HasPrefix(chunk, "todo_update:") {
            fmt.Println("Todo update:", chunk)
            fmt.Println("Progress:", chunk)
        }
    },
)

Swift

for try await chunk in Runner.runStream(agent, prompt: "Refactor the module") {
    if chunk.type == .todoUpdate {
        print("Todo update: (chunk.item)")
        print("Progress: (chunk.progress)")
    }
}

Rust

Runner::run_stream(&agent, "Refactor the module")
    .await?
    .for_each(|chunk| async {
        if chunk.starts_with("todo_update:") {
            println!("Todo update: {}", chunk);
            println!("Progress: {}", chunk);
        }
    })
    .await;

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