Skip to main content
The Python SDK is the distribution 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.types or a dict spelled 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; .data and .next_cursor are the first page’s. models.list() takes no parameters and is one page. session.events.list() returns one EventPage with .data and .has_more, paged by after and before, and files.list() and memory.list() return a FileList whose .data holds every entry.
  • Methods that return an agent or a session return Agent or Session, which carry their sub-resources: agent.mcp, agent.sessions, session.events, session.send.

The main flow

The stream yields 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 raises paddock.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.