pydantic AI todo

0.2.1 verified Mon Apr 27 auth: no python

Todo/task planning toolset for pydantic-ai agents. Provides a FunctionToolset and a TodoCapability (agent capability) for todo list management including create, read, update, delete, subtasks, and dependency tracking. Supports both sync and async storage backends. Current version 0.2.1, requires Python >=3.10, active development with frequent releases.

pip install pydantic-ai-todo

Common errors

error ImportError: cannot import name 'create_todo_toolset' from 'pydantic_ai_todo' ↓

cause Package version too old (pre-0.1.0) or misspelled function name.

fix

Upgrade: pip install --upgrade pydantic-ai-todo

error AttributeError: 'Agent' object has no attribute 'capabilities' ↓

cause Using an older version of pydantic-ai that doesn't support capabilities (requires pydantic-ai >=0.0.18).

fix

Upgrade pydantic-ai-slim: pip install "pydantic-ai-slim>=1.74.0"

error TypeError: TodoCapability.__init__() missing 1 required positional argument: 'storage' ↓

cause Storage parameter is mandatory; omitted when instantiating TodoCapability.

fix

Provide a storage instance: TodoCapability(storage=MemoryStorage())

Warnings

breaking In v0.2.0, the recommended API changed from create_todo_toolset to TodoCapability. The toolset approach still works but may not receive future updates. ↓

fix Migrate to TodoCapability: replace create_todo_toolset(storage) with TodoCapability(storage) and pass agent via capabilities=[...].

breaking v0.2.1 requires pydantic-ai-slim >=1.74.0 for async get_instructions. Older versions will fail to load the toolset if installed with a lower version. ↓

fix Upgrade pydantic-ai-slim to >=1.74.0: pip install "pydantic-ai-slim>=1.74.0"

deprecated The CLI (command-line entry point) was removed in v0.1.6. The package is library-only. ↓

fix Use the Python API directly; no CLI available.

gotcha Todo IDs are auto-generated 8-char hex strings. When using update_todo_status or remove_todo, you must provide the exact ID. The system prompt includes ID in format [abc123ef] since v0.1.8. ↓

fix Ensure agent can see todo IDs in system prompt. If using custom prompts, include IDs explicitly.

Imports

TodoCapability

wrong

from pydantic_ai_todo.capabilities import TodoCapability

correct

from pydantic_ai_todo import TodoCapability

TodoCapability is top-level exported since v0.2.0

create_todo_toolset

wrong

from pydantic_ai_todo.toolset import create_todo_toolset

correct

from pydantic_ai_todo import create_todo_toolset

Direct top-level export since v0.1.0

MemoryStorage
```
from pydantic_ai_todo import MemoryStorage
```
Top-level export for sync in-memory storage
AsyncMemoryStorage
```
from pydantic_ai_todo import AsyncMemoryStorage
```
Top-level export for async in-memory storage
TodoStorageProtocol
```
from pydantic_ai_todo import TodoStorageProtocol
```
Sync storage protocol, top-level export

Quickstart

Create an agent with todo capability using in-memory storage. Requires OPENAI_API_KEY in environment.

import os
from pydantic_ai import Agent
from pydantic_ai_todo import TodoCapability, MemoryStorage

storage = MemoryStorage()
agent = Agent("openai:gpt-4o", capabilities=[TodoCapability(storage=storage)])
result = agent.run_sync("Add a task to buy milk")
print(result.data)