Getting Started

What is Prompty?

Prompty is a markdown file format for LLM prompts. A .prompty file combines structured YAML frontmatter (model config, inputs, tools) with a markdown body that becomes the prompt instructions. The runtime loads, renders, parses, and executes these files.

flowchart LR
    subgraph file["greeting.prompty"]
        frontmatter["YAML frontmatter<br/><br/>name<br/>model + connection<br/>inputs / outputs<br/>tools<br/>template config"]
        body["Markdown body<br/><br/>role markers<br/>instructions<br/>template variables"]
    end

    frontmatter --> loaded["typed Prompty object"]
    body --> instructions["agent instructions"]
    instructions --> render["render<br/>{{ userName }}"]
    render --> parse["parse<br/>system / user / assistant messages"]
    loaded --> execute["execute<br/>provider + model config"]
    parse --> execute
    execute --> result["processed result"]

    classDef filePart fill:#eff6ff,stroke:#2563eb,color:#1e3a8a
    classDef runtime fill:#f0fdf4,stroke:#16a34a,color:#14532d
    class frontmatter,body filePart
    class loaded,instructions,render,parse,execute,result runtime

The frontmatter is configuration. The body is the prompt. Prompty combines both: frontmatter becomes a typed runtime object, and the markdown body becomes rendered instructions that are parsed into chat messages.

Installation

Python

# Core + Jinja2 renderer + OpenAI provider
uv pip install "prompty[jinja2,openai]"

# With Microsoft Foundry support
uv pip install "prompty[jinja2,foundry]"

# With Anthropic support
uv pip install "prompty[jinja2,anthropic]"

# Everything
uv pip install "prompty[all]"

Note

Prompty v2 requires Python ≥ 3.11. Use uv for local environments and package management when working from source.

TypeScript

# Core + OpenAI provider
npm install @prompty/core @prompty/openai

# With Microsoft Foundry support
npm install @prompty/core @prompty/foundry

# With Anthropic support
npm install @prompty/core @prompty/anthropic

C#

dotnet add package Prompty.Core --prerelease
dotnet add package Prompty.OpenAI --prerelease  # or Prompty.Foundry, Prompty.Anthropic

Note

C# packages are in alpha preview. Install with --prerelease to get the latest version.

Rust

cargo add prompty prompty-openai

Choose a Provider

Provider	Python extra	TypeScript package	C# package	Rust crate	Notes
OpenAI	prompty[openai]	@prompty/openai	Prompty.OpenAI	prompty-openai	Direct OpenAI and OpenAI-compatible endpoints.
Microsoft Foundry	prompty[foundry]	@prompty/foundry	Prompty.Foundry	prompty-foundry	Foundry/Azure OpenAI deployments; azure remains a deprecated alias.
Anthropic	prompty[anthropic]	@prompty/anthropic	Prompty.Anthropic	prompty-anthropic	Claude via Anthropic Messages API.

If you are not sure which model.id or deployment to use, see Discover Available Models.

Write Your First .prompty File

Create a file called greeting.prompty:

---
name: greeting
description: A friendly greeting prompt
model:
  id: gpt-4o-mini
  provider: openai
  connection:
    kind: key
    apiKey: ${env:OPENAI_API_KEY}
inputs:
  - name: userName
    kind: string
    default: World
---
system:
You are a friendly assistant who greets people warmly.

user:
Say hello to {{userName}} and ask how their day is going.

Run It

Python

import prompty

# All-in-one: load → render → parse → execute → process
result = prompty.invoke(
    "greeting.prompty",
    inputs={"userName": "Jane"},
)
print(result)
# "Hello Jane! 👋 How's your day going so far?"

TypeScript

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

const result = await invoke("greeting.prompty", {
  userName: "Jane",
});
console.log(result);
// "Hello Jane! 👋 How's your day going so far?"

C#

using Prompty.Core;

var result = await Pipeline.InvokeAsync("greeting.prompty", new() { ["userName"] = "Jane" });
Console.WriteLine(result);
// "Hello Jane! 👋 How's your day going so far?"

Rust

use prompty;
use prompty_openai;
use serde_json::json;

// Register providers
prompty::register_defaults();
prompty_openai::register();

// All-in-one: load → render → parse → execute → process
let result = prompty::invoke_from_path(
    "greeting.prompty",
    Some(&json!({ "userName": "Jane" })),
).await?;
println!("{result}");
// "Hello Jane! 👋 How's your day going so far?"

