Skip to main content
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 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 (>=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.

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

​
Where to next

Configuration

Client options, credential resolution, and the provider-client helpers.

Sessions, conversations & turns

Group calls for tracing — from a single call to multi-agent, with full examples.

Rendering prompts

Formats, the rendered result shape, and the neutral converters.

Prompt management

Prompt lifecycle, versions, labels, and project environments.

Errors

The typed error classes the SDK raises, and how to catch them.