### Quick Start

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/implementation/python.mdx

A simple example demonstrating how to use Prompty for an all-in-one execution.

```APIDOC
## Quick Start

```python
import prompty

# All-in-one execution
result = prompty.invoke("greeting.prompty", inputs={"name": "Jane"})
print(result)
```
```

--------------------------------

### Quick Start: Invoke a .prompty File

Source: https://github.com/microsoft/prompty/blob/main/runtime/typescript/packages/core/README.md

A quick start example demonstrating how to load and run a .prompty file with a specific question. Ensure the OpenAI provider is registered.

```typescript
import "@prompty/openai"; // registers the OpenAI provider
import { invoke } from "@prompty/core";

// Load and run a .prompty file
const result = await invoke("./my-prompt.prompty", {
  question: "What is the capital of France?",
});
console.log(result);
```

--------------------------------

### Install Dependencies and Run Dev Server

Source: https://github.com/microsoft/prompty/blob/main/web/CONTRIBUTING.md

Install project dependencies and start the local development server for the Prompty docs site. The site will be available at http://localhost:4321 with hot-reloading.

```bash
cd web
npm install
npm run dev
```

--------------------------------

### Quick Start: Initialize and Invoke Prompty Agent

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/implementation/rust.mdx

A basic example demonstrating how to register default providers, load a Prompty agent from a file, and invoke it with inputs within a Tokio async runtime.

```rust
use prompty;
use prompty_openai;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Register providers (once at startup)
    prompty::register_defaults();
    prompty_openai::register();

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

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

--------------------------------

### Few-Shot Prompting Example

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/how-to/cookbook.mdx

Guides model output format by embedding examples within instructions. Useful for classification or structured response tasks. The prompt includes system instructions, examples, and a user input variable.

```yaml
---
name: few-shot
model:
  id: gpt-4o-mini
  apiType: chat
inputs:
  - name: text
    kind: string
    default: The movie was absolutely fantastic and I loved every minute.
---
system:
Classify the sentiment of the text as positive, negative, or neutral.

Examples:
- "I love this product!" → positive
- "Terrible experience, never again." → negative
- "It was okay, nothing special." → neutral

user:
{{text}}
```

--------------------------------

### Python Environment Setup with uv

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/contributing/code-guidelines.mdx

Sets up a virtual environment and installs development dependencies for the Python runtime using uv. Ensure Python 3.11+ is installed.

```bash
cd runtime/python/prompty
uv venv
uv pip install -e ".[dev,all]"
```

--------------------------------

### Install LLM Provider Packages

Source: https://github.com/microsoft/prompty/blob/main/runtime/typescript/packages/core/README.md

Install a provider package for your chosen LLM. Examples include OpenAI, Azure AI Foundry, and Anthropic.

```bash
# OpenAI
npm install @prompty/openai

# Azure AI Foundry
npm install @prompty/foundry

# Anthropic
npm install @prompty/anthropic
```

--------------------------------

### Quick Start with Prompty.Foundry

Source: https://github.com/microsoft/prompty/blob/main/runtime/csharp/Prompty.Foundry/README.md

Initialize the Prompty builder with the Foundry provider and invoke a .prompty file. This setup registers necessary components for Azure OpenAI interactions.

```csharp
using Prompty.Core;
using Prompty.Foundry;

// One-time setup — registers renderers, parser, and Foundry provider
// (also registers the legacy "azure" alias automatically)
new PromptyBuilder()
    .AddFoundry();

// Run a .prompty file
var result = await Pipeline.InvokeAsync("chat.prompty", new Dictionary<string, object>
{
    ["question"] = "Explain quantum computing in simple terms"
});
```

--------------------------------

### Agent Tool Calling Example (Python)

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/how-to/agent-tool-calling.mdx

A Python implementation for agent tool calling. This example demonstrates the setup and execution of an agent that can utilize external tools.

```python
from prompty import TurnOptions
from prompty_openai import register as register_openai
from prompty import register_defaults, register_tool_handler
from serde_json import json

@tokio::main
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    register_defaults();
    register_openai();

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

    // Run the agent loop — tools are called automatically
    let result = prompty::turn_from_path(
        "agent.prompty",
        Some(&json!({ "question": "What's the weather in Seattle?" })),
        Some(TurnOptions { max_iterations: Some(10), ..Default::default() }),
    ).await?;
    println!("{result}");
    Ok(())
}

```

--------------------------------

### Install Prompty Python Packages

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/getting-started/index.mdx

Install the core Prompty library with specific renderers and providers using uv pip. Use `[all]` for a complete installation.

```bash
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]"
```

--------------------------------

### Install Python Prompty Extras

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/how-to/troubleshooting.mdx

Install optional dependencies for specific features like OpenAI or Jinja2. Use `[all]` to install all extras.

```bash
uv pip install "prompty[openai]"
```

```bash
uv pip install "prompty[jinja2]"
```

```bash
uv pip install "prompty[mustache]"
```

```bash
uv pip install "prompty[foundry]"
```

--------------------------------

### Install Prompty with Extras

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/implementation/python.mdx

Install Prompty with specific extras like jinja2 and openai for template rendering and LLM provider support. Use uv for environment management and installation.

```bash
uv pip install "prompty[jinja2,openai]"
```

--------------------------------

### Local Development of Prompty Trace Viewer

Source: https://github.com/microsoft/prompty/blob/main/vscode/prompty/packages/trace/README.md

Commands to install dependencies, start the development server, and build the trace viewer package for local development.

```bash
npm install
npm run dev
npm run build
```

--------------------------------

### Agent Tool Calling Example (C#)

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/how-to/agent-tool-calling.mdx

A C# implementation for agent tool calling. This example illustrates the setup and execution of an agent capable of using external tools.

```csharp
using Prompty.Core;
using Prompty.OpenAI;
using Serde.Json;

public class AgentToolCalling
{
    public static async Task Main(string[] args)
    {
        Prompty.Core.Prompty.RegisterDefaults();
        Prompty.OpenAI.Prompty.Register();

        // Register tool handlers
        Prompty.Core.Prompty.RegisterToolHandler("get_weather", async (args) =>
        {
            var city = args.GetProperty("city").GetString() ?? "unknown";
            return JsonSerializer.Serialize( $"72°F and sunny in {city}" );
        });

        // Run the agent loop — tools are called automatically
        var result = await Prompty.Core.Prompty.TurnFromPath(
            "agent.prompty",
            JsonSerializer.Serialize(new Dictionary<string, object?> { { "question", "What's the weather in Seattle?" } }),
            new TurnOptions { MaxIterations = 10 })
        );
        Console.WriteLine(result);
    }
}

```

--------------------------------

### Connection YAML Example

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/reference/Connection.md

An example of how to configure a Connection in YAML format.

```APIDOC
## YAML Example

This is an example of a Connection configuration in YAML format.

```yaml
kind: reference
authenticationMode: system
usageDescription: This will allow the agent to respond to an email on your behalf
```
```

--------------------------------

### Complete Prompty Example

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/getting-started/index.mdx

A full, tested example demonstrating how to invoke Prompty, suitable for direct copying and execution.

```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(())
}
```

--------------------------------

### Install @prompty/anthropic

Source: https://github.com/microsoft/prompty/blob/main/runtime/typescript/packages/anthropic/README.md

Install the Anthropic provider along with core Prompty and the Anthropic SDK.

```bash
npm install @prompty/core @prompty/anthropic @anthropic-ai/sdk
```

--------------------------------

### Quick Start: Invoke a Prompty

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/implementation/python.mdx

Execute a Prompty file directly using the `invoke` function. This is the simplest way to run a prompt with inputs and get a result.

```python
import prompty

# All-in-one execution
result = prompty.invoke("greeting.prompty", inputs={"name": "Jane"})
print(result)
```

--------------------------------

### Install @prompty/openai and Dependencies

Source: https://github.com/microsoft/prompty/blob/main/runtime/typescript/packages/openai/README.md

Install the OpenAI provider along with core Prompty packages and the official OpenAI client library.

```bash
npm install @prompty/core @prompty/openai openai
```

--------------------------------

### Install Prompty Extension from Marketplace

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/vscode/index.mdx

Install the Prompty VS Code extension from the VS Code Marketplace using the command line.

```bash
code --install-extension ms-toolsai.prompty
```

--------------------------------

### Tool YAML Example

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/reference/Tool.md

An example of how to configure a tool using YAML format.

```APIDOC
## Tool YAML Configuration Example

