What's New in v2

The Core Pattern Is the Same

If you used Prompty v1, the mental model carries forward unchanged. A .prompty file is still a markdown file with YAML frontmatter. The pipeline still works the same way:

.prompty file → load → render → parse → execute → process → result

The functions you know still do exactly what they did:

Function	What it does (same as v1)
`load()`	Parse a `.prompty` file into a typed agent object
`prepare()`	Render the template + parse role markers into messages
`invoke()`	Full pipeline: load → prepare → execute → process
`run()`	Execute pre-prepared messages (skip load + prepare)

If your v1 code used load() → prepare() → invoke(), the same pattern works in v2 with updated frontmatter property names. That’s it.

What the file format updates look like

The frontmatter property names were cleaned up to align with the Prompty schema, but the structure is the same — model config, inputs, template settings:

# v1                           # v2
model:                          model:
  api: chat                       apiType: chat
  configuration:                  provider: foundry
    type: azure_openai            connection:
    azure_endpoint: ${env:X}        kind: key
    api_key: ${env:Y}               endpoint: ${env:X}
  parameters:                       apiKey: ${env:Y}
    max_tokens: 500               options:
    temperature: 0.7                maxOutputTokens: 500
                                    temperature: 0.7

See the Migration Guide for the full property mapping.

What’s New: `turn()` for Agentic Workflows

The one conceptually new function in v2 is turn(). It handles what happens when an LLM response includes tool calls — something v1 didn’t natively support.

turn() runs a loop: send messages → get response → if tool calls, execute them → re-send → repeat until the model returns a final answer.

from prompty import turn

result = turn(
    "agent.prompty",
    inputs={"question": "What's the weather in Seattle?"},
    tools={"get_weather": get_weather},
)

import { turn } from "@prompty/core";

const result = await turn("agent.prompty", {
  inputs: { question: "What's the weather in Seattle?" },
  tools: { get_weather: getWeather },
});

var result = await Pipeline.TurnAsync(
    "agent.prompty",
    new() { ["question"] = "What's the weather in Seattle?" },
    tools: new() { ["get_weather"] = GetWeather });

use prompty::TurnOptions;
use serde_json::json;

prompty::register_tool_handler("get_weather", |args| {
    Box::pin(async move {
        let city = args["city"].as_str().unwrap_or("unknown");
        Ok(json!(format!("72°F in {city}")))
    })
});

let result = prompty::turn_from_path(
    "agent.prompty",
    Some(&json!({ "question": "Weather in Seattle?" })),
    Some(TurnOptions {
        max_iterations: Some(10),
        ..Default::default()
    }),
).await?;

Without tools, turn() behaves identically to invoke() — the only difference is that it tracks turn numbers for multi-turn conversations.

What the trace looks like

turn 1
  prepare
    Jinja2Renderer
    PromptyChatParser
  Executor
  toolCalls          ← only appears when the LLM returns tool calls
    get_weather
  Executor           ← re-sends with tool results
  Processor

Three Runtimes, One File Format

v2 adds TypeScript and C# runtimes alongside the existing Python runtime, and introduces a new Rust runtime. All four share the same .prompty file format and public API:

	Python	TypeScript	C#	Rust
Package	`prompty`	`@prompty/core`	`Prompty.Core`	`prompty`
Providers	`prompty[openai]`	`@prompty/openai`	`Prompty.OpenAI`	`prompty-openai`
Install	`uv pip install`	`npm install`	`dotnet add package`	`cargo add`

Other Improvements

Streaming

First-class streaming with tracing integration:

PromptyStream / AsyncPromptyStream wrappers
Automatic chunk accumulation for trace output
Works with all providers (OpenAI, Azure, Anthropic)

Structured Output

Define outputs in frontmatter → automatic response_format:

outputs:
  - name: city
    kind: string
  - name: temperature
    kind: float

Responses are JSON-parsed and validated when an output schema is defined.

Tracing & Observability

@trace / [Trace] decorator wraps any function with spans
Pluggable backends: console, JSON files, OpenTelemetry
All pipeline stages traced automatically

Provider Support

OpenAI — direct API key
Azure OpenAI / Foundry — API key, Entra ID, managed identity
Anthropic — via provider registry
Extensible: implement executor/processor protocols and register

Pipeline Architecture

The four-stage pipeline (Render → Parse → Execute → Process) is now independently replaceable via the discovery/registry system. Third-party providers can register as plugins.

VS Code Extension

Live preview of rendered prompts
Connection management for OpenAI and Azure endpoints
Copilot Chat integration