Microsoft Agent Framework

Common errors

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

• 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'.

• 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'.

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

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

Install

• pip install agent-framework Full installation (includes all sub-packages)

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