Todo Toolset for Pydantic AI

Task Planning and Tracking for AI Agents

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.

Use Cases

What You Want to Build	How Todo Toolset Helps
AI Coding Assistant	Break down complex features into trackable tasks
Project Manager Bot	Create hierarchical task structures with dependencies
Research Agent	Track investigation progress across multiple topics
Workflow Automation	React to task completion with webhooks and callbacks
Multi-User App	Session-based PostgreSQL storage for each user

Installation

pip install pydantic-ai-todo

Or with uv:

uv add pydantic-ai-todo

Quick Start

from pydantic_ai import Agent
from pydantic_ai_todo import create_todo_toolset

agent = Agent(
    "openai:gpt-4o",
    toolsets=[create_todo_toolset()],
)

result = await agent.run("Create a todo list for building a REST API")

That's it. Your agent can now:

• ✅ Create tasks — add_todo, write_todos
• ✅ Track progress — read_todos, update_todo_status
• ✅ Manage hierarchy — subtasks and dependencies
• ✅ Persist state — PostgreSQL multi-tenant storage

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 create_todo_toolset, TodoStorage

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

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

Async Memory

from pydantic_ai_todo import create_todo_toolset, AsyncMemoryStorage

storage = AsyncMemoryStorage()
toolset = create_todo_toolset(async_storage=storage)

# Async access
todos = await storage.get_todos()

PostgreSQL

from pydantic_ai_todo import create_storage, create_todo_toolset

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

toolset = create_todo_toolset(async_storage=storage)

Task Hierarchy

Enable subtasks for complex task management:

toolset = create_todo_toolset(
    async_storage=storage,
    enable_subtasks=True,
)

# Agent can now:
# - add_subtask(parent_id, content) — create child tasks
# - set_dependency(task_id, depends_on_id) — link tasks
# - get_available_tasks() — list tasks ready to work on

Dependencies include automatic cycle detection — no infinite loops possible.

Event System

React to task changes:

from pydantic_ai_todo import TodoEventEmitter, AsyncMemoryStorage

emitter = TodoEventEmitter()

@emitter.on_completed
async def notify_completed(event):
    print(f"Task done: {event.todo.content}")
    # Send webhook, update UI, etc.

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

storage = AsyncMemoryStorage(event_emitter=emitter)
toolset = create_todo_toolset(async_storage=storage)

Custom Tool Descriptions

Override default tool descriptions for better LLM behavior in your use case:

toolset = create_todo_toolset(
    descriptions={
        "write_todos": "Plan and organize complex multi-step tasks only",
        "read_todos": "Check current task list and progress",
    }
)

Pass a descriptions dict mapping tool names to custom description strings. Any tool not listed keeps its default description. Available tool names: read_todos, write_todos, add_todo, update_todo_status, remove_todo, add_subtask, set_dependency, get_available_tasks.

API Reference

Factory Functions

Function	Description
create_todo_toolset()	Create toolset with todo tools
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