Workflow:Microsoft Agent framework Declarative Agent Definition
| Knowledge Sources | |
|---|---|
| Domains | AI_Agents, Declarative_Configuration, LLM_Ops, Python |
| Last Updated | 2026-02-11 17:00 GMT |
Overview
End-to-end process for defining AI agents declaratively using YAML configuration files and binding them to Python tool functions at runtime.
Description
This workflow demonstrates the declarative agent creation pattern using the agent-framework-declarative package. Instead of writing Python code to construct agents, developers define agent configuration in YAML files that specify the chat client type, model instructions, tool references, and MCP server connections. At runtime, an AgentFactory resolves the YAML definition against a set of Python bindings (tool functions, client instances) to produce a fully functional Agent. This approach separates agent configuration from implementation, enabling non-developers to modify agent behavior and supporting configuration-driven deployment patterns.
Usage
Execute this workflow when you want to decouple agent configuration from application code. Common scenarios include deploying agents where non-technical users configure behavior via YAML, managing multiple agent variants through configuration files, supporting hot-reloading of agent definitions without code changes, and creating portable agent specifications that work across different deployment environments. You need YAML agent definition files and the corresponding Python tool functions.
Execution Steps
Step 1: Author the YAML agent definition
Create a YAML file that declares the agent's configuration. The YAML schema specifies the agent type (chat client provider), model deployment details, system instructions, and references to tools and MCP servers. Tool references in the YAML point to binding keys that will be resolved at runtime against Python function implementations.
Key considerations:
- YAML files follow the agent-framework declarative schema
- The type field determines which chat client is instantiated
- Instructions define the agent's system prompt and persona
- Tool references use binding keys that map to Python functions at runtime
- MCP server connections can be declared with authentication configuration
- Sample YAML files are provided in the agent-samples/ directory of the repository
Step 2: Implement tool functions
Write the Python functions that will be bound to the tool references in the YAML definition. These functions do not need the @tool decorator since the declarative binding system handles tool registration. Each function should have proper type annotations and docstrings for the LLM to understand usage.
Key considerations:
- Functions are regular Python callables, not necessarily @tool decorated
- Type annotations on parameters inform the LLM about expected inputs
- Docstrings serve as tool descriptions for LLM reasoning
- Functions can be async or sync
- One function per YAML tool reference, matched by binding key
Step 3: Create the AgentFactory with bindings
Instantiate an AgentFactory by providing the chat client instance and a bindings dictionary that maps YAML tool reference keys to their Python function implementations. The factory resolves all references and validates that every tool declared in the YAML has a corresponding binding.
Key considerations:
- The bindings dictionary maps string keys to Python callables
- The client parameter provides the default chat client for the agent
- Missing bindings cause validation errors at factory creation time
- Multiple agents can share the same factory with different YAML definitions
Step 4: Load YAML and create the agent
Call the factory's create_agent_from_yaml() method with the YAML content (loaded from a file or provided as a string). The factory parses the YAML, resolves tool bindings, configures the chat client, and returns a fully functional Agent instance ready for execution.
Key considerations:
- YAML can be loaded from files, strings, or configuration management systems
- The returned Agent is identical to one created programmatically
- Inline YAML strings are supported for testing and embedded configurations
- The agent inherits all standard Agent capabilities (streaming, tools, middleware)
Step 5: Run the declarative agent
Execute the agent using the standard agent.run() interface with either streaming or non-streaming mode. The declarative agent behaves identically to a programmatically created agent, supporting all features including tool calls, streaming responses, thread management, and middleware.
Key considerations:
- The execution interface is identical to programmatic agents
- All standard features (streaming, tools, threads) are available
- YAML changes can be reloaded by creating a new agent from the factory
- The declarative agent can participate in orchestrations and workflows