---
id: pydantic-ai-todo
version: "0.2.7"
license: MIT License Copyright (c) 2025 Vstorm Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the… (full text in the JSON record)
license_treatment: permissive
maintenance: active
---

# pydantic-ai-todo — Todo/task planning toolset for pydantic-ai agents

License: permissive · Maintenance: active · Downloads: 317.6K/mo

## What it is and what it does

pydantic-ai-todo is a task management library that plugs into Pydantic AI agents via a single-line Capabilities API. It gives agents the ability to create, read, update, and delete tasks—with optional support for subtasks, task dependencies, and automatic cycle detection. Tasks can be stored in memory (default), async memory, or PostgreSQL with multi-tenant isolation.

The package provides both a high-level Capabilities API (recommended) and a lower-level Toolset API for integration flexibility. It includes an event system for reacting to task state changes via webhooks and callbacks. Storage backends are pluggable, and the system prompt can be static (for LLM prompt caching) or dynamic (embedding live task lists). Runtime dependencies are pydantic-ai-slim, pydantic, and redis.

Use it for:

- Enable an AI agent to plan and track subtasks for a complex project, with automatic dependency resolution and cycle detection.
- Build a multi-tenant task management system where different users' agents maintain isolated task lists in PostgreSQL.
- Integrate task completion events with external webhooks to trigger notifications or downstream workflows when agent-created tasks change state.
- Use in-memory task storage for lightweight agent-driven planning in development or single-session scenarios without database setup.
- Combine with Pydantic AI's YAML agent definitions to declaratively enable task planning in agent configurations.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Adds task planning and tracking tools to Pydantic AI agents, enabling them to create, manage, and complete hierarchical tasks with subtasks, dependencies, and persistent storage.

Yes, with conditions. Install if you are building Pydantic AI agents that need task planning, hierarchical task management, or persistent multi-tenant task storage. The low install friction, active maintenance, permissive MIT license, and zero known vulnerabilities make it safe to adopt. Beta status is appropriate for a specialized toolset; verify PostgreSQL backend requirements and compatibility with your Pydantic AI version before production use.

## Install

pip install pydantic-ai-todo
uv add pydantic-ai-todo
poetry add pydantic-ai-todo

## Installing pydantic-ai-todo

Before you install: Low friction install with three runtime dependencies. Package is actively maintained with recent releases; last commit 2026-08-14. Beta status (Development Status :: 4) is appropriate for a specialized toolset in active development.

License in practice: MIT license permits unrestricted use, modification, and distribution with minimal restrictions—suitable for commercial and open-source projects alike.

Quickstart:

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")

Requires Python 3.10 or later; Pydantic AI agent framework must be installed and configured with a valid model provider (e.g., OpenAI API key for gpt-4.1).

Verify before relying:

- Whether PostgreSQL backend requires additional system dependencies beyond the 'postgres' extra
- Performance characteristics and scalability limits for in-memory vs. async storage backends
- Compatibility guarantees with specific Pydantic AI versions or provider APIs

## Package facts

- License: MIT License Copyright (c) 2025 Vstorm Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the… (full text in the JSON record) (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 317.6K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

pydantic ai task planning, ai agent todo management, hierarchical task tracking, agent task dependencies, pydantic ai capabilities, ai task workflow, agent planning toolset, pydantic-ai-integration, task-planning, agent-tools

[View on SkillFed](https://skillfed.io/packages/pydantic-ai-todo) · [View on PyPI](https://pypi.org/project/pydantic-ai-todo/)