Python: Introducing support for declarative yaml spec

[eavanvalkenburg]

Motivation and Context

1. Adds a declarative spec package
2. Adds the same folder in core
3. helpers for parsing the yaml into a object
4. loader that takes either a yaml string or a yaml path and creates a ChatAgent based on it

Closes #1471 for python

Todo:

• additional tests with agent-samples
• mypy typing
• documentation

Description

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

[Copilot]

Pull Request Overview

This PR adds declarative YAML-based agent specification support to the Microsoft Agent Framework Python implementation. The changes enable developers to define agents using YAML files that can be loaded and instantiated at runtime.

Key changes:

• New agent-framework-declarative package with YAML parsing and PowerFx expression evaluation
• Model classes for representing MAML (Microsoft Agent Markup Language) objects
• AgentFactory class for creating agents from YAML specifications
• Sample agents demonstrating various scenarios (OpenAI, Azure, tools, etc.)
• Updates to core framework to support additional chat options

Reviewed Changes

Copilot reviewed 30 out of 31 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
python/packages/declarative/*	New declarative package with models, loader, and factory
python/samples/getting_started/declarative/*	Sample applications demonstrating declarative agent usage
agent-samples/*.yaml	YAML agent definitions for various providers and scenarios
python/packages/core/agent_framework/declarative/*	Core package integration for declarative module
python/packages/core/agent_framework/_agents.py	Added allow_multiple_tool_calls parameter support
python/packages/core/agent_framework/_clients.py	Added allow_multiple_tool_calls parameter support
python/pyproject.toml	Added declarative package to dependencies
python/uv.lock	Updated lock file with new dependencies

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
_agents.py	283	51	81%	329, 388–390, 436, 485, 503, 665, 844, 847–849, 970–973, 975, 978–980, 1063, 1104, 1106, 1115–1120, 1126, 1128, 1138–1139, 1146, 1148–1149, 1157–1161, 1169–1170, 1172, 1177, 1179, 1213, 1254–1255, 1257, 1270
_clients.py	104	12	88%	268, 384, 430–433, 477, 671, 674–675, 806, 808
TOTAL	15010	2214	85%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
2172	127 💤	0 ❌	0 🔥	53.552s ⏱️

[markwallace-microsoft]

@eavanvalkenburg Consider creating your own feature branch for this work so the changes can be broken down into multiples PR's. I've done this on the .NET side as I'm expecting a very large number of unit tests.

[eavanvalkenburg]

I'll get this into a feature branch once this first iteration is very close to done

[nstijepovic]

Hey all, sorry to hijack the PR, quick question: is there any plan to include the YAML declarative workflow approach (similar to what we have for C#)? Maybe not in this PR, but in the roadmap? Thanks! :)

[eavanvalkenburg]

@nstijepovic yes that is the plan, and both workflows and agents should be able to be parsed in both dotnet and python from the same yaml file.