Microsoft Agent Framework

1.0.1 verified Wed Apr 15 auth: no python

Microsoft Agent Framework is a comprehensive Python library for building, orchestrating, and deploying AI agents and multi-agent workflows. It provides core abstractions, implementations, and integrations with various LLM providers. Version 1.0.1 is the current stable release, offering production-ready APIs with a commitment to long-term support. The project maintains an active development and release cadence.

pip install agent-framework

Common errors

error ImportError: cannot import name 'use_instrumentation' from 'agent_framework.observability' ↓

cause The 'use_instrumentation' function is not present in the 'agent_framework.observability' module, possibly due to an API change or version mismatch.

fix

Verify the installed version of 'agent-framework' and ensure it includes 'use_instrumentation'. If not, update the package or consult the documentation for the correct function to use.

error ImportError: cannot import name 'MCPTool' from 'azure.ai.projects.models' ↓

cause The 'MCPTool' has been relocated from 'azure.ai.projects.models' to 'azure.ai.agents.models' in the Azure AI SDK.

fix

Update the import statement to 'from azure.ai.agents.models import MCPTool'.

error ModuleNotFoundError: No module named 'agent_framework' ↓

cause The 'agent-framework' package is not installed in the current Python environment.

fix

Install the package using 'pip install agent-framework'.

error ImportError: cannot import name 'AzureAIAgentClient' from 'agent_framework.azure' ↓

cause The 'AzureAIAgentClient' class is not available in the 'agent_framework.azure' module, possibly due to a version mismatch or incorrect installation.

fix

Ensure that the 'agent-framework' package is up to date and correctly installed. If the issue persists, consult the official documentation for the correct import path.

error ModuleNotFoundError: No module named 'agent_framework.foundry' ↓

cause The 'foundry' submodule, which provides components like 'FoundryChatClient', is either not installed or its package path is incorrect. It often requires additional installation beyond the core 'agent-framework'.

fix

Ensure that any necessary Foundry-specific extensions or sub-packages are installed. Consult the 'agent-framework' documentation for specific Foundry integration installation instructions, which might involve a command like pip install agent-framework-foundry or pip install agent-framework --pre if it's part of a pre-release bundle.

Warnings

gotcha All agent operations in the Microsoft Agent Framework are asynchronous. You must use `async/await` syntax and execute your agent logic within an `async` function, typically run via `asyncio.run()`. ↓

fix Wrap agent invocation code in an `async def main():` function and execute it with `asyncio.run(main())`.

gotcha Proper authentication and configuration via environment variables are crucial. For Azure services, you'll need to authenticate (e.g., using `az login` for `AzureCliCredential`) and set variables like `AZURE_AI_PROJECT_ENDPOINT` and `AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME`. ↓

fix Ensure `azure-identity` is installed, run `az login` for Azure CLI authentication, and set required environment variables or API keys before running your agent code. Consider using `python-dotenv` for local development with a `.env` file.

gotcha The command `pip install agent-framework` installs the main package along with all its sub-packages and integrations (e.g., Azure, Foundry, Purview, AG-UI). This can lead to a large dependency footprint. If you only need core functionality or specific integrations, consider installing individual sub-packages (e.g., `agent-framework-core`, `agent-framework-azure`) to keep dependencies lighter. ↓

fix For smaller deployments or specific use cases, analyze your needs and install only the relevant sub-packages (e.g., `pip install agent-framework-core agent-framework-azure`).

gotcha The Microsoft Agent Framework requires Python 3.10 or a newer version to run correctly. ↓

fix Ensure your development and deployment environments are using Python 3.10 or a later version.

Imports

Agent
```
from agent_framework import Agent
```

FoundryChatClient

from agent_framework.foundry import FoundryChatClient

AzureOpenAIResponsesClient

from agent_framework.azure import AzureOpenAIResponsesClient

AzureCliCredential
wrong
```
from agent_framework.azure import AzureCliCredential
```
correct
```
from azure.identity import AzureCliCredential
```
AzureCliCredential is part of the 'azure-identity' package, not 'agent-framework.azure'.
asyncio
```
import asyncio
```
os
```
import os
```

Quickstart

This quickstart demonstrates how to create a simple AI agent using the Microsoft Agent Framework with Azure OpenAI. It requires `azure-identity` for authentication (e.g., via `az login`) and environment variables for Azure project endpoint and deployment name. All agent operations are asynchronous and must be run using `asyncio.run()`.

import asyncio
import os
from agent_framework.azure import AzureOpenAIResponsesClient
from azure.identity import AzureCliCredential
# from dotenv import load_dotenv # Uncomment and install if using .env file locally

async def main():
    # Load environment variables from .env file if uncommented above
    # load_dotenv()

    # Ensure AZURE_AI_PROJECT_ENDPOINT and AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME are set
    # and you are authenticated via Azure CLI (e.g., `az login`)
    project_endpoint = os.environ.get("AZURE_AI_PROJECT_ENDPOINT", "https://your-project.services.ai.azure.com")
    deployment_name = os.environ.get("AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME", "gpt-4o")

    if not all([project_endpoint, deployment_name]):
        print("Please set AZURE_AI_PROJECT_ENDPOINT and AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME environment variables.")
        print("Ensure you have authenticated via Azure CLI (`az login`).")
        return

    # Create an Azure CLI credential for authentication
    credential = AzureCliCredential()

    # Initialize the Azure OpenAI Responses client
    client = AzureOpenAIResponsesClient(
        project_endpoint=project_endpoint,
        deployment_name=deployment_name,
        credential=credential,
    )

    # Create an agent with instructions
    agent = client.as_agent(
        name="HelloAgent",
        instructions="You are a friendly assistant. Keep your answers brief.",
    )

    # Run the agent
    print("Agent: Thinking...")
    result = await agent.run("What is the capital of France?")
    print(f"Agent: {result}")

    # Example of streaming response (optional)
    # print("\nAgent (streaming): Thinking...")
    # async for token in agent.run("Tell me a short story about a brave knight.", stream=True):
    #     print(token, end="", flush=True)
    # print()

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