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

# Rendering prompts

> Render a managed prompt, shape it per provider, or convert the neutral result.

`client.prompts.render(slug, **options)` renders a prompt's `latest` version for the client's `project_id` in a single request. Set `format` — on the client or per call — to get a result shaped for that provider; omit it to get the neutral result. It is the primary runtime method.

```python theme={null}
client = create_client(format="openai")

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

The keyword options are `format`, `label`, `variables`, `fallback`, and `on_unknown_role`: `label` names the label to render — `latest`, the only label a prompt has, which is also what an omitted `label` serves — `format` overrides the client default, and `fallback` is served on a transient network or 5xx failure. The return shape is fixed by the call's `format`, not by the network outcome. Authored `developer` blocks render as-is; the SDK maps them per provider (OpenAI keeps `developer`, Anthropic folds them into `system`). `on_unknown_role` (`"drop"` default, `"warn"`, or `"error"`) sets how a message with an unrecognized role is handled during provider conversion — see [Unknown roles](#unknown-roles).

## Shaped result

With a `format`, `render` returns a dict you can spread straight into a provider request. `format="openai"` returns `{"messages", "config", "metadata"}`; `format="anthropic"` returns `{"system", "messages", "config", "metadata"}` — the authored system and developer instructions are folded into a top-level `system` string, which Anthropic takes as a separate request field. When the prompt authors tools, the result also carries provider-shaped `tools` and `tool_choice`.

| Key | Holds |
| - | - |
| `system` | **Anthropic only.** The folded system/developer instruction text, passed as Anthropic's top-level `system`. Omit it and you drop the authored instructions. |
| `messages` | The rendered messages, shaped for the provider. |
| `config` | Model parameters from the resolved version — `model`, `temperature`, `max_tokens`, and any other stored keys — passed through verbatim, so the dict spreads straight into `create()`. |
| `tools` / `tool_choice` | Provider-shaped tool definitions and directive, present only when the prompt authors tools. Spread them into the request so a tool-using prompt isn't sent without its tools. |
| `metadata` | Provenance: `prompt_id`, `version`, `version_id`, `label` (the label the prompt resolved through, `latest`), and `slug`. |

Spread the result into the request:

```python theme={null}
# OpenAI — tools/tool_choice are present only when the prompt authors tools
res = openai.chat.completions.create(
    **prompt["config"],
    messages=prompt["messages"],
    **({"tools": prompt["tools"]} if "tools" in prompt else {}),
    **({"tool_choice": prompt["tool_choice"]} if "tool_choice" in prompt else {}),
)
```

```python theme={null}
# Anthropic — pass the folded system alongside the messages, when the prompt has one
res = anthropic.messages.create(
    **prompt["config"],
    **({"system": prompt["system"]} if "system" in prompt else {}),
    messages=prompt["messages"],
)
```

## Neutral result and converters

Omit `format` (on both the client and the call) to get the neutral `RenderedPrompt` dataclass: `messages`, `tools`, `tool_choice`, `prompt_id`, `version`, `version_id`, `content_hash`, `label`, `slug`, and `block_render_record`. The version's model config is exposed as `model_config_` — the trailing underscore avoids Pydantic's reserved `model_config` attribute. This is the path for a client the shaper does not cover, such as LangChain, or for driving one prompt through more than one provider.

The package root, `to11ai_sdk`, exports the converters that turn a neutral result into a provider's request shape:

| Helper | Purpose |
| - | - |
| `to_openai_messages` / `to_anthropic_messages` | Convert the neutral `messages` to the provider's message list. Both accept an `on_unknown_role` argument — see [Unknown roles](#unknown-roles). |
| `to_anthropic_system` | Fold the `system`/`developer` turns into Anthropic's top-level `system` string (they are omitted from `to_anthropic_messages`). Pair the two for an Anthropic call. |
| `to_openai_tools` / `to_anthropic_tools` | Convert `tools` to the provider's tool schema. |
| `to_openai_tool_choice` / `to_anthropic_tool_choice` | Convert `tool_choice` to the provider's directive. |

With a `format`, `render` applies the conversion for you, so most apps call the converters only for message history they build themselves, such as a rendered prompt followed by the conversation so far:

```python theme={null}
from to11ai_sdk import create_client, to_openai_messages, to_openai_tools

client = create_client()  # no format: render returns the neutral RenderedPrompt
rendered = client.prompts.render("weather-concierge", variables={"city": "NYC"})
res = openai.chat.completions.create(
    **(rendered.model_config_ or {}),
    messages=to_openai_messages(rendered.messages),
    **({"tools": to_openai_tools(rendered.tools)} if rendered.tools else {}),
)
```

## Unknown roles

The message converters recognize `system`, `user`, `assistant`, `developer`, and `tool`. A message whose role is anything else is handled by the `on_unknown_role` policy — set it per call, on `create_client`, or on the converter directly:

| Mode | Behavior |
| - | - |
| `"drop"` (default) | The message is omitted silently. |
| `"warn"` | The message is omitted and a warning on the `to11ai_sdk` logger names the role and index. |
| `"error"` | Conversion raises `UnknownRoleError` (carrying `code="unknown_role"`, `role`, and `index`). |

```python theme={null}
# Fail loudly when a hand-built message array has an unrecognized role
messages = to_openai_messages(history, on_unknown_role="error")
```

A prompt rendered by to11 only ever carries known roles, so on `render()` this matters mainly when you convert your own message arrays (assembled conversation history, messages from another source). `on_unknown_role="error"` on `render()` is a way to assert that invariant explicitly.

## Skills

A [skill](https://to11.ai/docs/skills/concepts.md) is the second kind of prompt: it is delivered to a developer's machine as files and read there by a coding agent, rather than sent to a model as messages. `render()` does not render one.

* **You will not find one by accident.** `prompts.list()` returns chat prompts only.
* **If you render one with `render()`, it raises.** The SDK validates every render response against a closed model, and a skill's response does not match it, so the call raises a validation error rather than handing back something your code would misread.
* **To read a skill's files from code**, list the skills across an organization with `prompts.list_org_prompts(org_id=...)` and render one exact version with `prompts.render_skill_version(project_id=..., slug=..., version=...)`. The result's `files` holds each file's `filename` and `content`. See [Prompt management](https://to11.ai/docs/reference/python-sdk/prompts.md#skills).

To install skills on a machine, use the [to11 CLI](https://to11.ai/docs/reference/cli.md).


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