Todo Toolset for Pydantic AI

Task Planning and Tracking for AI Agents

Capabilities API — plug-and-play with one line  •  Subtasks & Dependencies — hierarchical task management  •  PostgreSQL Storage — persistent multi-tenant tasks  •  Event System — webhooks and callbacks

Todo Toolset for Pydantic AI adds task planning capabilities to any Pydantic AI agent. Your agent can create, track, and complete tasks with full support for subtasks, dependencies, and persistent storage.

Full framework? Check out Pydantic Deep Agents — complete agent framework with planning, filesystem, subagents, and skills.

Quick Start

The recommended way to add todo support is via the Capabilities API — one import, one line:

from pydantic_ai import Agent
from pydantic_ai_todo import TodoCapability

agent = Agent("openai:gpt-4.1", capabilities=[TodoCapability()])
result = await agent.run("Create a todo list for building a REST API")

TodoCapability automatically:

• Registers all todo tools (add_todo, read_todos, write_todos, update_todo_status, remove_todo)
• Injects a system prompt section describing the todo workflow (static by default, so todo updates never invalidate the provider's prompt cache; pass include_current_todos=True to embed the live task list instead)
• Creates in-memory storage (or use your own)

With Storage Access

from pydantic_ai_todo import TodoCapability, TodoStorage

storage = TodoStorage()
agent = Agent("openai:gpt-4.1", capabilities=[TodoCapability(storage=storage)])

result = await agent.run("Plan a blog application")

# Access todos directly
for todo in storage.todos:
    print(f"[{todo.status}] {todo.content}")

With Subtasks and Dependencies

agent = Agent(
    "openai:gpt-4.1",
    capabilities=[TodoCapability(enable_subtasks=True)],
)

Enables add_subtask, set_dependency, and get_available_tasks tools with automatic cycle detection.

YAML Agent Definition

model: openai:gpt-4.1
instructions: "You are a project planner."
capabilities:
  - TodoCapability:
      enable_subtasks: true

agent = Agent.from_file("agent.yaml")

Installation

pip install pydantic-ai-todo

Or with uv:

uv add pydantic-ai-todo

Alternative: Toolset API

If you prefer the lower-level toolset approach (without capabilities):

from pydantic_ai import Agent
from pydantic_ai_todo import create_todo_toolset, get_todo_system_prompt, TodoStorage

storage = TodoStorage()
toolset = create_todo_toolset(storage=storage)

agent = Agent(
    "openai:gpt-4.1",
    toolsets=[toolset],
    system_prompt=get_todo_system_prompt(storage),
)

Note: With the toolset API, you need to wire get_todo_system_prompt() manually. TodoCapability handles this automatically.

Available Tools

*Available when enable_subtasks=True

Storage Backends

In-Memory (Default)

from pydantic_ai_todo import TodoCapability, TodoStorage

storage = TodoStorage()
agent = Agent("openai:gpt-4.1", capabilities=[TodoCapability(storage=storage)])

Async Memory

from pydantic_ai_todo import TodoCapability, AsyncMemoryStorage

storage = AsyncMemoryStorage()
agent = Agent("openai:gpt-4.1", capabilities=[TodoCapability(async_storage=storage)])

PostgreSQL

Requires the postgres extra: pip install 'pydantic-ai-todo[postgres]'

from pydantic_ai_todo import TodoCapability, create_storage

storage = create_storage(
    "postgres",
    connection_string="postgresql://user:pass@localhost/db",
    session_id="user-123",  # Multi-tenancy
)
await storage.initialize()

agent = Agent("openai:gpt-4.1", capabilities=[TodoCapability(async_storage=storage)])

Event System

React to task changes:

from pydantic_ai_todo import TodoCapability, TodoEventEmitter, AsyncMemoryStorage

emitter = TodoEventEmitter()

@emitter.on_completed
async def notify_completed(event):
    print(f"Task done: {event.todo.content}")

@emitter.on_created
async def notify_created(event):
    print(f"New task: {event.todo.content}")

storage = AsyncMemoryStorage(event_emitter=emitter)
agent = Agent("openai:gpt-4.1", capabilities=[TodoCapability(async_storage=storage)])

API Reference

Capability

Factory Functions

Models

Storage Classes

Related Projects

Contributing

git clone https://github.com/vstorm-co/pydantic-ai-todo.git
cd pydantic-ai-todo
make install
make test  # 100% coverage required

License

MIT — see LICENSE

Need help implementing this in your company?

We're Vstorm — an Applied Agentic AI Engineering Consultancy
with 30+ production AI agent implementations.

Made with ❤️ by Vstorm