{"id":6955,"library":"agent-framework-declarative","title":"Declarative support for Microsoft Agent Framework","description":"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.","status":"active","version":"1.0.0b260409","language":"en","source_language":"en","source_url":"https://github.com/microsoft/agent-framework","tags":["AI","agents","Microsoft","declarative","LLM","workflow","automation"],"install":[{"cmd":"pip install agent-framework-declarative","lang":"bash","label":"Install declarative package"},{"cmd":"pip install agent-framework","lang":"bash","label":"Install full Agent Framework (recommended for most scenarios)"}],"dependencies":[{"reason":"This package relies on the core abstractions and implementations provided by agent-framework-core.","package":"agent-framework-core","optional":false}],"imports":[{"note":"AgentFactory is part of the main `agent-framework` package, which is used to load declarative definitions.","wrong":"from agent_framework_declarative import AgentFactory","symbol":"AgentFactory","correct":"from agent_framework import AgentFactory"}],"quickstart":{"code":"import os\nimport asyncio\nfrom agent_framework import AgentFactory\n\n# Create a dummy YAML file for the declarative agent\nagent_yaml_content = \"\"\"\nname: GreetingAgent\ndescription: An agent that greets the user.\ninstructions: \"You are a friendly agent that responds to greetings. If asked 'What can you do for me?', state your purpose as a greeting agent.\"\nmodel:\n  id: =Env.AZURE_OPENAI_MODEL # Use environment variable for model ID\n  connection:\n    kind: remote\n    endpoint: =Env.FOUNDRY_PROJECT_ENDPOINT # Use environment variable for endpoint\n\"\"\"\n\nwith open(\"greeting-agent.yaml\", \"w\") as f:\n    f.write(agent_yaml_content)\n\nasync def run_declarative_agent():\n    # Ensure environment variables are set for model connection\n    os.environ['AZURE_OPENAI_MODEL'] = os.environ.get('AZURE_OPENAI_MODEL', 'gpt-4')\n    os.environ['FOUNDRY_PROJECT_ENDPOINT'] = os.environ.get('FOUNDRY_PROJECT_ENDPOINT', 'http://localhost:5000/v1') # Placeholder\n\n    print(\"Loading agent from YAML...\")\n    async with AgentFactory().create_agent_from_yaml(\"greeting-agent.yaml\") as agent:\n        print(f\"Agent '{agent.name}' loaded. Description: {agent.description}\")\n        response = await agent.run(\"Hello, Agent!\")\n        print(\"Agent response (Hello):\", response.text)\n\n        response_purpose = await agent.run(\"What can you do for me?\")\n        print(\"Agent response (Purpose):\", response_purpose.text)\n\nif __name__ == \"__main__\":\n    asyncio.run(run_declarative_agent())\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"Prior to 1.0.0"},{"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.","message":"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).","severity":"gotcha","affected_versions":"1.0.0b* and potentially future beta releases"},{"fix":"Consider using more specific credentials like `ManagedIdentityCredential` or `EnvironmentCredential` directly configured for your production environment.","message":"For production deployments, using `DefaultAzureCredential` for authentication is not recommended due to potential latency issues, unintended credential probing, and security risks from fallback mechanisms.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"Python: Declarative agent name is not correct on the AI foundry and description+instruction not reflecting on foundry"},{"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.","cause":"Incorrect or improperly configured Azure credentials, often related to permissions or the choice of credential provider in development vs. production.","error":"Authentication errors when using Azure credentials"}]}