Implementation:Microsoft Agent framework YAML Agent Definition Schema

Property	Value
Implementation Name	YAML Agent Definition Schema
SDK	Microsoft Agent Framework
Repository	Microsoft Agent Framework
Source File	`python/packages/declarative/agent_framework_declarative/_models.py`
Line Range	L815-856
Example File	`agent-samples/chatclient/GetWeather.yaml`
Type	Pattern Doc (user-defined YAML configuration)
Domains	Declarative_Systems, Agent_Architecture

Overview

The YAML Agent Definition Schema is the implementation of declarative agent configuration in the Microsoft Agent Framework. Agents are defined entirely through YAML files that the framework's PromptAgent class (lines 815-856 of _models.py) deserializes into executable agent objects. This pattern doc covers the full YAML schema, its mapping to the Python model hierarchy, and practical configuration examples for different providers, tool types, and output constraints.

Code Reference

Source Location

Property	Value
File	`python/packages/declarative/agent_framework_declarative/_models.py`
Class	`PromptAgent`
Base Class	`AgentDefinition`
Lines	815-856
Dispatch	`AgentDefinition.from_dict` routes `kind: Prompt` and `kind: Agent` to `PromptAgent`

PromptAgent Constructor Signature

class PromptAgent(AgentDefinition):
    """Object representing a prompt agent specification."""

    def __init__(
        self,
        kind: str = "Prompt",
        name: str | None = None,
        displayName: str | None = None,
        description: str | None = None,
        metadata: dict[str, Any] | None = None,
        inputSchema: PropertySchema | None = None,
        outputSchema: PropertySchema | None = None,
        model: Model | dict[str, Any] | None = None,
        tools: list[Tool] | None = None,
        template: Template | dict[str, Any] | None = None,
        instructions: str | None = None,
        additionalInstructions: str | None = None,
    ) -> None:
        ...

Supporting Model Classes

The YAML fields map to the following Python model hierarchy:

YAML Block	Python Class	Source Lines	Key Fields
`model`	`Model`	L404-423	`id`, `provider`, `apiType`, `connection`, `options`
`model.options`	`ModelOptions`	L373-401	`temperature`, `topP`, `topK`, `maxOutputTokens`, `frequencyPenalty`, `presencePenalty`, `seed`, `stopSequences`, `allowMultipleToolCalls`
`model.connection`	`Connection` subclasses	L238-370	`kind` (`reference`, `remote`, `key`, `anonymous`), `endpoint`, `apiKey`
`tools[*]`	`Tool` subclasses	L513-812	`kind`, `name`, `description`, `bindings`, plus kind-specific fields
`outputSchema`	`PropertySchema`	L189-232	`properties`, `examples`, `strict`
`outputSchema.properties[*]`	`Property`	L82-101	`name`, `kind`/`type`, `description`, `required`, `default`, `enum`
`template`	`Template`	L452-465	`format`, `parser`

YAML Schema Reference

Complete Schema Structure

kind: Prompt                       # Required. "Prompt" or "Agent".
name: <string>                     # Agent identifier.
displayName: <string>              # Human-readable agent name.
description: <string>              # Short description of the agent.
instructions: <string>             # System prompt. Supports PowerFx (=Env.VAR).
additionalInstructions: <string>   # Supplementary instructions appended to the primary.
metadata:                          # Arbitrary key-value metadata.
    authors:
      - <string>
    tags:
      - <string>

model:
    id: <string>                   # Model deployment name (e.g., gpt-4o, gpt-4.1-mini).
    provider: <string>             # AzureOpenAI | OpenAI | Anthropic
    apiType: <string>              # Responses | Chat | Assistants
    connection:
        kind: <string>             # key | reference | remote | anonymous
        key: <string>              # API key (for kind: key). Supports PowerFx.
        apiKey: <string>           # Alias for key.
        endpoint: <string>         # Endpoint URL (for kind: remote).
        name: <string>             # Reference name (for kind: reference).
        target: <string>           # Reference target (for kind: reference).
    options:
        temperature: <float>       # Sampling temperature (0.0-2.0).
        topP: <float>              # Nucleus sampling threshold.
        topK: <int>                # Top-k sampling.
        maxOutputTokens: <int>     # Maximum tokens in the response.
        frequencyPenalty: <float>   # Penalize repeated tokens.
        presencePenalty: <float>    # Penalize tokens already present.
        seed: <int>                # Random seed for reproducibility.
        stopSequences:             # Stop generation at these sequences.
          - <string>
        allowMultipleToolCalls: <bool>  # Allow parallel tool invocations.

