Microsoft Agent Framework Core

1.0.1 · active · verified Sun Apr 12

Microsoft Agent Framework Core (version 1.0.1) is the foundational Python package for building, orchestrating, and deploying AI agents and multi-agent workflows. It provides core abstractions and implementations, serving as the stable and production-ready base for the broader Microsoft Agent Framework which also supports .NET. The framework offers enterprise-grade multi-agent orchestration, multi-provider model support, and cross-runtime interoperability. It maintains an active development and release cadence, with version 1.0.0 released in early April 2026 and subsequent patches.

Warnings

breaking With the 1.0.0 release, OpenAI and Azure-specific implementations and their dependencies were extracted from `agent-framework-core` into dedicated packages (e.g., `agent-framework-openai`, `agent-framework-foundry`). Users migrating from older beta versions must update their `pip install` commands and import paths accordingly.
Fix: Run `pip install agent-framework` to get the metapackage, then update imports from `agent_framework.core.openai` to `agent_framework.openai` (or similar for other providers).
breaking The `Message` constructor's `text` parameter is deprecated and will be removed. All message content should now be passed via the `contents` parameter.
Fix: Replace `Message(text='your message')` with `Message(contents=[{'text': 'your message'}])` or similar structured content.
breaking Deprecated aliases `BaseContextProvider` and `BaseHistoryProvider` were removed in version 1.0.0.
Fix: Update references to the new, non-aliased class names as per official documentation.
gotcha Version 1.0.1 introduced a restricted unpickler for checkpoint deserialization as a security hardening. If your application stores custom types in checkpoints, you must explicitly pass their 'module:qualname' identifiers via the `allowed_checkpoint_types` constructor parameter for `FileCheckpointStorage`, otherwise loads will raise `WorkflowCheckpointException`.
Fix: For custom types in checkpoints, provide `allowed_checkpoint_types=['your_module:YourCustomClass']` during storage configuration.
gotcha The `AgentSession` type in Agent Framework does not provide a built-in session deletion API. This is because not all AI providers support hosted chat history or thread deletion. If you require session deletion, you must manage and track session IDs yourself and use the specific provider's API if it supports such functionality.
Fix: Maintain external tracking of session IDs and use provider-specific methods for deletion, if available.
gotcha Most agent frameworks, including `agent-framework-core` when used without careful design, can struggle with consistent memory and coordination in multi-worker or parallel multi-agent setups. They often assume a single model session context, leading to inconsistencies if state isn't explicitly shared or managed centrally.
Fix: Implement robust memory management strategies like centralized event logs or derived state snapshots, and design explicit coordination mechanisms for multi-agent workflows.
gotcha Not all AI workflows necessitate a full agent framework. For simpler, linear tasks, direct tool-calling code can be more efficient and easier to debug. Agent frameworks provide the most value for complex scenarios involving loops, parallel specialists, or long-running persistent state.
Fix: Evaluate your workflow complexity before committing to a full framework; start with simpler solutions and introduce framework elements only where clear benefits in orchestration, state management, or multi-agent coordination are observed.

Install

pip install agent-framework Recommended installation (includes core and common providers)

Imports

Agent
```
from agent_framework import Agent
```

OpenAIChatClient

from agent_framework.openai import OpenAIChatClient

FoundryChatClient

from agent_framework.foundry import FoundryChatClient

Message
```
from agent_framework.core.message import Message
```
The `text` parameter in `Message` constructor is deprecated; use `contents=[...]` instead.

Quickstart

This quickstart demonstrates how to create and run a simple agent using the `agent-framework` with an OpenAI chat client. It requires setting the `OPENAI_API_KEY` environment variable. For Azure OpenAI, `AZURE_OPENAI_ENDPOINT` and `AZURE_OPENAI_DEPLOYMENT_NAME` would be needed along with Azure credentials.

import asyncio
import os
from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient

async def main():
    # Ensure OPENAI_API_KEY environment variable is set
    # For Azure OpenAI, set AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_DEPLOYMENT_NAME
    openai_api_key = os.environ.get("OPENAI_API_KEY", "YOUR_OPENAI_API_KEY_HERE")

    if not openai_api_key or openai_api_key == "YOUR_OPENAI_API_KEY_HERE":
        print("Please set the OPENAI_API_KEY environment variable or replace the placeholder.")
        return

    try:
        client = OpenAIChatClient(api_key=openai_api_key)
        agent = Agent(
            client=client,
            name="HelloAgent",
            instructions="You are a friendly assistant that writes haikus about nature."
        )
        print("\n--- Running Agent ---")
        result = await agent.run("Write a haiku about a blooming spring flower.")
        print(f"Agent Response: {result}")

    except Exception as e:
        print(f"An error occurred: {e}")
        print("Ensure your API key is valid and required environment variables are set for the chosen client.")

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

view raw JSON →