microsoft/prompty

microsoft/prompty

Description: Prompty makes it easy to create, manage, debug, and evaluate LLM prompts for your AI applications. Prompty is an asset class and format for LLM prompts designed to enhance observability, understandability, and portability for developers.

Language: TypeScript

License: MIT

Stars: 1217

Forks: 117

Open issues: 9

Created: 2024-04-22T16:55:53Z

Pushed: 2026-06-10T05:34:42Z

Default branch: main

Fork: no

Archived: no

README:

Prompty

> ⚠️ v2 Alpha — This is the v2 branch of Prompty, currently in alpha. The API, file format, and tooling are under active development and may change. Feedback welcome via Issues.

Prompty is a markdown file format (.prompty) for LLM prompts. Write your prompt once — run it from VS Code, Python, or TypeScript.

Quick Start

1. Write a .prompty file

---
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}}.

2. Run it

Python

pip install "prompty[jinja2,openai]"

import prompty

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

TypeScript

npm install @prompty/core @prompty/openai

import { invoke } from "@prompty/core";
import "@prompty/openai";

const result = await invoke("greeting.prompty", { name: "Jane" });
console.log(result);

VS Code — open the .prompty file and press F5.

Contributor hygiene

Prompty normalizes text files to LF line endings via .gitattributes. Enable the repo hook once per clone so staged files are normalized before each commit and whitespace errors are blocked locally:

git config core.hooksPath .githooks

Before opening a PR, you can run the same core hygiene checks directly:

git diff --check
git ls-files --eol | grep 'w/crlf'

VS Code Extension

The v2 extension includes a connections sidebar, live preview, chat mode, and a redesigned trace viewer.

Create

Right-click in the explorer → New Prompty to scaffold a new prompt file.


Preview

See the rendered prompt with live markdown rendering and template interpolation as you type.


Connections

Manage model connections from the sidebar — add OpenAI, Microsoft Foundry, or Anthropic endpoints, set a default, and browse available models.


Chat Mode

Thread-enabled prompts automatically open an interactive chat panel with tool calling support.


Tracing

Every execution generates a .tracy trace file. Click to inspect the full pipeline — render, parse, execute, process — with timing and payloads.


Runtimes

Python

pip install "prompty[all]" # everything
pip install "prompty[jinja2,openai]" # just OpenAI
pip install "prompty[jinja2,foundry]" # Microsoft Foundry
pip install "prompty[jinja2,anthropic]" # Anthropic

import prompty

# Full pipeline: load → render → parse → execute → process
result = prompty.invoke("my-prompt.prompty", inputs={...})

# Step-by-step
agent = prompty.load("my-prompt.prompty")
messages = prompty.prepare(agent, inputs={...})
result = prompty.run(agent, messages)

# Async
result = await prompty.invoke_async("my-prompt.prompty", inputs={...})

See [runtime/python/prompty/README.md](runtime/python/prompty/README.md) for full API docs.

TypeScript

npm install @prompty/core @prompty/openai # OpenAI
npm install @prompty/core @prompty/foundry # Microsoft Foundry
npm install @prompty/core @prompty/anthropic # Anthropic

import { load, prepare, run, invoke } from "@prompty/core";
import "@prompty/openai"; // registers the provider

// Full pipeline
const result = await invoke("my-prompt.prompty", { name: "Jane" });

// Step-by-step
const agent = await load("my-prompt.prompty");
const messages = await prepare(agent, { name: "Jane" });
const result = await run(agent, messages);

See [runtime/typescript/packages/core/README.md](runtime/typescript/packages/core/README.md) for full API docs.

.prompty File Format

A .prompty file has two parts: YAML frontmatter (model config, inputs, tools) and a markdown body (the prompt with role markers and template syntax).

---
name: my-prompt
model:
id: gpt-4o
provider: foundry
connection:
kind: key
endpoint: ${env:AZURE_OPENAI_ENDPOINT}
apiKey: ${env:AZURE_OPENAI_API_KEY}
options:
temperature: 0.7
inputs:
- name: question
kind: string
default: What is the meaning of life?
tools:
- name: get_weather
kind: function
description: Get the current weather
parameters:
- name: location
kind: string
template:
format:
kind: jinja2
parser:
kind: prompty
---
system:
You are a helpful assistant.

user:
{{question}}

Role markers

Lines starting with system:, user:, or assistant: define message boundaries.

Template syntax

Jinja2 ({{variable}}, {% if %}, {% for %}) or Mustache ({{variable}}, {{#section}}).

Variable references

| Syntax | Purpose | |--------|---------| | ${env:VAR} | Environment variable (required) | | ${env:VAR:default} | With fallback value | | ${file:path.json} | Load file content from the prompt directory tree |

${file:...} references are scoped to the containing .prompty file's directory by default. Host applications can opt into additional allowed roots through runtime load options; prompts cannot grant themselves broader filesystem access.

Legacy format

Prompty v1 files are automatically migrated with deprecation warnings. See the [Python README](runtime/python/prompty/README.md#legacy-format-support) for details.

Contributing

See [SUPPORT.md](SUPPORT.md) for help and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community guidelines.

To release a new version, see [RELEASING.md](RELEASING.md).

License

[MIT](LICENSE)