tools:                             # List of tool definitions.
  - kind: function                 # Function tool.
    name: <string>
    description: <string>
    bindings:
      <binding_name>: <function_ref>
    parameters:
      properties:
        <param_name>:
          kind: <string>           # string | integer | number | boolean | array | object
          description: <string>
          required: <bool>
          default: <any>
          enum:
            - <value>

  - kind: web_search                # Web search tool.
    name: <string>
    description: <string>
    connection: { ... }
    options: { ... }

  - kind: file_search               # File search tool.
    name: <string>
    description: <string>
    vectorStoreIds:
      - <string>
    maximumResultCount: <int>
    ranker: <string>
    scoreThreshold: <float>
    filters: { ... }

  - kind: mcp                       # Model Context Protocol tool.
    name: <string>
    description: <string>
    serverName: <string>
    serverDescription: <string>
    url: <string>
    allowedTools:
      - <string>
    approvalMode:
        kind: <string>             # always | never | specify
        alwaysRequireApprovalTools:
          - <string>
        neverRequireApprovalTools:
          - <string>
    connection: { ... }

  - kind: code_interpreter           # Code interpreter tool.
    name: <string>
    description: <string>
    fileIds:
      - <string>

  - kind: openapi                    # OpenAPI-backed tool.
    name: <string>
    description: <string>
    specification: <string>          # Path or URL to OpenAPI spec.
    connection: { ... }

outputSchema:                       # Structured output constraint.
    strict: <bool>                  # Enforce strict schema validation.
    examples:
      - { ... }
    properties:
        <property_name>:
            type: <string>         # string | integer | number | boolean
            kind: <string>         # Alternative to type.
            description: <string>
            required: <bool>
            default: <any>
            enum:
              - <value>

inputSchema:                        # Structured input constraint.
    properties:
        <property_name>:
            type: <string>
            description: <string>
            required: <bool>

template:
    format:
        kind: <string>
        strict: <bool>
        options: { ... }
    parser:
        kind: <string>
        options: { ... }

Tool Type Details

Function Tool

Function tools bind YAML-declared parameters to Python functions at runtime through the bindings map. The parameters.properties block defines the function's input schema, which the LLM uses to generate structured tool-call arguments.

tools:
  - kind: function
    name: GetWeather
    description: Get the weather for a given location.
    bindings:
      get_weather: get_weather
    parameters:
      properties:
        location:
          kind: string
          description: The city and state, e.g. San Francisco, CA
          required: true
        unit:
          kind: string
          description: The unit of temperature.
          required: false
          enum:
            - celsius
            - fahrenheit

MCP Tool

MCP tools connect to Model Context Protocol servers. The approvalMode controls whether tool invocations require human approval.

tools:
  - kind: mcp
    name: LearnSearch
    description: Search Microsoft Learn documentation.
    serverName: ms-learn-mcp
    url: https://mcp.example.com/learn
    approvalMode:
        kind: specify
        alwaysRequireApprovalTools:
          - delete_resource
        neverRequireApprovalTools:
          - search_docs
    connection:
        kind: remote
        endpoint: https://mcp.example.com

OpenAPI Tool

OpenAPI tools are backed by an OpenAPI specification file or URL. The framework generates tool definitions from the API endpoints.

tools:
  - kind: openapi
    name: PetStore
    description: Interact with the pet store API.
    specification: ./petstore-openapi.yaml
    connection:
        kind: key
        key: =Env.PETSTORE_API_KEY
        endpoint: https://api.petstore.example.com

Connection Types

The connection block supports four kinds:

Kind	Python Class	Key Fields	Use Case
`key`	`ApiKeyConnection`	`key`/`apiKey`, `endpoint`	Direct API key authentication (OpenAI, third-party APIs).
`reference`	`ReferenceConnection`	`name`, `target`	Reference to a named connection managed externally.
`remote`	`RemoteConnection`	`name`, `endpoint`	Endpoint-based connection (Azure Foundry projects).
`anonymous`	`AnonymousConnection`	`endpoint`	No authentication required.

Usage Examples

Example 1: Minimal Chat Agent

