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

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. Spread the result into the request:

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: 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:

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:
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 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.
To install skills on a machine, use the to11 CLI.