Registry /
llm-agents / agent-framework-declarative
Install & Compatibility
Where this runs
tested against v1.0.0b260528 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✕ build_error
832MB installed
● package 832MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AgentFactory
✓ from agent_framework import AgentFactory
✗ from agent_framework_declarative import AgentFactory
AgentFactory is part of the main `agent-framework` package, which is used to load declarative definitions.
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())
Debug
Known issues
breakingThe 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.fixReview 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.
affects: Prior to 1.0.0
gotchaThis `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).fixPin 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.
affects: 1.0.0b* and potentially future beta releases
gotchaFor production deployments, using `DefaultAzureCredential` for authentication is not recommended due to potential latency issues, unintended credential probing, and security risks from fallback mechanisms.fixConsider using more specific credentials like `ManagedIdentityCredential` or `EnvironmentCredential` directly configured for your production environment.
affects: All versions
gotchaThe 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.fixCall `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.
affects: All versions
Upgrade
Version history
1.0.0b260528latest on PyPI · released May 28, 2026
Audit
Dependencies
agent-framework-corerequiredThis package relies on the core abstractions and implementations provided by agent-framework-core.