agent-webkit-server API

pip install "agent-webkit-server[fastapi]"
# Postgres adapter:
pip install "agent-webkit-server[fastapi,postgres]"

`create_app(...)` — FastAPI adapter

from agent_webkit_server.adapters.fastapi import create_app
from agent_webkit_server.auth import AuthConfig

app = create_app(auth=AuthConfig.from_env())

Signature:

def create_app(
    *,
    auth: AuthConfig | None = None,
    sdk_factory: SDKFactory | None = None,
    session_store: SessionStore | None = None,
) -> FastAPI: ...

Param	Notes
`auth`	Auth policy. Defaults to `AuthConfig.from_env()` (reads `AGENT_WEBKIT_AUTH_TOKEN`).
`sdk_factory`	Override how `ClaudeSDKClient` is constructed. Useful for tests and for injecting custom SDK options. When set, `session_store` is ignored — wire it into your own factory.
`session_store`	Forwarded to `ClaudeAgentOptions(session_store=...)` by the default factory. Pair with the bundled `PgSessionStore` for failover.

`AuthConfig`

from agent_webkit_server.auth import AuthConfig

AuthConfig(token="hunter2")          # require this Bearer token
AuthConfig(disabled=True)            # no auth (dev only)
AuthConfig.from_env()                # read AGENT_WEBKIT_AUTH_TOKEN / AGENT_WEBKIT_NO_AUTH

Attribute	Type
`token`	`Optional[str]`
`disabled`	`bool`

`SessionRegistry`

The in-memory registry of live sessions. You typically never touch this — create_app constructs and owns one. Reach for it if you're writing a custom adapter.

from agent_webkit_server.session import SessionRegistry

registry = SessionRegistry(sdk_factory, idle_timeout_s=300.0)
registry.start_reaper()

session = registry.create(SessionConfig(...))
registry.get(session_id)
registry.remove(session_id)
await registry.shutdown()

Param	Default	Notes
`sdk_factory`	—	Required. Async callable that builds and returns a `ClaudeSDKClient`.
`idle_timeout_s`	`300.0`	Seconds since last input and last subscriber before eviction.

`EventLog` — the ring buffer

from agent_webkit_server.event_log import EventLog, EvictedError

log = EventLog(max_size=1000)

Method / property	Notes
`append(event, data)`	Append a new event. Returns the assigned `LoggedEvent`.
`subscribe(after_seq=0)`	Async iterator. Replays buffered events `> after_seq`, then live tails.
`last_seq`	Highest seq assigned so far.
`close()`	Closes all subscribers with a terminal `done` event.
`EvictedError`	Raised by `subscribe` when `after_seq` is older than the ring window.

max_size is the most important production knob: bigger = longer disconnects survive resume, but more memory per session.

Postgres adapter

from agent_webkit_server.adapters.pg_session_store import PgSessionStore

store = await PgSessionStore.connect("postgresql://...", min_size=1, max_size=10)
# or, with an existing pool:
store = PgSessionStore.from_pool(my_pool)

Class method	Notes
`connect(dsn, *, min_size, max_size)`	Open a new asyncpg pool.
`from_pool(pool)`	Reuse an existing `asyncpg.Pool`.

Implements the SessionStore protocol: append, load, close. See the Postgres sessions guide.

Constants

from agent_webkit_server import PROTOCOL_VERSION  # "1.0"

Request and response bodies live in agent_webkit_server.models and are Pydantic models. The shapes match the wire protocol. You can import them in tests or to build a non-FastAPI adapter — see Custom adapter guide.