Conversations for Pydantic AI App Factory

pydantic-ai-conversations adds persistent, multi-turn conversations to an app built with pydantic-ai-app-factory. Messages are stored through pydantic-ai-harness's Step Persistence, the harness's durable record of an agent run. This package adds what a chat product needs on top: a registry that lists, titles, deletes, and isolates conversations per tenant; a capability that loads the stored conversation into each run and records each turn, so retries, edits, and tool approvals are ordinary turns; and the /conversations routes a frontend reads.

Quick Start

Install the package and the FastAPI CLI:

pip install pydantic-ai-conversations "fastapi[standard]"

Create main.py. The agent uses pydantic-ai's test model and the auth function is a stub, so the app runs without a model key:

from pydantic_ai_app_factory import UserContext, create_agent, create_agent_app
from pydantic_ai_conversations import ConversationsFeature
from pydantic_ai_conversations.sqlite import SqliteConversationRegistry, SqliteConversationStepStore


def auth() -> UserContext:
    return UserContext(user_id='alice', tenant_id='t1')


conversations = ConversationsFeature(
    registry=SqliteConversationRegistry('app.db'),
    step_store=SqliteConversationStepStore('app.db'),
)
agent = create_agent('test', instructions='You are a support assistant.')
app = create_agent_app(agent, auth=auth, features=[conversations])

Run it with fastapi dev. A conversation starts with the first request that names a conversation_id; the id is yours to choose. Every later request names the turn (one agent run) it builds on, through the previous_run_id the previous answer returned:

curl -s http://127.0.0.1:8000/run \
  -H 'Content-Type: application/json' \
  -d '{"prompt": "My printer is offline.", "conversation_id": "c1"}' | jq -r .run_id

curl -s http://127.0.0.1:8000/run \
  -H 'Content-Type: application/json' \
  -d '{"prompt": "It is a Brother.", "conversation_id": "c1", "extras": {"previous_run_id": "<the run_id printed above>"}}'

GET /conversations lists the caller's conversations and GET /conversations/c1 returns the transcript. Over /chat, the streaming endpoint for Vercel AI SDK frontends, the chat id is the conversation, previousRunId names the previous turn, and the streamed message's id is the run id to send back.

What stays with the app

Who the caller is, and whether they may act in a tenant or case, is the app's AuthProvider. Sanitising the messages a client sends is the endpoint's job; the app factory does it. Message durability is the harness's. This package enforces one thing: a conversation is reachable only inside the partition its caller's identity maps to.

Documentation

The quick start uses a test model, a stub auth function, and SQLite. The documentation covers the rest.

1. Getting started: install, wire, first conversation over /run and /chat.
   1. Example app
2. How a conversation is stored: the terms, and what the harness, this package, and the app each own.
3. Continuing a conversation: previous_run_id, retries, edits, approvals, history limits.
4. Scope and access: tenants, users, shared cases, and where the access wall ends.
   1. Example: conversations shared per case
5. The /conversations routes: listing, transcript, and what a frontend renders.
   1. Example: attrs set by the server
6. Deleting conversations: soft delete, purge, cleanup hooks, what remains.
7. Backends: SQLite, MongoDB, PostgreSQL, schema and upgrades.
8. Extending: your own registry or store, transforms, use without the app factory.
9. Operations: readiness, concurrency, logging, limits, version pins.
10. Testing: testing an app with conversations; the registry conformance suite.
11. Reference: signatures, wire shapes, error codes.

Compatibility

Python 3.11 or later. The package depends on a narrow range of pydantic-ai-app-factory and pydantic-ai-harness versions, and the harness range fixes the pydantic-ai version with it; Operations says why, and pyproject.toml has the current ranges.

Contributing

Apache-2.0. Set up with make install, run make all before a pull request, and see AGENTS.md for the module layout and boundaries.

License

Apache-2.0