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
Working together with the Pydantic team, we folded this library into the official pydantic-ai-harness — it now lives in
pydantic_ai_harness/planning(PR #404, merged), which supersedes this package.For new projects, use the harness — it is maintained by Pydantic alongside Pydantic AI itself. This repository stays on PyPI and keeps working for everyone already depending on it.
from pydantic_ai import Agent from pydantic_ai_harness.planning import Planning agent = Agent("openai:gpt-5.4", capabilities=[Planning(enable_subtasks=True)])Tools were renamed
Here In the harness write_todoswrite_planread_todosread_planadd_todoadd_taskupdate_todo_status/update_todo_statusesupdate_task_status/update_task_statusesremove_todoremove_taskadd_subtask,set_dependency,get_available_tasksunchanged API mapping
Here In pydantic_ai_harness.planningTodoCapabilityPlanningTodoStorage,AsyncMemoryStorageInMemoryPlanStoreAsyncPostgresStorage/create_storage("postgres", connection_string=…)PostgresPlanStore— takes a caller-owned asyncpg-compatible pool, so the harness pulls in no database drivercreate_todo_toolset()PlanningToolsetget_todo_system_prompt()not needed — Planningsurfaces the plan as an ephemeral tail reminder behind aCachePoint, so the cached prefix stays byte-identical across turnsTodo,TodoItemPlanItemTodoEvent,TodoEventType,TodoEventEmitterPlanEvent,PlanEventType,PlanEventEmitterThe harness also adds
SqlitePlanStoreandRedisPlanStore, and ablockedtask status, none of which exist here.
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.
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=Trueto embed the live task list instead) - Creates in-memory storage (or use your own)
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}")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.
model: openai:gpt-4.1
instructions: "You are a project planner."
capabilities:
- TodoCapability:
enable_subtasks: trueagent = Agent.from_file("agent.yaml")pip install pydantic-ai-todoOr with uv:
uv add pydantic-ai-todoIf 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.TodoCapabilityhandles this automatically.
| 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
from pydantic_ai_todo import TodoCapability, TodoStorage
storage = TodoStorage()
agent = Agent("openai:gpt-4.1", capabilities=[TodoCapability(storage=storage)])from pydantic_ai_todo import TodoCapability, AsyncMemoryStorage
storage = AsyncMemoryStorage()
agent = Agent("openai:gpt-4.1", capabilities=[TodoCapability(async_storage=storage)])Requires the
postgresextra: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)])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)])| Class | Description |
|---|---|
TodoCapability |
Pydantic AI capability — recommended way to add todo support |
| 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 |
| 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 |
| Class | Description |
|---|---|
TodoStorage |
Sync in-memory storage |
AsyncMemoryStorage |
Async in-memory with CRUD |
AsyncPostgresStorage |
PostgreSQL with multi-tenancy |
TodoEventEmitter |
Event emitter for callbacks |
| 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 |
git clone https://github.com/vstorm-co/pydantic-ai-todo.git
cd pydantic-ai-todo
make install
make test # 100% coverage requiredMIT — see LICENSE
