agent-framework-persql 0.1.0

Microsoft Agent Framework conversation history backed by PerSQL — durable message history in an isolated SQLite database per agent.

agent-framework-persql

Microsoft Agent Framework conversation history backed by PerSQL — durable message history in an isolated SQLite database per agent, provisioned instantly.

pip install agent-framework-persql

Usage

import os
from persql import PerSQL
from agent_framework_persql import PerSQLHistoryProvider

client = PerSQL(token=os.environ["PERSQL_TOKEN"])
provider = PerSQLHistoryProvider(client.database("acme/agent-state"))

agent = chat_client.as_agent(instructions="...", context_providers=[provider])
session = agent.create_session(session_id="user-42")
await agent.run("hi", session=session)

Or let the provider own the client:

with PerSQLHistoryProvider.from_token(os.environ["PERSQL_TOKEN"], "acme/agent-state") as provider:
    ...

AsyncPerSQL databases are awaited natively; sync databases run via asyncio.to_thread.

What it stores

One agent_framework_messages row per message (Message.to_dict() as JSON), appended in run order and replayed with Message.from_dict(). Pass messages_table= to rename the table. The standard HistoryProvider flags (load_messages, store_inputs, store_outputs, store_context_messages, store_context_from) and skip_excluded work as in the built-in providers, so the same class covers primary memory, audit-only, and evaluation storage.

provider.clear(session_id) deletes one session's history.

Limits

• A None session_id maps to one shared "default" history — the same behavior as the framework's FileHistoryProvider. Pass session ids for per-user isolation.
• Message payloads are JSON; binary content should be referenced by URI, not embedded.
• Requires agent-framework-core >= 1.8, < 2 — the package subclasses HistoryProvider, so a framework major version can change the contract.

Local mode for tests

from persql import PerSQL
provider = PerSQLHistoryProvider(PerSQL(local=":memory:").database("test/db"))

Runs against in-process SQLite — no network, no token.