microsoft/prompty: a .prompty file format for prompts you can run from Python, TypeScript or VS Code

The problem Prompty addresses: prompts that live outside the application

A prompt usually starts as a string in a source file and ends up as a string in three source files, one per language, drifting apart. Prompty's answer is to make the prompt an asset: a single .prompty file that a runtime loads, renders and executes. The README frames the format as one that improves observability, understandability and portability, and describes the flow as a .prompty file going through a runtime to an LLM provider.

The audience is developers building AI applications who want the prompt to be a reviewable artifact rather than an inline literal. Because the file carries its own model configuration, inputs and tool declarations, the same asset can be opened in VS Code, run from Python, or run from TypeScript. That is the whole proposition. It is not an orchestration framework, and the README does not present it as one.

Inside a .prompty file: frontmatter, role markers and variable references

A .prompty file has two parts. YAML frontmatter holds model config, inputs and tools. The markdown body holds the prompt text, with lines starting with system:, user: or assistant: defining message boundaries.

The model block names a provider and a connection. The README's examples use provider: openai and provider: foundry, with connection.kind: key and either apiKey or endpoint plus apiKey. Model options such as temperature sit under model.options. Inputs are declared as a list with name, kind and an optional default, and tools are declared with name, kind: function, description and a parameters list.

Template syntax is Jinja2 ({{variable}}, {% if %}, {% for %}) or Mustache ({{variable}}, {{#section}}), selected through template.format.kind. Variable references are a separate mechanism: ${env:VAR} reads a required environment variable, ${env:VAR:default} supplies a fallback, and ${file:path.json} loads file content. The README states that ${file:...} references are scoped to the containing .prompty file's directory by default, and that host applications can opt into additional allowed roots through runtime load options. Prompts cannot grant themselves broader filesystem access. That last sentence is a security boundary stated in the documentation, not a feature name, and it is worth reading literally.

Installing Prompty for Python and running a first prompt

Start with the Python runtime. The README gives an install line with extras that select the template engine and the provider.

pip install "prompty[jinja2,openai]"

Write a file named greeting.prompty. The frontmatter sets the model and the template engine; the body uses system: and user: markers, and interpolates an input named name.

---
name: greeting
model:
  id: gpt-4o-mini
  provider: openai
  connection:
    kind: key
    apiKey: ${env:OPENAI_API_KEY}
template:
  format:
    kind: jinja2
  parser:
    kind: prompty
---
system:
You are a friendly assistant.

user:
Say hello to {{name}}.

Then invoke the file. The README's example passes inputs as a dictionary and prints the result.

import prompty

result = prompty.invoke("greeting.prompty", inputs={"name": "Jane"})
print(result)

The same README shows the pipeline split into stages when you need to inspect the middle: prompty.load returns an agent, prompty.prepare turns the agent and inputs into messages, and prompty.run executes them. There is also prompty.invoke_async for the async path. The TypeScript equivalent installs @prompty/core plus a provider package, then calls invoke, or load, prepare and run in sequence.

Switching endpoints without editing the prompt body

The openai provider can target OpenAI-compatible control planes, gateways or self-hosted model servers. The mechanism is model.connection.endpoint, which accepts an environment reference with a default.

---
name: governed-greeting
model:
  id: gpt-4o-mini
  provider: openai
  connection:
    kind: key
    endpoint: ${env:OPENAI_BASE_URL:https://api.openai.com/v1}
    apiKey: ${env:OPENAI_API_KEY}
template:
  format:
    kind: jinja2
  parser:
    kind: prompty
---
system:
You are a careful assistant.

user:
Say hello to {{name}}.

The README's example for routing through a gateway is two environment variables, with the prompt file unchanged.

export OPENAI_BASE_URL=https://api.tuningengines.com/v1
export OPENAI_API_KEY=sk-te-your-inference-key

This is the most concrete portability claim in the documentation, and it is a narrow one: the endpoint and key move to the environment, the prompt body does not. Whether the gateway preserves the semantics your prompt relies on is outside what the README states.

Tracing, the VS Code extension, and what the trace files actually contain

Every execution generates a .tracy trace file, according to the README. The VS Code extension's trace viewer inspects the pipeline in four named stages: render, parse, execute, process, with timing and payloads. The same extension adds a connections sidebar for OpenAI, Microsoft Foundry and Anthropic endpoints, a live preview that renders the prompt with template interpolation as you type, and a chat panel that opens automatically for thread-enabled prompts, with tool calling support.

The step-by-step Python API maps onto those stages, which is the useful part: if a rendered prompt is wrong, you can stop at prepare and read the messages before anything is sent. The README does not document trace file retention, size limits or a way to redact payloads before they are written, and it does not describe a rollback path for a prompt change. Those omissions matter if .tracy files are going to sit next to your source in a repository.

Where Prompty is the wrong tool, and how it differs from a code-first framework

The README carries its own warning: this is the v2 branch, currently in alpha, and the API, file format and tooling are under active development and may change. Treat that as a real constraint. A team that needs a frozen prompt format with a compatibility guarantee should not build on a format the maintainers say may change.

There is a second boundary. Prompty is a file format plus runtimes, not an orchestration engine. If your application's logic is a graph of retrievers, conditional branches and custom callbacks, a .prompty file describes one prompt and its model configuration; the control flow stays in your code. Frameworks that keep prompts as code, with the prompt assembled by the same functions that call the model, are the opposite trade-off: less portability across languages, but no second format to keep in sync and no gap between what the code does and what the file says.

The provider list is also narrower than the format suggests. The README's install extras and connection examples cover OpenAI, Microsoft Foundry and Anthropic. The extension's connections sidebar lists those three. If your model server is not reachable through an OpenAI-compatible endpoint or one of those providers, the format does not help you.

Maintenance, releases and licence

The repository is not archived, and the last push was on 2026-09-10, the same day as the python/2.0.0 release. The TypeScript provider packages listed as recent releases, @prompty/openai v2.0.0-alpha.1 and @prompty/foundry v2.0.0-alpha.1, date from 2026-04-02, so the runtimes are not moving in lockstep. Before you write prompt files into a shared repository, check which runtime version your team will run and whether it reads the same frontmatter keys.

Upgrade cost has a specific shape here. Because the file format is versioned alongside the runtimes, a change to frontmatter or template semantics can require editing every .prompty file rather than bumping a dependency. The README points contributors at .gitattributes for LF normalization and a repository hook enabled with git config core.hooksPath .githooks, which is about repository hygiene, not about your prompt files.

The licence is MIT. That is permissive and places few obligations on how you redistribute or modify the code. It says nothing about the prompts you write or the model outputs you receive, which are governed by your provider's terms, not by this repository.

Editorial conclusion

Adopt Prompty if you want prompts to live in version control as .prompty files with model config, inputs and tools attached, and you accept that the v2 branch is alpha. Do not adopt it if you need a frozen file format today, or if your prompts are inseparable from a framework's own chain and callback objects. Verify first that the runtime you intend to use matches the file format you write: the Python package on PyPI is version 2.0.0, while the TypeScript provider packages npm lists as @prompty/openai v2.0.0-alpha.1 and @prompty/foundry v2.0.0-alpha.1. Check the README for your runtime before committing prompt files to a shared repository.

Frequently asked questions

Official sources

1. License: MIT
2. microsoft/prompty on GitHub
3. Project website
4. README
5. Releases