How Prompty Works
Prompty introduces a structured markdown-based file format for defining and managing large language model (LLM) prompts. Each .prompty file combines YAML frontmatter with a markdown body, creating a single, portable asset. The YAML frontmatter section allows developers to specify model configurations, inputs, tools, templates, and agentic controls. This separation of structured metadata from the human-readable prompt body ensures clarity and maintainability. The format is designed to be extensible, accommodating future advancements in AI while preserving backward compatibility.
The core of Prompty’s functionality revolves around a four-stage pipeline: render, parse, execute, and process. During the render stage, the prompt is prepared for execution, including the extraction of content and parsing of structured outputs. The execution stage involves sending the prompt to an LLM API, such as OpenAI, Anthropic, or Microsoft Foundry, while the process stage handles streaming responses and managing conversation state. This pipeline ensures that prompts are executed consistently across different environments, including VS Code and standalone runtimes in Python, TypeScript, C#, and Rust.
Prompty v2 introduces an additional layer of functionality with the turn() method, enabling agentic loops around the same prompt asset. This feature allows developers to define tools in the YAML frontmatter and provide handlers from host code, facilitating governed conversations and tool usage. The system supports runtime controls for guardrails, steering, cancellation, and retries, ensuring robust and controlled interactions with LLMs. Context budgets and memory-aware conversation turns further enhance the ability to manage long-running dialogues efficiently.
Every execution in Prompty generates a detailed trace, capturing messages sent, tokens consumed, latency metrics, and raw API responses. This trace data is accessible via a built-in trace viewer in the VS Code extension, offering conversation, timing, and raw views. Developers can decorate their own functions with @trace to achieve end-to-end visibility into prompt execution. The tracing system is pluggable, supporting backends such as console output, file logging, or integration with OpenTelemetry for advanced observability.
A single .prompty file can be executed across multiple runtimes—VS Code, Python, C#, or TypeScript—without requiring modifications.
Connection management is built into Prompty, with native support for major LLM providers like OpenAI, Anthropic, and Microsoft Foundry. Developers can switch between providers or configure custom endpoints directly within the YAML frontmatter.
Key Features & Capabilities
- Structured Prompt Definition: Prompts are defined in a hybrid markdown-YAML format, where YAML frontmatter handles metadata (model config, inputs, tools) and markdown provides the human-readable prompt body.
- Four-Stage Execution Pipeline: Prompts are processed through render, parse, execute, and process stages, ensuring consistency and reproducibility. The pipeline supports streaming responses and dynamic conversation management.
- Agentic Looping with turn(): Version 2 introduces agentic capabilities, allowing prompts to invoke tools or continue conversations programmatically. Tools are defined in the YAML frontmatter, and their execution is handled by host code, enabling complex workflows without hardcoding logic into prompts.
- Comprehensive Tracing and Debugging: Every prompt execution generates a trace log, including API calls, token usage, latency, and raw responses. The VS Code extension provides a trace viewer with conversation, timing, and raw data views, accelerating debugging. Custom functions can be traced using the @trace decorator for full observability.
- Multi-Runtime Support: Prompty files are executable across Python, TypeScript, C#, and Rust runtimes, as well as within the VS Code extension.
- Pluggable Backends and Extensibility: Prompty supports custom executors for LLM APIs and pluggable tracing backends (console, files, OpenTelemetry). The format is open and designed to evolve with the AI ecosystem, accommodating future extensions or integrations.
- Runtime Controls and Guardrails: Developers can enforce guardrails such as context budgets, conversation compaction, and memory management to prevent runaway dialogues. Additional controls include steering, cancellation, and retry mechanisms for resilient prompt execution.
- Connection Management for Major Providers: Native support for OpenAI, Anthropic, and Microsoft Foundry simplifies provider switching or custom endpoint configurations. The YAML frontmatter allows dynamic specification of API endpoints and authentication methods.
- VS Code Integration: The Prompty VS Code extension serves as a dedicated workbench for prompt engineering. Features include real-time execution with F5, syntax highlighting for markdown and YAML, and an integrated trace viewer for immediate feedback during development.
Use Cases
Prompty is tailored for developers, data scientists, and AI engineers who require systematic prompt management, versioning, and debugging. Its structured format and tooling are particularly valuable in scenarios where prompts are treated as first-class assets—similar to code files—rather than ad-hoc strings.
- Prompt Development and Collaboration: Teams can define, version, and share prompts as .prompty files, ensuring consistency across projects. The VS Code extension facilitates collaborative editing with syntax highlighting, linting, and real-time execution, reducing miscommunication and errors.
- Debugging and Optimization: The built-in trace viewer allows developers to analyze prompt performance, token usage, and API latency in real time. By inspecting raw responses and conversation flows, teams can refine prompts for accuracy, cost efficiency, or compliance with guardrails.
- Agentic Workflows and Tool Integration: Prompty v2’s turn() method enables the creation of agentic systems where prompts dynamically invoke external tools or APIs.
- Multi-Provider and Hybrid Deployments: Organizations using multiple LLM providers (e.g., OpenAI for research, Microsoft Foundry for enterprise) can standardize on .prompty files. The format’s flexibility allows prompts to be executed across providers without rewriting, simplifying migration or A/B testing.
- Reproducible AI Experiments: Researchers and engineers can version-control prompts alongside code, ensuring experiments are reproducible. The trace logs serve as audit trails, documenting input-output pairs, hyperparameters, and environmental variables used during execution.
- Enterprise Guardrails and Compliance: Prompty’s runtime controls—such as context budgets, cancellation, and steering—help enforce organizational policies (e.g., avoiding sensitive data leaks or excessive costs). The structured format also simplifies compliance documentation by making prompt logic transparent and traceable.
- Education and Onboarding: The combination of markdown readability and YAML structure makes Prompty accessible to non-experts while offering depth for advanced users.