Pydantic AI pgtask
Durable execution for Pydantic AI agents, on Postgres alone.
Agents run for a while, a model call, a tool call, another model call. When the worker dies in the middle of that, the run is usually lost: you restart from zero and pay for every token again.
Pydantic AI pgtask fixes that. Call agent.run() inside a durable pgtask handler and every model and MCP call is checkpointed into Postgres. If the worker crashes, a new one resumes from the last completed step, no restart, no re-spent tokens. Same idea as Pydantic AI's Temporal integration, but with no Temporal, no Redis, no broker: just the Postgres you already have.
Installation
pip install pydantic-ai-pgtask
Example
import asyncio
import os
from typing import Any
from pgtask import Client, Task, TaskRegistry, Worker
from pydantic_ai import Agent
from pydantic_ai_pgtask import PGTaskDurability
tasks = TaskRegistry(queue_name="agents")
agent = Agent("openai:gpt-5.2", name="analyst", capabilities=[PGTaskDurability()])
@tasks.task("analyse")
async def analyse(task: Task, payload: dict[str, Any]) -> dict[str, Any]:
result = await agent.run(payload["prompt"])
return {"output": result.output}
async def main() -> None:
database_url = os.environ["PGTASK_DATABASE_URL"]
client = await Client.connect(database_url)
await client.migrate()
await client.enqueue(analyse.request({"prompt": "Analyse Q3 revenue"}))
await Worker(database_url, tasks).run()
if __name__ == "__main__":
asyncio.run(main())
You author a task, call the agent inside it, and run it durably. That's the whole idea.
How it works
PGTaskDurability is a Pydantic AI capability. When the agent runs inside any pgtask handler (discovered via pgtask's get_current_task()), it wraps:
- every model request in a
task.step(...)checkpoint, - every function tool call in its own checkpoint, so side effects run exactly once,
- every MCP
get_tools,get_instructions, andcall_toolin its own checkpoint.
Step names are built from the agent's name and each toolset's id, so every toolset that runs its own tools needs an id (including Capability(tools=...)); without one, building the agent raises, even if it never runs in a task. Step results are stored in Postgres as JSON. On a retry after a crash, pgtask replays completed steps from their cached results instead of re-executing them, so the run resumes exactly where it stopped.
Outside a durable task the capability is transparent: the agent behaves like a regular, non-durable agent.
!!! warning "Deterministic step order"
Repeated step names are disambiguated with an encounter-order occurrence counter, so tool calls run in 'sequential' mode by default. 'parallel' execution is excluded by type - a replay must reach checkpoints in the same order they were recorded.
Metadata
Release files for pydantic-ai-pgtask 0.0.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pydantic_ai_pgtask-0.0.3.tar.gz | 7.2 kB | Without provenance | Details for pydantic_ai_pgtask-0.0.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pydantic_ai_pgtask-0.0.3-py3-none-any.whl | Python 3 | none | any | Details for pydantic_ai_pgtask-0.0.3-py3-none-any.whl |
Total release size: 15.6 kB
Release files / pydantic_ai_pgtask-0.0.3.tar.gz
| Download URL | pydantic_ai_pgtask-0.0.3.tar.gz |
|---|---|
| Size | 7.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
43f40597e14f3f5318df9567b97403eb8045bc6965562e2c6e7d772963030c1e
|
|
BLAKE2b-256 checksum How to use checksums |
eb978f9debf6bf1e1a1f7b565d96e6d640102a2fec3d1b2f90ade023b68dd5e1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.9.12 {"installer":{"name":"uv","version":"0.9.12"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / pydantic_ai_pgtask-0.0.3-py3-none-any.whl
| Download URL | pydantic_ai_pgtask-0.0.3-py3-none-any.whl |
|---|---|
| Size | 8.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
178d4007860527165a0e9a0bd040b8de36b7adbeb34a1b9492cfeca205b3d8b6
|
|
BLAKE2b-256 checksum How to use checksums |
91b0f34900739da82d964a6f85342e099088eac2ba0e827dd3092e62585a77d0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.9.12 {"installer":{"name":"uv","version":"0.9.12"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for pydantic-ai-pgtask 0.0.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.