Step-by-Step Pipeline

For more control, use the pipeline stages individually:

Python

import prompty

# 1. Load the .prompty file → typed Prompty object
agent = prompty.load("greeting.prompty")

# 2. Render template + parse → list[Message]
messages = prompty.prepare(agent, inputs={"userName": "Jane"})

# 3. Call the LLM + process → clean result
result = prompty.run(agent, messages)

TypeScript

import { load, prepare, run } from "@prompty/core";
import "@prompty/openai";

const agent = await load("greeting.prompty");
const messages = await prepare(agent, { userName: "Jane" });
const result = await run(agent, messages);

C#

using Prompty.Core;

// 1. Load the .prompty file → Prompty
var agent = PromptyLoader.Load("greeting.prompty");

// 2. Render template + parse → messages
var rendered = await Pipeline.RenderAsync(agent, new() { ["userName"] = "Jane" });
var messages = await Pipeline.ParseAsync(agent, rendered);

// 3. Call the LLM + process → clean result
var response = await Pipeline.ExecuteAsync(agent, messages);
var result = await Pipeline.ProcessAsync(agent, response);

Rust

use prompty;
use prompty_openai;
use serde_json::json;

prompty::register_defaults();
prompty_openai::register();

// 1. Load the .prompty file → typed agent
let agent = prompty::load("greeting.prompty")?;

// 2. Render template + parse → messages
let messages = prompty::prepare(
    &agent, Some(&json!({ "userName": "Jane" }))
).await?;

// 3. Call the LLM + process → clean result
let result = prompty::run(&agent, &messages).await?;

Environment Variables

Use ${env:VAR_NAME} in frontmatter to reference environment variables. Create a .env file in your project root:

OPENAI_API_KEY=sk-your-key-here

Prompty automatically loads .env files.

Complete Example

Here’s a full, tested example you can copy and run:

Python

chat_basic.py

"""Basic chat completion with OpenAI.

This example loads a .prompty file and runs a simple chat completion.
Used in: how-to/openai.mdx, getting-started/index.mdx
"""
from __future__ import annotations

from prompty import invoke, load

agent = load("chat-basic.prompty")
result = invoke(agent, inputs={"question": "What is Prompty?"})
print(result)

TypeScript

chat-basic.ts

/**
 * Basic chat completion — load a .prompty file and invoke it.
 *
 * @example
 * ```bash
 * OPENAI_API_KEY=sk-... npx tsx examples/chat-basic.ts
 * ```
 */
import "@prompty/openai"; // auto-registers openai executor + processor
import { invoke } from "@prompty/core";
import { resolve } from "node:path";

const promptyFile = resolve(import.meta.dirname, "../../prompts/chat-basic.prompty");

export async function chatBasic(question?: string): Promise<string> {
  const result = await invoke(promptyFile, {
    question: question ?? "What is Prompty?",
  });
  return result as string;
}

// Run directly
const response = await chatBasic();
console.log(response);

C#

ChatBasic.cs

// Copyright (c) Microsoft. All rights reserved.

using Prompty.Core;
using Prompty.OpenAI;

namespace DocsExamples.Examples;

/// <summary>
/// Basic chat completion — load a .prompty file and invoke it.
/// </summary>
public static class ChatBasic
{
    /// <summary>
    /// Load a .prompty file and run the full pipeline (render → parse → execute → process).
    /// </summary>
    public static async Task<object> RunAsync(string promptyPath, Dictionary<string, object?>? inputs = null)
    {
        // One-time setup — registers renderers, parser, and OpenAI provider
        new PromptyBuilder()
            .AddOpenAI();

        // Full pipeline: load → prepare → run
        var result = await Pipeline.InvokeAsync(promptyPath, inputs);
        return result;
    }
}

Rust

chat_basic.rs

use prompty;
use prompty_openai;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    prompty::register_defaults();
    prompty_openai::register();

    let result = prompty::invoke_from_path(
        "greeting.prompty",
        Some(&json!({ "userName": "Jane" })),
    ).await?;

    println!("{result}");
    Ok(())
}

Next Steps

• The .prompty File Format — understand the anatomy of a .prompty file
• Pipeline Architecture — how render → parse → execute → process works
• Schema Reference — all available frontmatter properties
• How-To Guides — practical recipes for common tasks
• Tutorials — hands-on walkthroughs from chat to production
• Why Prompty? — design philosophy and motivation