> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paddock.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Python

> The Python server SDK, paddock-sdk: install, authenticate, and call every operation, synchronously or with asyncio.

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

```bash theme={null}
pip install paddock-sdk
```

> [!NOTE]
>
> `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

```python theme={null}
from paddock import Paddock

client = Paddock()  # PADDOCK_API_KEY, PADDOCK_BASE_URL
```

| Argument | Default |
| - | - |
| `api_key` | `PADDOCK_API_KEY`, then `apiKey` of the [credentials file](https://docs.paddock.build/platform/authentication.md#api-keys) when the base URL is unset or the file's; the constructor raises `ValueError` when none is set |
| `base_url` | `PADDOCK_BASE_URL`, then `baseUrl` of the credentials file when the key is the file's, then `https://api.paddock.build/v1` |
| `max_retries` | 2 retries of idempotent requests; `0` turns them off |
| `timeout` | 60 seconds; 10 minutes for files and memory |
| `http_client` | Your own `httpx.Client` (`httpx.AsyncClient` for `AsyncPaddock`) |

`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.

```python theme={null}
import asyncio

from paddock import AsyncPaddock


async def main() -> None:
    async with AsyncPaddock() as client:
        agent = await client.agents.create(template="code-maintainer@1")
        session = await agent.sessions.create()
        await session.send("CI failed on main; fix it.")
        async for s in await client.sessions.list(agent_id=agent.id):
            print(s.id)
        async with session.stream() as events:
            async for event in events:
                print(event.event)


asyncio.run(main())
```

## 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 `datetime`s.
* 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

```python theme={null}
from paddock import Paddock, types

client = Paddock()
template = client.templates.create("./agents/code-maintainer/template.yaml")
agent = client.agents.create(template=f"{template.name}@{template.version}", metadata={"teamId": "t_42"})
session = agent.sessions.create(cwd="repos/web")
session.send("CI failed on main; fix it.")

with session.stream() as events:
    for event in events:
        if not isinstance(event, types.EventStreamEvent):
            continue
        data = event.data
        if isinstance(data, types.MessageEvent) and isinstance(data.message, types.ToolCallMessage):
            print(data.message.tool_call.tool)
        elif isinstance(data, types.TurnEndedEvent):
            print("turn", data.turn.outcome)
            break
```

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

| Resource | Methods |
| - | - |
| `client.templates` | `create(path_or_document, dry_run=False)`, `get(ref)`, `list(name=None)`, `delete("name@version")` |
| `client.models` | `list()` |
| `client.model_providers` | `list()`, `get(name)`, `create(spec)`, `update(name, patch)`, `delete(name)`, `test(name_or_draft, test_model=None)` |
| `client.agents` | `create(template=, metadata=)`, `get(agent_id)`, `list(template=, metadata=)`, `delete(agent_id)` |
| `agent.mcp`, `agent.plugins`, `agent.env` | `list()`, `get(name)`, `add(entry)`, `update(name, entry)`, `delete(name)` |
| `agent.marketplaces` | The same, and `refresh(name)` |
| `agent.model_setting`, `agent.small_model_setting`, `agent.system_prompt` | `get()`, `set(value)`, `delete()` |
| `agent.permissions` | `get()`, `set(spec)` |
| `agent.workflows` | `list()`, `get(name)` |
| `agent.export()` | The agent's effective spec as a `TemplateDocument` |
| `agent.memory` | `list()`, `read(path)`, `write(path, content)`, `delete(path)` |
| `agent.files` | `list(dir=None, recursive=None)`, `read(path)`, `write(path, data)`, `delete(path, recursive=None)` |
| `agent.sessions` | `create(cwd=, system_prompt=, metadata=)`, `list(metadata=)` |
| `client.sessions` | `get(session_id)`, `list(agent_id=, metadata=, created_after=, created_before=)`, `delete(session_id)` |
| `session` | `send(text)`, `stop()`, `stream(after=None)`, `create_token(ttl=)` |
| `session.events` | `list(after=, before=, types=, limit=)` |
| `session.turns` | `list()`, `get(turn_id)` |
| `client.triggers` | `create(spec)`, `get(trigger_id)`, `list()`, `update(trigger_id, spec)`, `delete(trigger_id)`, `test(trigger=, event=)` |
| `trigger.secret` | `get()`, `rotate(secret=None)` |
| `trigger.deliveries` | `list(status=None)`, `get(delivery_id)`, `replay(delivery_id)` |

What each operation does is in the guides: [Templates](https://docs.paddock.build/guides/templates.md), [Agents and sessions](https://docs.paddock.build/guides/agents-and-sessions.md), [Capabilities](https://docs.paddock.build/guides/capabilities.md), [Configuration](https://docs.paddock.build/guides/configuration.md), [Models](https://docs.paddock.build/guides/models.md), [Triggers](https://docs.paddock.build/guides/triggers.md), and [Files](https://docs.paddock.build/guides/files.md).

## 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](https://docs.paddock.build/platform/errors.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.