Prompty Specification

The Prompty Runtime Specification defines the runtime behavior of Prompty — a markdown file format and execution pipeline for LLM prompts. It is language-agnostic: implementations in any programming language MUST conform to the behavioral contracts defined here.

This specification is intended for implementers building Prompty runtimes in any language. It defines the behavioral contracts that all implementations must satisfy. For user-facing guides on using Prompty, see the Getting Started section.

Version: 0.1.0-draft · Status: Draft

Note

The type system (data model) is defined in TypeSpec under schema/ and emitted into the runtime libraries and Schema Reference. This specification is the source of truth for runtime behavior; it covers what implementations do with those generated types.

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Sections

§	Title	Page
1	Overview & Architecture	§1 Overview & Architecture
2	File Format	§2 File Format
3	Tracing	§3 Tracing
4	Loading	§4 Loading
5	Rendering	§5 Rendering
6	Parsing	§6 Parsing
7	Wire Format	§7 Wire Format
8	Processing	§8 Processing
9	Agent Loop	§9 Agent Loop
10	Streaming	§10 Streaming
11	Registries & Plugin Discovery	§11 Registries & Plugin Discovery
12	Cross-Cutting Concerns	§12 Cross-Cutting Concerns
13	Agent Loop Extensions	§13 Agent Loop Extensions

Public API Surface

Implementations MUST expose the following functions. Each function MUST have an async variant (e.g., load_async). Each function SHOULD have a sync variant.

Function	Signature	Returns	Spec Section
load	(path: string) → PromptAgent	PromptAgent	§4
render	(agent, inputs) → string	Rendered string	§5
parse	(agent, rendered) → Message[]	Message list	§6
prepare	(agent, inputs) → Message[]	Message list	§5 + §6
run	(agent, messages) → result	Processed result	§7 + §8
invoke	(path, inputs) → result	Processed result	§4–§8
turn	(path, inputs, tools?) → result	Processed result	§4–§8 + loop
process	(agent, response) → result	Extracted result	§8
validate_inputs	(agent, inputs) → validated_inputs	Validated dict	§12

Async contract: All pipeline functions MUST have async variants. Implementations SHOULD also provide sync variants. When both exist, they MUST produce identical results for the same inputs.

Conformance Levels

This specification uses three conformance levels:

• MUST — An absolute requirement. An implementation that does not satisfy a MUST requirement is non-conformant.
• SHOULD — Recommended but not required. An implementation may omit a SHOULD requirement with good reason, but the implications must be understood.
• MAY — Truly optional. An implementation may provide or omit a MAY feature freely.