```yaml
name: my-tool
kind: function
description: A description of the tool
bindings:
  input: value
```
```

--------------------------------

### Install @prompty/foundry and Dependencies

Source: https://github.com/microsoft/prompty/blob/main/runtime/typescript/packages/foundry/README.md

Install the necessary packages for Prompty core, OpenAI, Foundry provider, and Azure identity.

```bash
npm install @prompty/core @prompty/openai @prompty/foundry openai @azure/identity
```

--------------------------------

### ModelOptions YAML Example

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/reference/ModelOptions.md

An example of how to configure ModelOptions using YAML.

```APIDOC
## ModelOptions YAML Example

### Description
This example demonstrates the structure for configuring ModelOptions in YAML format.

### Request Example
```yaml
frequencyPenalty: 0.5
maxOutputTokens: 2048
presencePenalty: 0.3
seed: 42
temperature: 0.7
topK: 40
topP: 0.9
stopSequences:
  - ""
  - "###"
allowMultipleToolCalls: true
additionalProperties:
  customProperty: value
  anotherProperty: anotherValue
```
```

--------------------------------

### Install OpenTelemetry Package (Python)

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/core-concepts/tracing.mdx

Install Prompty with the OpenTelemetry extra for Python.

```bash
pip install prompty[otel]
```

--------------------------------

### Install Prompty for Development

Source: https://github.com/microsoft/prompty/blob/main/runtime/python/prompty/README.md

Installs the Prompty package in editable mode with development and all extra dependencies.

```bash
# Install for development
uv pip install -e ".[dev,all]"
```

--------------------------------

### ToolCallStartPayload YAML Example

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/reference/ToolCallStartPayload.md

Example of the ToolCallStartPayload structure in YAML format. Use this to represent a tool call request.

```yaml
name: get_weather
arguments: '{"city": "Paris"}'
```

--------------------------------

### ReferenceConnection Yaml Example

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/reference/ReferenceConnection.md

Example of how to configure a ReferenceConnection in YAML format. This specifies the kind, name, and target resource for the connection.

```yaml
kind: reference
name: my-reference-connection
target: my-target-resource
```

--------------------------------

### Install Prompty TypeScript Packages

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/getting-started/index.mdx

Install the core Prompty library and the desired provider package using npm.

```bash
# 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
```

--------------------------------

### Run Python Documentation Tests

Source: https://github.com/microsoft/prompty/blob/main/web/CONTRIBUTING.md

Execute the pytest test suite for Python documentation examples. Ensure you have the necessary development dependencies installed for the Python examples.

```bash
# Python
cd web/docs-examples/python && pip install -e ".[dev]" && pytest
```

--------------------------------

### Install Prompty for Python

Source: https://github.com/microsoft/prompty/blob/main/README.md

Install the Prompty Python package with Jinja2 and OpenAI support to run `.prompty` files.

```bash
pip install "prompty[jinja2,openai]"

```

--------------------------------

### FilePart Yaml Example

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/reference/FilePart.md

Example of how to define a FilePart in YAML format, specifying the source URL and media type.

```yaml
source: https://example.com/document.pdf
mediaType: application/pdf
```

--------------------------------

### Build and Start Production Docs

Source: https://github.com/microsoft/prompty/blob/main/web/CONTRIBUTING.md

Build a production version of the docs site and start a local server to test it. This command sequence is used for final testing before deployment.

```bash
cd web
npm run build && npm run start
```

--------------------------------

### Quick Start with Prompty.OpenAI

Source: https://github.com/microsoft/prompty/blob/main/runtime/csharp/Prompty.OpenAI/README.md

Initialize the Prompty builder with the OpenAI provider and invoke a .prompty file for chat completions. Ensure the .prompty file has 'openai' specified as the provider in its frontmatter.

```csharp
using Prompty.Core;
using Prompty.OpenAI;

