Jump to content

Connect SuperML | Leeroopedia MCP: Equip your AI agents with best practices, code verification, and debugging knowledge. Powered by Leeroo — building Organizational Superintelligence. Contact us at founders@leeroo.com.

Principle:Microsoft Agent framework YAML Agent Schema

From Leeroopedia
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
Retrieved from "https://leeroopedia.com/index.php?title=Principle:Microsoft_Agent_framework_YAML_Agent_Schema&oldid=26552"