paddock-sdk, imported as paddock. It needs Python 3.10 or later, and depends on httpx and pydantic 2. It is fully typed.
Install
paddock-sdk is not on PyPI yet. Until it is published, install it from the sdk/python directory of the paddock repository.Create a client
Paddock is a context manager, and AsyncPaddock an async one, that closes its HTTP client on exit, unless you passed one in.
asyncio
AsyncPaddock has the same methods as coroutines. Awaiting a list gives its first page, which async-iterates every item; a stream is an async context manager and an async iterator.
Conventions
- Arguments are keyword-only:
agent.sessions.create(cwd="repos/web"). - Fields are snake_case (
processed_seq,turn_id); metadata keys are your own strings and are never converted. - Timestamps are timezone-aware UTC
datetimes. - Models are pydantic classes from
paddock.types, named as the API names them. They keep fields and enum values this SDK version does not know. - A request body, such as an MCP entry or a trigger, is a model from
paddock.typesor adictspelled as the API spells it, in camelCase:{"agentId": ...}. - A list of a paged collection returns a page that iterates every item, fetching later pages as it goes;
.dataand.next_cursorare the first page’s.models.list()takes no parameters and is one page.session.events.list()returns oneEventPagewith.dataand.has_more, paged byafterandbefore, andfiles.list()andmemory.list()return aFileListwhose.dataholds every entry. - Methods that return an agent or a session return
AgentorSession, which carry their sub-resources:agent.mcp,agent.sessions,session.events,session.send.
The main flow
SessionStreamEvent (a snapshot of the session) and EventStreamEvent (an event, its data one of the event classes such as MessageEvent, TurnEndedEvent, or StreamingMessageEvent). It never yields an ErrorStreamEvent: the stream’s error event, such as not_found when the session is deleted, raises PaddockError and ends the stream, so catch it with try/except paddock.PaddockError. Messages are classes by kind: UserMessage, AssistantMessage, ReasoningMessage, ToolCallMessage, ToolResultMessage, UnknownMessage, StreamingMessage, and UnrecognizedMessage for a kind this version does not know. Encode a model as the wire does with model.model_dump(mode="json", by_alias=True, exclude_unset=True).
Operations
What each operation does is in the guides: Templates, Agents and sessions, Capabilities, Configuration, Models, Triggers, and Files.
Errors
A non-2xx answer raisespaddock.PaddockError with status, code, message, details, and request_id. No answer raises paddock.ConnectionError, or its subclass paddock.TimeoutError. Idempotent requests are retried after a connection error, a timeout, or a 5xx; a POST never is. See Errors.