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

Tool	Description
read_todos	List all tasks (supports hierarchical view)
write_todos	Bulk write/update tasks
add_todo	Add a single task
update_todo_status	Update task status by ID
remove_todo	Delete task by ID
add_subtask*	Create child task
set_dependency*	Link tasks with dependency
get_available_tasks*	List tasks ready to work on

*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

Class	Description
TodoCapability	Pydantic AI capability — recommended way to add todo support

Factory Functions

Function	Description
create_todo_toolset()	Create standalone toolset (lower-level API)
create_storage(backend, **options)	Factory for storage backends
get_todo_system_prompt()	Generate system prompt with current todos

Models

Model	Description
Todo	Task with id, content, status, parent_id, depends_on
TodoItem	Input model for write_todos
TodoEvent	Event data with type, todo, timestamp
TodoEventType	CREATED, UPDATED, STATUS_CHANGED, DELETED, COMPLETED

Storage Classes

Class	Description
TodoStorage	Sync in-memory storage
AsyncMemoryStorage	Async in-memory with CRUD
AsyncPostgresStorage	PostgreSQL with multi-tenancy
TodoEventEmitter	Event emitter for callbacks

Related Projects

Package	Description
Pydantic Deep Agents	Full agent framework (uses this library)
pydantic-ai-backend	File storage and Docker sandbox
subagents-pydantic-ai	Multi-agent orchestration
summarization-pydantic-ai	Context management
pydantic-ai	The foundation — agent framework by Pydantic

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