Principle:Microsoft Agent framework YAML Agent Schema

Property	Value
Principle Name	YAML Agent Schema
SDK	Microsoft Agent Framework
Repository	Microsoft Agent Framework
Documentation	Agent Samples
Source Reference	`python/packages/declarative/agent_framework_declarative/_models.py:L815-856`
Domains	Declarative_Systems, Agent_Architecture

Overview

The YAML Agent Schema principle describes the declarative approach to defining AI agents in the Microsoft Agent Framework using YAML configuration files. Rather than writing imperative Python or C# code to construct agents, developers author structured YAML documents that specify an agent's identity, behavior, model configuration, tools, and output constraints. A runtime parser then materializes these declarations into executable agent objects. This separation of agent definition from implementation code enables non-developers to configure agents, promotes version-controlled configuration, and supports multi-language runtimes from a single schema.

Description

In the Microsoft Agent Framework, a declarative agent is specified by a YAML file whose top-level kind field identifies the agent type. The primary agent kind is Prompt, which maps to the PromptAgent class in the Python SDK. The YAML document acts as a complete, self-contained specification that a factory method can deserialize into a live agent instance.

Agent Kind

The kind field serves as a discriminator. When the framework's AgentDefinition.from_dict method encounters kind: Prompt (or kind: Agent), it dispatches to PromptAgent construction. This pattern allows the schema to be extended with additional agent kinds in the future without changing the deserialization entry point.

Core Fields

Every Prompt agent YAML supports the following top-level fields:

Field	Type	Required	Description
`kind`	string	Yes	Agent type discriminator. Must be `Prompt` or `Agent`.
`name`	string	No	The programmatic identifier of the agent.
`displayName`	string	No	A human-readable name for the agent.
`description`	string	No	A short summary of the agent's purpose.
`instructions`	string	No	The system prompt that guides the agent's behavior. Supports PowerFx expressions prefixed with `=`.
`additionalInstructions`	string	No	Supplementary instructions appended to the primary instructions.
`model`	object	No	Model configuration block specifying provider, API type, connection, and options.
`tools`	list	No	Tool definitions the agent can invoke during execution.
`outputSchema`	object	No	Schema constraining the agent's structured JSON output.
`inputSchema`	object	No	Schema constraining the input the agent accepts.
`metadata`	object	No	Arbitrary key-value metadata (e.g., authors, tags).
`template`	object	No	Template configuration for format and parser settings.

Model Configuration

The model block configures which LLM backs the agent and how it connects:

Sub-field	Type	Description
`id`	string	The model deployment name or identifier (e.g., `gpt-4o`, `gpt-4.1-mini`). Supports PowerFx expressions such as `=Env.AZURE_OPENAI_DEPLOYMENT_NAME`.
`provider`	string	The model provider: `AzureOpenAI`, `OpenAI`, or `Anthropic`.
`apiType`	string	The API surface to use: `Responses`, `Chat`, or `Assistants`.
`connection`	object	Connection credentials. Kinds include `key` (API key), `reference`, `remote` (endpoint-based), and `anonymous`.
`options`	object	Generation parameters: `temperature`, `topP`, `topK`, `maxOutputTokens`, `frequencyPenalty`, `presencePenalty`, `seed`, `stopSequences`, `allowMultipleToolCalls`.

Tool Types

The tools list supports multiple tool kinds, each identified by a kind discriminator:

Tool Kind	Class	Description
`function`	`FunctionTool`	A locally bound Python function with typed parameters and bindings.
`web_search`	`WebSearchTool`	A web search capability with optional connection and options.
`file_search`	`FileSearchTool`	A vector store file search tool with configurable ranker, score threshold, and filters.
`mcp`	`McpTool`	A Model Context Protocol server tool with connection, approval mode, and allowed tool filtering.
`code_interpreter`	`CodeInterpreterTool`	A sandboxed code execution environment with optional file IDs.
`openapi`	`OpenApiTool`	A tool backed by an OpenAPI specification with connection credentials.
`custom`	`CustomTool`	A custom tool with provider-specific connection and options.

Output Schema

The outputSchema block constrains the agent's response to a specific JSON structure. Properties use either kind (e.g., kind: string) or type (e.g., type: string) to declare their data type, along with required, description, default, and enum sub-fields. This enables the framework to generate a JSON Schema and enforce structured output from the LLM.

PowerFx Expressions

String values prefixed with = are evaluated as PowerFx expressions at parse time when the PowerFx engine is available. This enables dynamic configuration such as =Env.AZURE_OPENAI_DEPLOYMENT_NAME to resolve environment variables, or =Env.OPENAI_API_KEY for secrets. When safe_mode is enabled (the default), environment variable access is restricted.

Theoretical Basis

The YAML Agent Schema principle draws from several architectural patterns:

Declarative Configuration: Agents are described as data rather than constructed through imperative API calls. This follows the infrastructure-as-code philosophy where the desired state is declared and the runtime reconciles it.
Schema-Driven Dispatch: The kind field acts as a discriminator for polymorphic deserialization, a pattern common in Kubernetes resource definitions and other YAML-based configuration systems.
Separation of Concerns: Agent definition (what the agent is) is separated from agent implementation (how it runs). Domain experts can author YAML files without understanding the underlying SDK classes.
Convention over Configuration: Sensible defaults for most fields mean a minimal YAML file (just kind, name, and instructions) produces a working agent.

Usage

Minimal Agent

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

Agent with Azure OpenAI Provider

kind: Prompt
name: Assistant
description: Helpful assistant
instructions: You are a helpful assistant.
model:
    id: gpt-4o-mini
    provider: AzureOpenAI
    apiType: Responses
    options:
        temperature: 0.9
        topP: 0.95

Agent with Function Tool

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.
          required: false
          enum:
            - celsius
            - fahrenheit

Agent with Structured Output

kind: Prompt
name: Assistant
description: Helpful assistant
instructions: You return your answers in a JSON format.
model:
    id: gpt-4o-mini
    provider: AzureOpenAI
    apiType: Chat
    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.

Agent with OpenAI Provider and API Key Connection

kind: Prompt
name: Assistant
description: Helpful assistant
instructions: You are a helpful assistant.
model:
    id: =Env.OPENAI_MODEL
    provider: OpenAI
    apiType: Chat
    options:
        temperature: 0.9
        topP: 0.95
    connection:
        kind: key
        key: =Env.OPENAI_API_KEY

Agent with Remote Connection (Azure Foundry)

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

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment