Declarative support for Microsoft Agent Framework

1.0.0b260409 · active · verified Thu Apr 16

agent-framework-declarative provides declarative specification support for defining AI agents and workflows using YAML or JSON files within the Microsoft Agent Framework. It enables easier agent definition, modification, and sharing, serving as a key component of the broader Agent Framework which unifies capabilities from Semantic Kernel and AutoGen. As of April 2026, the main Agent Framework is stable at version 1.0.1, while this specific declarative package is in beta (1.0.0b260409), indicating a rapid release cadence for this component.

Common errors

```
Python: Declarative agent name is not correct on the AI foundry and description+instruction not reflecting on foundry
```
cause An issue where agent name, description, and instructions defined in YAML were not correctly reflected when deployed or viewed in Azure AI Foundry. This was a bug that has since been addressed.

fix Ensure you are using the latest stable versions of `agent-framework-declarative` and `agent-framework-azure-ai` (if applicable). This issue was resolved in recent updates.
```
Authentication errors when using Azure credentials
```
cause Incorrect or improperly configured Azure credentials, often related to permissions or the choice of credential provider in development vs. production.

fix Verify that your Azure credentials (e.g., `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID`) are correctly set in your environment. For development, `DefaultAzureCredential` is common, but ensure your user account has the necessary permissions. For production, consider using `ManagedIdentityCredential` or `EnvironmentCredential` with explicit permissions. Refer to Azure Identity documentation for detailed setup.

Warnings

breaking The Agent Framework underwent a significant architectural shift in its 1.0.0 release, impacting how agents are configured and connected. This includes a move to a leaner core and provider-leading client design. Old provider patterns, such as `AzureAIProjectAgentProvider`, are deprecated in favor of connecting directly to agents pre-configured in services like Azure AI Foundry.
Fix: Review the migration guides for Agent Framework (from Semantic Kernel or AutoGen) and update code to use the new `AgentFactory` pattern for loading and interacting with agents, especially for Foundry-hosted agents. Ensure provider-specific packages like `agent-framework-openai` or `agent-framework-foundry` are installed.
gotcha This `agent-framework-declarative` package is currently in beta (version 1.0.0b260409), meaning its APIs and behavior may be subject to more frequent changes and less backward compatibility guarantees compared to the stable `agent-framework` (version 1.0.1).
Fix: Pin the exact version in `requirements.txt` to ensure consistent behavior in your deployments. Regularly check the official GitHub repository and release notes for updates and potential breaking changes when upgrading.
gotcha For production deployments, using `DefaultAzureCredential` for authentication is not recommended due to potential latency issues, unintended credential probing, and security risks from fallback mechanisms.
Fix: Consider using more specific credentials like `ManagedIdentityCredential` or `EnvironmentCredential` directly configured for your production environment.
gotcha The Agent Framework does not automatically load environment variables from `.env` files. If you rely on `.env` files for configuration, you must explicitly load them at the start of your application.
Fix: Call `load_dotenv()` from the `python-dotenv` library at the entry point of your application, or ensure environment variables are set directly in your shell or deployment environment.

Install

pip install agent-framework-declarative Install declarative package
pip install agent-framework Install full Agent Framework (recommended for most scenarios)

Imports

AgentFactory
wrong:
```
from agent_framework_declarative import AgentFactory
```
correct:
```
from agent_framework import AgentFactory
```
AgentFactory is part of the main `agent-framework` package, which is used to load declarative definitions.

Quickstart

This quickstart demonstrates how to define a simple agent using a YAML file and then load and run it using `AgentFactory.create_agent_from_yaml`. It uses placeholder environment variables for model connection, which should be configured with actual values for execution.

import os
import asyncio
from agent_framework import AgentFactory

# Create a dummy YAML file for the declarative agent
agent_yaml_content = """
name: GreetingAgent
description: An agent that greets the user.
instructions: "You are a friendly agent that responds to greetings. If asked 'What can you do for me?', state your purpose as a greeting agent."
model:
  id: =Env.AZURE_OPENAI_MODEL # Use environment variable for model ID
  connection:
    kind: remote
    endpoint: =Env.FOUNDRY_PROJECT_ENDPOINT # Use environment variable for endpoint
"""

with open("greeting-agent.yaml", "w") as f:
    f.write(agent_yaml_content)

async def run_declarative_agent():
    # Ensure environment variables are set for model connection
    os.environ['AZURE_OPENAI_MODEL'] = os.environ.get('AZURE_OPENAI_MODEL', 'gpt-4')
    os.environ['FOUNDRY_PROJECT_ENDPOINT'] = os.environ.get('FOUNDRY_PROJECT_ENDPOINT', 'http://localhost:5000/v1') # Placeholder

    print("Loading agent from YAML...")
    async with AgentFactory().create_agent_from_yaml("greeting-agent.yaml") as agent:
        print(f"Agent '{agent.name}' loaded. Description: {agent.description}")
        response = await agent.run("Hello, Agent!")
        print("Agent response (Hello):", response.text)

        response_purpose = await agent.run("What can you do for me?")
        print("Agent response (Purpose):", response_purpose.text)

if __name__ == "__main__":
    asyncio.run(run_declarative_agent())

view raw JSON →