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

# Python SDK

> Install the to11 Python SDK, render a prompt, and send it through the gateway.

The `to11ai-sdk` package gives Python services typed access to to11. You use it to render managed prompts, wire your own provider client to the to11 gateway with the right headers, and group calls into sessions, conversations, and turns for tracing. It mirrors the [TypeScript SDK](/docs/reference/typescript-sdk) surface with snake\_case, synchronous methods.

The SDK is **header-only**: it talks to the to11 **platform API** (the control plane) for prompt and configuration data, but it never sends the model request itself — there is no `.chat()`. Your own provider client (OpenAI or Anthropic) sends the request through the to11 gateway at `https://gw.to11.ai`, and the SDK supplies the base URL, the headers, and the request shape.

The distribution is published as `to11ai-sdk` and imported as `to11ai_sdk`, under the MPL-2.0 license.

## Runtime requirements

* **Python:** 3.10 or later.
* **A provider client:** because the SDK is header-only, your app also installs the provider client that sends the model call — `openai` or `anthropic`.
* **One runtime dependency:** [Pydantic](https://docs.pydantic.dev/) (>=2.13). The client is synchronous — there is no async client; every method returns its value directly.
* **Credentials:** a to11 API key and project id. The SDK runs server-side and reads `TO11_API_KEY` and `TO11_PROJECT_ID` from the environment. The control-plane and gateway URLs default to production (`https://api.to11.ai` and `https://gw.to11.ai`); override them with `TO11_API_URL` / `TO11_GATEWAY_URL` for a self-hosted to11. The gateway URL is the host only — no `/v1` path; the SDK adds the path each provider client expects.

## Installation

Install `to11ai-sdk` alongside your provider client.

<CodeGroup>
  ```bash pip theme={null}
  pip install to11ai-sdk openai
  ```

  ```bash uv theme={null}
  uv add to11ai-sdk openai
  ```

  ```bash poetry theme={null}
  poetry add to11ai-sdk openai
  ```
</CodeGroup>

## The happy path

Create a client, render a prompt for the current environment, and send it through the gateway with your OpenAI client. Setting `format="openai"` shapes the rendered prompt so you can spread it straight into the request; `client.openai_options()` points the OpenAI client at the gateway; and `client.turn().headers(prompt)` supplies the auth, trace, and provenance headers.

```python theme={null}
from to11ai_sdk import create_client
from openai import OpenAI

# Reads TO11_API_KEY and TO11_PROJECT_ID from the environment.
client = create_client(env="production", format="openai")
openai = OpenAI(**client.openai_options())

prompt = client.prompts.render("welcome-message", variables={"name": "Ada"})

res = openai.chat.completions.create(
    **prompt["config"],
    messages=prompt["messages"],
    extra_headers=client.turn().headers(prompt),
)
```

That is the whole integration: `prompt["config"]` carries the model parameters, `prompt["messages"]` the rendered messages, and `turn().headers(prompt)` the headers that authenticate the gateway call and record which prompt produced the trace. The request runs on the model and provider you configured for the prompt; you never assemble a `provider::model` string or merge headers by hand.

<Note>
  Run the SDK server-side and keep your to11 API key there. It carries gateway access, so it must never reach an end user's device. See [Configuration](/docs/reference/python-sdk/configuration).
</Note>

## Where to next

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/docs/reference/python-sdk/configuration">
    Client options, credential resolution, and the provider-client helpers.
  </Card>

  <Card title="Sessions, conversations & turns" icon="diagram-project" href="/docs/reference/python-sdk/sessions-and-turns">
    Group calls for tracing — from a single call to multi-agent, with full examples.
  </Card>

  <Card title="Rendering prompts" icon="download" href="/docs/reference/python-sdk/rendering-prompts">
    Formats, the rendered result shape, and the neutral converters.
  </Card>

  <Card title="Prompt management" icon="file-text" href="/docs/reference/python-sdk/prompts">
    Prompt lifecycle, versions, labels, and project environments.
  </Card>

  <Card title="Errors" icon="triangle-alert" href="/docs/reference/python-sdk/errors">
    The typed error classes the SDK raises, and how to catch them.
  </Card>
</CardGroup>