Declarative support for Microsoft Agent Framework

1.0.0b260409 verified Thu Apr 16 auth: no python

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.

pip install agent-framework-declarative

Common errors

error 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.

error 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

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())