// One-time setup — registers renderers, parser, and OpenAI provider
new PromptyBuilder()
    .AddOpenAI();

// Run a .prompty file (provider: openai in frontmatter)
var result = await Pipeline.InvokeAsync("chat.prompty", new Dictionary<string, object>
{
    ["question"] = "Explain quantum computing in simple terms"
});

Console.WriteLine(result);
```

--------------------------------

### Install Prompty for TypeScript

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/tutorials/tool-calling-agent.mdx

Use this command to install the core Prompty library and the OpenAI integration for TypeScript projects.

```bash
npm install @prompty/core @prompty/openai
```

--------------------------------

### Build and Start Production Documentation

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/contributing/docs-guidelines.mdx

Use these commands to test a production build of the documentation. Check for errors and warnings before submitting a pull request.

```bash
npm run build
npm run start
```

--------------------------------

### AudioPart Yaml Example

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/reference/AudioPart.md

An example of how to define an AudioPart in YAML format, specifying the source URL and media type.

```APIDOC
## Yaml Example

```yaml
source: https://example.com/audio.wav
mediaType: audio/wav
```
```

--------------------------------

### Install All Prompty Features

Source: https://github.com/microsoft/prompty/blob/main/runtime/python/prompty/README.md

Installs the core Prompty library with all available renderers, providers, and OpenTelemetry support. Use this for comprehensive development or testing.

```bash
pip install prompty[all]
```

--------------------------------

### TypeScript Environment Setup

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/contributing/code-guidelines.mdx

Installs dependencies and builds the TypeScript monorepo. Requires Node.js version 18 or higher.

```bash
cd runtime/typescript
npm install
npm run build
```

--------------------------------

### Complete Prompty File Example

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/core-concepts/file-format.mdx

This example demonstrates a full .prompty file, showcasing all features including metadata, model configuration, inputs, outputs, tools, and a Jinja2 template.

```yaml
---
name: customer-support
displayName: Customer Support Agent
description: Answers customer questions using context from their account.
metadata:
  authors: [support-team]
  tags: [production, customer-facing]
  version: "2.1"

model:
  id: gpt-4o
  provider: foundry
  apiType: chat
  connection:
    kind: key
    endpoint: ${env:AZURE_OPENAI_ENDPOINT}
    apiKey: ${env:AZURE_OPENAI_API_KEY}
  options:
    temperature: 0.3
    maxOutputTokens: 2000

inputs:
  - name: customerName
    kind: string
    description: Full name of the customer
    required: true
  - name: question
    kind: string
    description: The customer's question
    required: true
  - name: orderHistory
    kind: array
    description: Recent orders for context
    default: []

outputs:
  - name: answer
    kind: string
  - name: sentiment
    kind: string
    enumValues: [positive, neutral, negative]

tools:
  - name: lookup_order
    kind: function
    description: Look up an order by ID
    parameters:
      - name: orderId
        kind: string
        required: true

template:
  format: jinja2
---
system:
You are a customer support agent for Contoso. Be helpful, concise,
and empathetic. Always greet the customer by name.

You have access to the following order history:
{% for order in orderHistory %}
- Order #{{ order.id }}: {{ order.status }} ({{ order.date }})
{% endfor %}

user:
Hi, my name is {{customerName}}. {{question}}

```

--------------------------------

### Jinja2 Length Filter Example

Source: https://github.com/microsoft/prompty/blob/main/spec/spec.md

Demonstrates the 'length' filter to get the number of items in a list or the length of a string in Jinja2.

```jinja2
{{list|length}}
```

--------------------------------

### Quick Start with Prompty.Anthropic

Source: https://github.com/microsoft/prompty/blob/main/runtime/csharp/Prompty.Anthropic/README.md

Initialize the Prompty builder with the Anthropic provider and invoke a .prompty file. Ensure the Prompty.Core and Prompty.Anthropic namespaces are included.

```csharp
using Prompty.Core;
using Prompty.Anthropic;

// One-time setup — registers renderers, parser, and Anthropic provider
new PromptyBuilder()
    .AddAnthropic();

