Microsoft Agent Framework Core

raw JSON →
1.0.1 verified Fri May 15 auth: no python

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.

pip install agent-framework
error ModuleNotFoundError: No module named 'agent_framework_core'
cause The 'agent_framework_core' package is not installed in the Python environment.
fix
Install the package using pip: 'pip install agent-framework-core'.
error ImportError: cannot import name 'OpenAIResponsesClient'
cause The 'openai' package version is outdated and does not include 'OpenAIResponsesClient'.
fix
Upgrade the 'openai' package to version 1.99.0 or later: 'pip install openai>=1.99.0'.
error pydantic.errors.PydanticImportError
cause Pydantic version 1 is installed, but version 2 is required.
fix
Upgrade Pydantic to version 2: 'pip install pydantic>=2,<3'.
error ModuleNotFoundError: No module named 'powerfx'
cause The 'powerfx' package is not installed or is incompatible with Python 3.14 or later.
fix
Install 'powerfx' version 0.0.31 or later on Python versions earlier than 3.14: 'pip install powerfx>=0.0.31'.
error agent_framework.exceptions.ServiceResponseException: <class 'agent_framework.openai._chat_client.OpenAIChatClient'> service failed to complete the prompt: Error code: 500 - {'type': 'https://tools.ietf.org/html/rfc9110#section-15.6.1', 'title': 'Failed to handle openAI completion', 'status': 500, 'detail': "JsonTypeInfo metadata for type 'System.Collections.Generic.List`1[Betalgo.Ranul.OpenAI.ObjectModels.RequestModels.MessageContent]' was not provided by TypeInfoResolver of type 'Microsoft.Neutron.OpenAI.JsonChatCompletionCreateRequestContext'. If using source generation, ensure that all root types passed to the serializer have been annotated with 'JsonSerializableAttribute', along with any types that might be serialized polymorphically. The unsupported member type is located on type 'System.Object'. Path: $.ContentCalculated."}
cause The OpenAI Chat Client encountered a serialization issue due to missing JSON metadata.
fix
Ensure that all root types passed to the serializer are annotated with 'JsonSerializableAttribute' and that the TypeInfoResolver is correctly configured to handle polymorphic serialization.
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.
python os / libc status wheel install import disk mem side effects
3.10 alpine (musl) build_error - - - - - -
3.10 slim (glibc) wheel 38.3s 0.49s 679M 16.2M noisy
3.11 alpine (musl) build_error - - - - - -
3.11 slim (glibc) wheel 38.3s 0.84s 856M 18.1M noisy
3.12 alpine (musl) build_error - - - - - -
3.12 slim (glibc) wheel 31.7s 1.04s 842M 17.8M noisy
3.13 alpine (musl) build_error - - - - - -
3.13 slim (glibc) wheel 30.9s 1.15s 838M 18.5M noisy
3.9 alpine (musl) build_error - - - - - -
3.9 slim (glibc) build_error - 1.7s - - - -

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