Prompted output templates reject literal JSON braces

Author: qdivanCreated Aug 15, 2026Updated Sep 18, 2026
Labelsbugoutputpydanty:bugloopablep:4-lowneeds-maintainer-actionhas-workaround

Initial Checks

  • I am using the current main checkout.
  • I searched the issue tracker and pull requests for build_instructions, literal braces, prompted output, schema template, and output template.

Description

PromptedOutput.template documents {schema} as the placeholder that is replaced with the output JSON schema. However, StructuredTextOutputSchema.build_instructions() applies str.format(schema=...) to the entire template. A literal JSON example in the template is consequently interpreted as another format field and raises KeyError before a model request is made.

A template such as Return JSON {"name": "x"} matching {schema} should preserve the JSON example while substituting only {schema}. Escaped braces ({{ and }}) currently work, but the documented placeholder contract does not say that every other literal brace must be escaped.

Minimal, Reproducible Example

python
from pydantic_ai._output import PromptedOutputSchema
from pydantic_ai.output import OutputObjectDefinition

object_def = OutputObjectDefinition(
    json_schema={"type": "object", "properties": {"name": {"type": "string"}}}
)

PromptedOutputSchema.build_instructions(
    'Return JSON {"name": "x"} matching {schema}',
    object_def,
)

Actual result:

KeyError: '"name"'

Expected result: the literal JSON example is retained and {schema} is replaced with the serialized schema. This happens before model invocation, so no Logfire trace is available.

Version

  • Python: 3.11.15
  • Pydantic AI: current main at ffd580e6ce90d51974c3f1645e83bf555d634d87 (0.0.1.dev1+ffd580e)
  • LLM provider SDK: not applicable; the failure occurs before a request is sent.