// Run a .prompty file
var result = await Pipeline.InvokeAsync("chat.prompty", new Dictionary<string, object>
{
    ["question"] = "Explain quantum computing in simple terms"
});

Console.WriteLine(result);
```

--------------------------------

### Quick Start: Prompty Rust Runtime Usage

Source: https://github.com/microsoft/prompty/blob/main/runtime/rust/prompty/README.md

Demonstrates the basic workflow of loading a .prompty file, preparing messages, and running an LLM call using the Prompty Rust runtime. Includes registration of default components.

```rust
use prompty::{load, prepare, run, turn, register_defaults};

// Register built-in renderers and parsers
register_defaults();

// Load a .prompty file into a typed agent
let agent = load("path/to/prompt.prompty")?;

// Render template + parse role markers → Vec<Message>
let messages = prepare(&agent, Some(&inputs)).await?;

// Execute LLM call + process response
let result = run(&agent, &messages).await?;

// Or do it all in one shot with agent loop support
let result = turn(&agent, Some(&inputs), None).await?;
```

--------------------------------

### TypeScript Executor Implementation

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/how-to/custom-providers.mdx

Implement the execute method for a custom provider using TypeScript and the Fetch API. This example assumes a standard Prompty setup.

```typescript
// my-provider/executor.ts
import type { Executor } from "@prompty/core";
import type { Prompty, Message } from "@prompty/core";