The simplest possible agent with default model settings:

kind: Prompt
name: Assistant
description: Helpful assistant
instructions: You are a helpful assistant.
model:
    options:
        temperature: 0.9
        topP: 0.95

Example 2: Azure OpenAI with Responses API

An agent targeting Azure OpenAI's Responses API with structured output:

kind: Prompt
name: Assistant
description: Helpful assistant
instructions: >
    You are a helpful assistant. You answer questions in the language
    specified by the user. You return your answers in a JSON format.
model:
    id: gpt-4o-mini
    provider: AzureOpenAI
    apiType: Responses
    options:
        temperature: 0.9
        topP: 0.95
outputSchema:
    properties:
        language:
            type: string
            required: true
            description: The language of the answer.
        answer:
            type: string
            required: true
            description: The answer text.

Example 3: OpenAI with API Key and Assistants API

An agent using OpenAI directly with explicit API key authentication and the Assistants API:

kind: Prompt
name: Assistant
description: Helpful assistant
instructions: You are a helpful assistant.
model:
    id: gpt-4.1-mini
    provider: OpenAI
    apiType: Assistants
    options:
        temperature: 0.9
        topP: 0.95
    connection:
        kind: ApiKey
        key: =Env.OPENAI_API_KEY
outputSchema:
    properties:
        language:
            type: string
            required: true
            description: The language of the answer.
        answer:
            type: string
            required: true
            description: The answer text.

Example 4: Function Tool Agent (GetWeather)

From agent-samples/chatclient/GetWeather.yaml, a complete agent with a function tool for weather lookups:

kind: Prompt
name: Assistant
description: Helpful assistant
instructions: You are a helpful assistant. You answer questions using the tools provided.
model:
    options:
        temperature: 0.9
        topP: 0.95
        allowMultipleToolCalls: true
        chatToolMode: auto
tools:
  - kind: function
    name: GetWeather
    description: Get the weather for a given location.
    bindings:
      get_weather: get_weather
    parameters:
      properties:
        location:
          kind: string
          description: The city and state, e.g. San Francisco, CA
          required: true
        unit:
          kind: string
          description: The unit of temperature. Possible values are 'celsius' and 'fahrenheit'.
          required: false
          enum:
            - celsius
            - fahrenheit

Example 5: Azure Foundry Remote Connection

An agent connecting through Azure Foundry's project endpoint using a remote connection:

kind: Prompt
name: Assistant
description: Helpful assistant
instructions: You are a helpful assistant.
model:
    id: gpt-4.1-mini
    options:
        temperature: 0.9
        topP: 0.95
    connection:
        kind: Remote
        endpoint: =Env.AZURE_FOUNDRY_PROJECT_ENDPOINT
outputSchema:
    properties:
        language:
            type: string
            required: true
            description: The language of the answer.
        answer:
            type: string
            required: true
            description: The answer text.

Example 6: Agent with Full Structured Output

From agent-samples/chatclient/Assistant.yaml, an agent enforcing structured JSON responses:

kind: Prompt
name: Assistant
description: Helpful assistant
instructions: >
    You are a helpful assistant. You answer questions in the language
    specified by the user. You return your answers in a JSON format.
model:
    options:
        temperature: 0.9
        topP: 0.95
outputSchema:
    properties:
        language:
            type: string
            required: true
            description: The language of the answer.
        answer:
            type: string
            required: true
            description: The answer text.

Deserialization Flow

The YAML-to-object deserialization follows this chain:

A YAML file is loaded and parsed into a Python dictionary.
AgentDefinition.from_dict() reads the kind field.
For kind: Prompt or kind: Agent, it dispatches to PromptAgent.from_dict().
PromptAgent.__init__ converts nested dictionaries:
- model dict is converted via Model.from_dict(), which in turn converts connection via Connection.from_dict() and options via ModelOptions.from_dict().
- Each item in tools is converted via Tool.from_dict(), which dispatches to the appropriate subclass (FunctionTool, McpTool, etc.) based on kind.
- outputSchema and inputSchema are converted via PropertySchema.from_dict().
- template is converted via Template.from_dict().
String values starting with = are evaluated as PowerFx expressions through _try_powerfx_eval().
The resulting PromptAgent instance is ready for execution.

Related Pages

Principle:Microsoft_Agent_framework_YAML_Agent_Schema

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment