This folder contains sample code demonstrating how to use the Microsoft Agent Framework Declarative package to create agents from YAML specifications. The declarative approach allows you to define your agents in a structured, configuration-driven way, separating agent behavior from implementation details.
Install the declarative package via pip:
pip install agent-framework-declarative --preThe declarative package provides support for building agents based on YAML specifications. This approach offers several benefits:
- Cross-Platform Compatibility: Write one YAML definition and create agents in both Python and .NET - the same agent configuration works across both platforms
- Separation of Concerns: Define agent behavior in YAML files separate from your implementation code
- Reusability: Share and version agent configurations independently across projects and languages
- Flexibility: Easily swap between different LLM providers and configurations
- Maintainability: Update agent instructions and settings without modifying code
1. Get Weather Agent (get_weather_agent.py)
Demonstrates how to create an agent with custom function tools using the declarative approach.
- Uses Azure OpenAI Responses client
- Shows how to bind Python functions to the agent using the
bindingsparameter - Loads agent configuration from
agent-samples/chatclient/GetWeather.yaml - Implements a simple weather lookup function tool
Key concepts: Function binding, Azure OpenAI integration, tool usage
2. Microsoft Learn Agent (microsoft_learn_agent.py)
Shows how to create an agent that can search and retrieve information from Microsoft Learn documentation using the Model Context Protocol (MCP).
- Uses Azure AI Foundry client with MCP server integration
- Demonstrates async context managers for proper resource cleanup
- Loads agent configuration from
agent-samples/foundry/MicrosoftLearnAgent.yaml - Uses Azure CLI credentials for authentication
- Leverages MCP to access Microsoft documentation tools
Requirements: pip install agent-framework-azure-ai --pre
Key concepts: Azure AI Foundry integration, MCP server usage, async patterns, resource management
3. Inline YAML Agent (inline_yaml.py)
Shows how to create an agent using an inline YAML string rather than a file.
- Uses Azure AI Foundry v2 Client with instructions.
Requirements: pip install agent-framework-azure-ai --pre
Key concepts: Inline YAML definition.
4. Azure OpenAI Responses Agent (azure_openai_responses_agent.py)
Illustrates a basic agent using Azure OpenAI with structured responses.
- Uses Azure OpenAI Responses client
- Shows how to pass credentials via
client_kwargs - Loads agent configuration from
agent-samples/azure/AzureOpenAIResponses.yaml - Demonstrates accessing structured response data
Key concepts: Azure OpenAI integration, credential management, structured outputs
5. OpenAI Responses Agent (openai_responses_agent.py)
Demonstrates the simplest possible agent using OpenAI directly.
- Uses OpenAI API (requires
OPENAI_API_KEYenvironment variable) - Shows minimal configuration needed for basic agent creation
- Loads agent configuration from
agent-samples/openai/OpenAIResponses.yaml
Key concepts: OpenAI integration, minimal setup, environment-based configuration
All the YAML configuration files referenced in these samples are located in the agent-samples folder at the repository root. This folder contains declarative agent specifications organized by provider:
agent-samples/azure/- Azure OpenAI agent configurationsagent-samples/chatclient/- Chat client agent configurations with toolsagent-samples/foundry/- Azure AI Foundry agent configurationsagent-samples/openai/- OpenAI agent configurations
Important: These YAML files are platform-agnostic and work with both Python and .NET implementations of the Agent Framework. You can use the exact same YAML definition to create agents in either language, making it easy to share agent configurations across different technology stacks.
These YAML files define:
- Agent instructions and system prompts
- Model selection and parameters
- Tool and function configurations
- Provider-specific settings
- MCP server integrations (where applicable)
from agent_framework.declarative import AgentFactory
with open("agent.yaml", "r") as f:
yaml_str = f.read()
agent = AgentFactory().create_agent_from_yaml(yaml_str)
# response = await agent.run("Your query here")from pathlib import Path
from agent_framework.declarative import AgentFactory
yaml_path = Path("agent.yaml")
agent = AgentFactory().create_agent_from_yaml_path(yaml_path)
# response = await agent.run("Your query here")from pathlib import Path
from agent_framework.declarative import AgentFactory
def my_function(param: str) -> str:
return f"Result: {param}"
agent_factory = AgentFactory(bindings={"my_function": my_function})
agent = agent_factory.create_agent_from_yaml_path(Path("agent_with_tool.yaml"))from pathlib import Path
from agent_framework.declarative import AgentFactory
from azure.identity import AzureCliCredential
agent = AgentFactory(
client_kwargs={"credential": AzureCliCredential()}
).create_agent_from_yaml_path(Path("azure_agent.yaml"))from pathlib import Path
from agent_framework.declarative import AgentFactory
# from my_custom_module import MyCustomChatClient
# Register a custom provider mapping
agent_factory = AgentFactory(
additional_mappings={
"MyProvider": {
"package": "my_custom_module",
"name": "MyCustomChatClient",
"model_id_field": "model_id",
}
}
)
# Now you can reference "MyProvider" in your YAML
# Example YAML snippet:
# model:
# provider: MyProvider
# id: my-model-name
agent = agent_factory.create_agent_from_yaml_path(Path("custom_provider.yaml"))This allows you to extend the declarative framework with custom chat client implementations. The mapping requires:
- package: The Python package/module to import from
- name: The class name of your SupportsChatGetResponse implementation
- model_id_field: The constructor parameter name that accepts the value of the
model.idfield from the YAML
You can reference your custom provider using either Provider.ApiType format or just Provider in your YAML configuration, as long as it matches the registered mapping.
The declarative framework supports PowerFx formulas in YAML values, enabling dynamic configuration based on environment variables and conditional logic. Prefix any value with = to evaluate it as a PowerFx expression.
Access environment variables using the Env.<variable_name> syntax:
model:
connection:
kind: key
apiKey: =Env.OPENAI_API_KEY
endpoint: =Env.BASE_URL & "/v1" # String concatenation with &
options:
temperature: 0.7
maxOutputTokens: =Env.MAX_TOKENS # Will be converted to appropriate typeUse PowerFx operators for conditional configuration. This is particularly useful for adjusting parameters based on which model is being used:
model:
id: =Env.MODEL_NAME
options:
# Set max tokens based on model - using conditional logic
maxOutputTokens: =If(Env.MODEL_NAME = "gpt-5", 8000, 4000)
# Adjust temperature for different environments
temperature: =If(Env.ENVIRONMENT = "production", 0.3, 0.7)
# Use logical operators for complex conditions
seed: =If(Env.ENVIRONMENT = "production" And Env.DETERMINISTIC = "true", 42, Blank())- String operations: Concatenation (
&), comparison (=,<>), substring testing (in,exactin) - Logical operators:
And,Or,Not(also&&,||,!) - Arithmetic: Basic math operations (
+,-,*,/) - Conditional:
If(condition, true_value, false_value) - Environment access:
Env.<VARIABLE_NAME>
Example with multiple features:
instructions: =If(
Env.USE_EXPERT_MODE = "true",
"You are an expert AI assistant with advanced capabilities. " & Env.CUSTOM_INSTRUCTIONS,
"You are a helpful AI assistant."
)
model:
options:
stopSequences: =If("gpt-4" in Env.MODEL_NAME, ["END", "STOP"], ["END"])Note: PowerFx evaluation happens when the YAML is loaded, not at runtime. Use environment variables (via .env file or env_file parameter) to make configurations flexible across environments.
Each sample can be run independently. Make sure you have the required environment variables set:
- For Azure samples: Ensure you're logged in via Azure CLI (
az login) - For OpenAI samples: Set
OPENAI_API_KEYenvironment variable
# Run a specific sample
python get_weather_agent.py
python microsoft_learn_agent.py
python inline_yaml.py
python azure_openai_responses_agent.py
python openai_responses_agent.py- Agent Framework Declarative Package - Main declarative package documentation
- Agent Samples - Additional declarative agent YAML specifications
- Agent Framework Core - Core agent framework documentation
- Explore the YAML files in the
agent-samplesfolder to understand the configuration format - Try modifying the samples to use different models or instructions
- Create your own declarative agent configurations
- Build custom function tools and bind them to your agents