export const myExecutor: Executor = {
  async execute(agent: Prompty, messages: Message[]): Promise<unknown> {
    const conn = agent.model.connection;
    const resp = await fetch(`${conn.endpoint}/v1/completions`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${conn.apiKey}`,
      },
      body: JSON.stringify({
        model: agent.model.id,
        messages: messages.map((m) => ({ role: m.role, content: m.text })),
      }),
    });
    return resp.json();
  },
  formatToolMessages() { return []; },
};

```

--------------------------------

### Install Prompty with Package Manager

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/migration.mdx

Use `pip` for v1 and `uv` for v2. Install extras like `jinja2` and `openai` for v2.

```bash
# v1
pip install prompty

# v2
uv pip install "prompty[jinja2,openai]"
```

--------------------------------

### Run TypeScript Documentation Tests

Source: https://github.com/microsoft/prompty/blob/main/web/CONTRIBUTING.md

Execute the npm test command for TypeScript documentation examples. This command installs dependencies and runs the vitest test suite.

```bash
# TypeScript
cd web/docs-examples/typescript && npm install && npm test
```

--------------------------------

### Install Dependencies

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/contributing/docs-guidelines.mdx

Run this command in the `web` directory to install necessary dependencies for the documentation site. Ensure you are using Node.js 18+.

```bash
npm install
```

--------------------------------

### Step-by-Step Usage of Prompty Core

Source: https://github.com/microsoft/prompty/blob/main/runtime/typescript/packages/core/README.md

Demonstrates the step-by-step process of loading, preparing, running, and processing a .prompty file. This involves parsing the file, rendering the template, calling the LLM, and extracting the result.

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

// 1. Load — parse .prompty file into a typed Prompty object
const agent = await load("./chat.prompty");

// 2. Prepare — render template + parse into messages
const messages = await prepare(agent, { name: "Alice" });

// 3. Run raw — call the LLM
const response = await run(agent, messages, { raw: true });

// 4. Process — extract the result
const result = await process(agent, response);
```

--------------------------------

### CompactionFailedPayload Example

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/reference/CompactionFailedPayload.md

An example of the CompactionFailedPayload in YAML format.

```APIDOC
## Request Example

```yaml
message: Summarization prompt exceeded context window
```
```

--------------------------------

### OpenAI Connection Example

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/vscode/connections.mdx

Example wizard input for configuring an OpenAI connection. Ensure the API key is valid and the endpoint is correct if not using the default.

```text
Connection name: my-openai
API key: sk-...
Endpoint: (leave default)
Model: gpt-4o-mini
```

--------------------------------

### Install Prompty C# Packages

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/getting-started/index.mdx

Add the Prompty core and provider packages to your C# project using the dotnet CLI. Use the `--prerelease` flag for alpha versions.

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

--------------------------------

### Install All Prompty Extras

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/implementation/python.mdx

Install Prompty with all available extras for full functionality, including all template renderers and providers. This is useful for comprehensive testing or development.

```bash
uv pip install "prompty[all]"
```

--------------------------------

### ToolDispatchResult Yaml Example

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/reference/ToolDispatchResult.md

An example of the ToolDispatchResult in YAML format.

```APIDOC
## Yaml Example

```yaml
toolCallId: call_abc123
name: get_weather
result:
  parts:
    - kind: text
      value: 72°F and sunny
```
```

--------------------------------

### Render Raw Code Example

Source: https://github.com/microsoft/prompty/blob/main/web/CONTRIBUTING.md

Import and render raw code examples from the docs-examples directory using the Code component. This ensures examples are testable and displayed correctly.

```jsx
import code from '../../../docs-examples/python/examples/load_prompt.py?raw';
import { Code } from 'astro:components';

<Code code={code} lang="python" />
```

--------------------------------

### TokenUsage Yaml Example

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/reference/TokenUsage.md

An example of how TokenUsage can be represented in YAML format.

```APIDOC
## TokenUsage Yaml Example

```yaml
promptTokens: 150
completionTokens: 42
totalTokens: 192
```
```

--------------------------------

### TextPart Yaml Example

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/reference/TextPart.md

An example of how a TextPart can be represented in YAML format.

```APIDOC
## Yaml Example

```yaml
value: Hello, world!
```
```

--------------------------------

### Install Prompty Core and Providers

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/implementation/rust.mdx

Install the core Prompty runtime and optional provider crates for different LLM services using Cargo.

```bash
cargo add prompty

# Add a provider (pick one or more)
cargo add prompty-openai      # OpenAI
cargo add prompty-foundry     # Azure OpenAI / Foundry
cargo add prompty-anthropic   # Anthropic Claude
```

--------------------------------

### Prompty File Structure Example

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/vscode/editing.mdx

This example demonstrates the structure of a .prompty file, including YAML frontmatter for configuration and a body with role markers and template expressions.

```yaml
---
# YAML frontmatter — agent configuration
name: greeting
model:
  id: gpt-4o
  provider: openai
  apiType: chat
  connection:
    kind: key
    endpoint: ${env:OPENAI_ENDPOINT}
    apiKey: ${env:OPENAI_API_KEY}
  options:
    temperature: 0.7
    maxOutputTokens: 256
inputs:
  firstName:
    kind: string
    default: Jane
  question:
    kind: string
    default: What is Prompty?
---
system:
You are a friendly assistant helping {{ firstName }}.

user:
{{ question }}

```

--------------------------------

### AnthropicWireMessage Role Example

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/reference/AnthropicWireMessage.md

Example of setting the 'role' property for an AnthropicWireMessage.

```yaml
role: user
```

--------------------------------

### Install Prompty Packages with Alpha Tag

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/implementation/typescript.mdx

Install Prompty packages with the `@alpha` tag for the latest pre-release versions. Ensure you install the core package along with the desired provider package.

```bash
npm install @prompty/core@alpha @prompty/openai@alpha

# Core + Microsoft Foundry
npm install @prompty/core@alpha @prompty/foundry@alpha

# Core + Anthropic
npm install @prompty/core@alpha @prompty/anthropic@alpha
```

--------------------------------

### Install OpenTelemetry Package (TypeScript)

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/core-concepts/tracing.mdx

Install the OpenTelemetry API package for TypeScript.

```bash
npm install @opentelemetry/api
```

--------------------------------

### Install Prompty C# Packages

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/implementation/csharp.mdx

Install the core Prompty package and any desired LLM provider packages using the .NET CLI.

```bash
dotnet add package Prompty.Core --prerelease

# Pick one or more providers
dotnet add package Prompty.OpenAI --prerelease
dotnet add package Prompty.Foundry --prerelease
dotnet add package Prompty.Anthropic --prerelease
```

--------------------------------

### Start Local Development Server

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/contributing/docs-guidelines.mdx

Execute this command from the `web` directory to launch the local development server. Changes will hot-reload, and you can view the site at http://localhost:4321.

```bash
npm run dev
```

--------------------------------

### Install OpenTelemetry Package (C#)

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/core-concepts/tracing.mdx

Add the Prompty.Core package for C#. OpenTelemetry support is included.

```bash
dotnet add package Prompty.Core --prerelease
# OTel support is built into Prompty.Core
```

--------------------------------

### TraceSpan YAML Example

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/reference/TraceSpan.md

An example of how a TraceSpan might be represented in YAML format.

```APIDOC
## TraceSpan YAML Example

### Description
An example YAML representation of a TraceSpan, showing its name, signature, and error fields.

### Request Example
```yaml
name: prompty.core.pipeline.run
signature: prompty.core.pipeline.run
error: Connection refused
```
```

--------------------------------

### Quick Start: Invoke Prompty File

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/implementation/csharp.mdx

Perform an all-in-one execution of a .prompty file with input parameters. Ensure providers are registered before invocation.

```csharp
using Prompty.Core;

// All-in-one execution
var result = await Pipeline.InvokeAsync("greeting.prompty",
    new Dictionary<string, object?> { ["name"] = "Jane" });

Console.WriteLine(result);
```

--------------------------------

### TokenUsage YAML Example

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/reference/TokenUsage.md

Example of how TokenUsage properties are represented in YAML format.

```yaml
promptTokens: 150
completionTokens: 42
totalTokens: 192
```

--------------------------------

### TraceFile Yaml Example

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/reference/TraceFile.md

Example YAML structure for a TraceFile, specifying runtime and version.

```yaml
runtime: python
version: 2.0.0
```

--------------------------------

### Load and Run a Prompty Agent in C#

Source: https://github.com/microsoft/prompty/blob/main/runtime/csharp/Prompty.Core/README.md

This C# code demonstrates how to initialize the Prompty builder, load a .prompty file, and execute the prompt with provided inputs. Ensure you have registered the necessary provider, such as OpenAI.

```csharp
using Prompty.Core;
using Prompty.OpenAI;

// One-time setup — registers renderers, parser, and providers
new PromptyBuilder()
    .AddOpenAI();

// Load, prepare messages, and execute
var agent = PromptyLoader.Load("chat.prompty");
var result = await Pipeline.InvokeAsync(agent, new Dictionary<string, object>
{
    ["question"] = "What is the meaning of life?"
});

Console.WriteLine(result);

```

--------------------------------

### ToolContext Metadata Example

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/reference/ToolContext.md

Example of how to define metadata within the ToolContext, such as a user ID.

```yaml
metadata:
  userId: user-123
```

--------------------------------

### AnthropicToolResultBlock YAML Example

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/reference/AnthropicToolResultBlock.md

Example of how to structure a tool result content block for Anthropic.

```yaml
tool_use_id: toolu_01A09q90qw90lq917835lq9
content: 72°F and sunny in Paris
```

--------------------------------

### Install Prompty.Core Package

Source: https://github.com/microsoft/prompty/blob/main/runtime/csharp/Prompty.Core/README.md

Add the Prompty.Core package to your project using the .NET CLI. You will also need to add at least one provider package for specific LLM services.

```bash
dotnet add package Prompty.Core

```

```bash
dotnet add package Prompty.OpenAI      # OpenAI
dotnet add package Prompty.Foundry     # Azure OpenAI / Microsoft Foundry
dotnet add package Prompty.Anthropic   # Anthropic Claude

```

--------------------------------

### Install Prompty.OpenAI Package

Source: https://github.com/microsoft/prompty/blob/main/runtime/csharp/Prompty.OpenAI/README.md

Add the Prompty.Core and Prompty.OpenAI NuGet packages to your C# project.

```bash
dotnet add package Prompty.Core
dotnet add package Prompty.OpenAI
```

--------------------------------

### Install TypeScript Prompty Package

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/how-to/troubleshooting.mdx

Install the necessary npm packages for Prompty in a TypeScript project.

```bash
npm install @prompty/openai
```

--------------------------------

### Example connections.json Configuration

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/vscode/connections.mdx

This JSON file defines connection profiles for LLM providers. Each key is a connection name, and 'isDefault' specifies the default connection for a provider.

```json
{
  "openai-dev": {
    "provider": "openai",
    "endpoint": "https://api.openai.com/v1",
    "isDefault": true
  },
  "azure-prod": {
    "provider": "foundry",
    "endpoint": "https://my-resource.services.ai.azure.com/api/projects/my-project",
    "isDefault": false
  }
}
```

--------------------------------

### ToolResult Yaml Example

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/reference/ToolResult.md

Example of how a ToolResult can be represented in YAML format, showing a text part.

```yaml
parts:
  - kind: text
    value: 72°F and sunny
```

--------------------------------

### Install Prompty with OpenAI Support

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/how-to/openai.mdx

Install the Prompty package with OpenAI integration for your specific language. Ensure you have an OpenAI API key.

```bash
uv pip install "prompty[jinja2,openai]"
```

```bash
npm install @prompty/core @prompty/openai
```

```bash
dotnet add package Prompty.Core --prerelease
dotnet add package Prompty.OpenAI --prerelease
```

```bash
cargo add prompty prompty-openai
```

--------------------------------

### ToolChunk YAML Example

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/reference/ToolChunk.md

Example of a ToolChunk in YAML format, illustrating the structure of a tool call.

```yaml
toolCall:
  id: call_abc123
  name: get_weather
  arguments: '{"city": "Paris"}'
```

--------------------------------

### TextPart Yaml Example

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/reference/TextPart.md

Example of how to define a TextPart in YAML format, specifying its text value.

```yaml
value: Hello, world!
```

--------------------------------

### Combine Runtime Controls in C#

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/agentic-concepts/runtime-controls.mdx

An example in C# showing how to configure runtime controls for an agent turn, including event callbacks, cancellation tokens, context budget, compaction strategies, guardrails, steering, and parallel tool execution.

```csharp
var result = await Pipeline.TurnAsync(
    agent,
    inputs,
    tools: tools,
    onEvent: (eventType, data) => Console.WriteLine(eventType),
    cancellationToken: cancellationToken,
    contextBudget: 50_000,
    compaction: CompactionStrategy.FromFunction(SummarizeLocallyAsync),
    guardrails: new Guardrails(
        input: CheckInput,
        output: CheckOutput,
        tool: CheckTool),
    steering: steering,
    parallelToolCalls: true,
    maxLlmRetries: 3
);
```

--------------------------------

### Agent Tool Calling Example (Rust)

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/how-to/agent-tool-calling.mdx

A Rust implementation for agent tool calling. This example demonstrates setting up and running an agent that can utilize external tools.

```rust
use serde_json::json;
use prompty::TurnOptions;

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

    // Register tool handlers
    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 and sunny in {city}")))
        })
    });

    // Run the agent loop — tools are called automatically
    let result = prompty::turn_from_path(
        "agent.prompty",
        Some(&json!({ "question": "What's the weather in Seattle?" })),
        Some(TurnOptions { max_iterations: Some(10), ..Default::default() }),
    ).await?;
    println!("{result}");
    Ok(())
}

```

--------------------------------

### TextChunk YAML Example

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/reference/TextChunk.md

Example of how a TextChunk can be represented in YAML format, showing its 'value' property.

```yaml
value: Hello
```

--------------------------------

### StatusEventPayload YAML Example

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/reference/StatusEventPayload.md

Example of a StatusEventPayload in YAML format. Use this to represent status messages.

```yaml
message: Starting iteration 3
```

--------------------------------

### GuardrailError Yaml Example

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/reference/GuardrailError.md

Example of a GuardrailError in YAML format, specifying the reason for content denial.

```yaml
reason: Content contains personally identifiable information

```

--------------------------------

### ErrorChunk YAML Example

Source: https://github.com/microsoft/prompty/blob/main/web/src/content/docs/reference/ErrorChunk.md

Example of how an ErrorChunk is represented in YAML format, showing the error message.

```yaml
message: Rate limit exceeded
```