Agent

An Agent is the root model produced from a .prompty markdown file for LLM prompts. The frontmatter defines structured metadata including model configuration, input/output schemas, tools, and template settings. The markdown body becomes the instructions.

This is the single root type for the Prompty schema — there is no abstract base class or kind discriminator. A .prompty file always produces an Agent instance.

Runtime loaders may resolve frontmatter references such as ${env:VAR} and ${file:relative/path}. File references must be treated as a host-controlled capability: by default they are scoped to the containing .prompty file’s directory tree after canonicalization, and any additional allowed roots must be supplied by the host application’s load options rather than frontmatter.

Class Diagram

---
title: Agent
config:
  look: handDrawn
  theme: colorful
  class:
    hideEmptyMembersBox: true
---
classDiagram
    class Agent {
        +string name
        +string displayName
        +string description
        +dictionary metadata
        +Property[] inputs
        +Property[] outputs
        +Model model
        +Tool[] tools
        +Template template
        +string instructions
    }
    class Property {
        +string name
        +string kind
        +string description
        +boolean required
        +boolean nullable
        +unknown default
        +unknown example
        +unknown[] enumValues
    }
    Agent *-- Property
    class Model {
        +string id
        +string provider
        +string apiType
        +Connection connection
        +ModelOptions options
    }
    Agent *-- Model
    class Tool {
      <<abstract>>
        +string name
        +string kind
        +string description
        +Binding[] bindings
    }
    Agent *-- Tool
    class Template {
        +FormatConfig format
        +ParserConfig parser
    }
    Agent *-- Template

Markdown Example

---
name: basic-prompt
displayName: Basic Prompt
description: A basic prompt that uses the GPT-3 chat API to answer questions
metadata:
  authors:
    - sethjuarez
    - jietong
  tags:
    - example
    - prompt
inputs:
  firstName:
    kind: string
    default: Jane
  lastName:
    kind: string
    default: Doe
  question:
    kind: string
    default: What is the meaning of life?
outputs:
  answer:
    kind: string
    description: The answer to the user's question.
model:
  id: gpt-35-turbo
  connection:
    kind: key
    endpoint: https://{your-custom-endpoint}.openai.azure.com/
    apiKey: "{your-api-key}"
tools:
  - name: getCurrentWeather
    kind: function
    description: Get the current weather in a given location
    parameters:
      location:
        kind: string
        description: The city and state, e.g. San Francisco, CA
      unit:
        kind: string
        description: The unit of temperature, e.g. Celsius or Fahrenheit
template:
  format: mustache
  parser: prompty
---
system:
You are an AI assistant who helps people find information.
As the assistant, you answer questions briefly, succinctly,
and in a personable manner using markdown and even add some
personal flair with appropriate emojis.
# Customer
You are helping {{firstName}} {{lastName}} to find answers to
their questions. Use their name to address them in your responses.
user:
{{question}}

Yaml Example

name: basic-prompt
displayName: Basic Prompt
description: A basic prompt that uses the GPT-3 chat API to answer questions
metadata:
  authors:
    - sethjuarez
    - jietong
  tags:
    - example
    - prompt
inputs:
  firstName:
    kind: string
    default: Jane
  lastName:
    kind: string
    default: Doe
  question:
    kind: string
    default: What is the meaning of life?
outputs:
  answer:
    kind: string
    description: The answer to the user's question.
model:
  id: gpt-35-turbo
  connection:
    kind: key
    endpoint: https://{your-custom-endpoint}.openai.azure.com/
    apiKey: "{your-api-key}"
tools:
  - name: getCurrentWeather
    kind: function
    description: Get the current weather in a given location
    parameters:
      location:
        kind: string
        description: The city and state, e.g. San Francisco, CA
      unit:
        kind: string
        description: The unit of temperature, e.g. Celsius or Fahrenheit
template:
  format: mustache
  parser: prompty
instructions: |-
  system:
  You are an AI assistant who helps people find information.
  As the assistant, you answer questions briefly, succinctly,
  and in a personable manner using markdown and even add some
  personal flair with appropriate emojis.
  # Customer
  You are helping {{firstName}} {{lastName}} to find answers to
  their questions. Use their name to address them in your responses.
  user:
  {{question}}

Properties

Name	Type	Description
name	string	Human-readable name of the prompt
displayName	string	Display name for UI purposes
description	string	Description of the prompt’s purpose
metadata	dictionary	Additional metadata including authors, tags, and other arbitrary properties. Values may be explicit null.
inputs	Property[]	Input parameters that participate in template rendering(Related Types: ArrayProperty, ObjectProperty, UnionProperty)
outputs	Property[]	Expected output format and structure
model	Model	AI model configuration(Related Types: OpenAIModel, AzureModel, CustomModel)
tools	Tool[]	Tools available for extended functionality(Related Types: FunctionTool, CustomTool, McpTool, OpenApiTool)
template	Template	Template configuration for prompt rendering
instructions	string	Clear directions on what the prompt should do. In .prompty files, this comes from the markdown body.

Composed Types

The following types are composed within Agent:

• Property
• Model
• Tool
• Template