Microsoft Agent Framework (Python) — azure-ai-agents Add-on
azure-ai-agents is an optional Microsoft add-on for the Azure AI Agents service, not a replacement for agent-framework. This page explains when to use it alongside the framework.
Clarification:
azure-ai-agentsis not a replacement foragent-framework. It is an optional Microsoft SDK for direct access to the Azure AI Agents service REST API. Use it alongsideagent-frameworkwhen you need low-level control over Azure AI Agents service resources (threads, runs, vector stores). For everyday agent development, useagent-frameworkdirectly.
Deprecation:
azure-ai-agents(1.1.0) targets the classic Foundry Agent Service: the threads, messages and runs API. Microsoft Learn marks Agents (classic) as deprecated, to be retired on 31 March 2027, and says that models later than GPT-5 need the new agents. New code should use the new Foundry Agent Service, whichagent-frameworkreaches throughFoundryChatClientandFoundryAgent(agent-framework-foundry, built onazure-ai-projects2.x). See Microsoft’s migration guide.
Package Summary
Section titled “Package Summary”agent-framework | azure-ai-agents | |
|---|---|---|
| Role | Primary agent framework | Classic Azure AI Agents service SDK (deprecated service) |
| Install | pip install agent-framework | pip install azure-ai-agents azure-identity |
| Import root | agent_framework | azure.ai.agents |
| Entry-point class | Agent | AgentsClient |
| Use case | All agent development | Direct Azure AI Agents service access |
When to use azure-ai-agents
Section titled “When to use azure-ai-agents”Use azure-ai-agents alongside agent-framework when you need:
- Direct thread/run lifecycle management —
client.threads.create(),client.runs.create_and_process() - Azure AI Agents service tools — Code Interpreter, File Search, Bing Grounding, Azure AI Search via
AgentsClient - Vector store management —
VectorStore,VectorStoreFileBatchfor file-backed retrieval - Connected agent orchestration —
ConnectedAgentToolfor multi-agent topologies on Azure
For everything else — tool decoration, middleware, sessions, MCP, A2A, declarative agents, functional workflows — use agent-framework directly.
Side-by-side: agent-framework vs azure-ai-agents
Section titled “Side-by-side: agent-framework vs azure-ai-agents”agent-framework (primary framework)
Section titled “agent-framework (primary framework)”import asynciofrom agent_framework import Agentfrom agent_framework.foundry import FoundryChatClientfrom azure.identity import AzureCliCredential
async def main(): client = FoundryChatClient( project_endpoint="https://myresource.services.ai.azure.com/api/projects/my-project", model="gpt-6-luna", credential=AzureCliCredential(), ) agent = Agent(client=client, instructions="You are a helpful assistant.") response = await agent.run("hello") print(response.text)
asyncio.run(main())azure-ai-agents (add-on, direct service access)
Section titled “azure-ai-agents (add-on, direct service access)”import osfrom azure.ai.agents import AgentsClientfrom azure.identity import DefaultAzureCredential
client = AgentsClient( endpoint=os.environ["AZURE_AI_AGENTS_ENDPOINT"], credential=DefaultAzureCredential(),)
agent = client.create_agent( model=os.environ["MODEL_DEPLOYMENT_NAME"], # a deployment the classic service supports name="my-assistant", instructions="You are a helpful assistant.",)
thread = client.threads.create()client.messages.create(thread_id=thread.id, role="user", content="hello")run = client.runs.create_and_process(thread_id=thread.id, agent_id=agent.id)
messages = client.messages.list(thread_id=thread.id)for msg in messages: for content in msg.content: if hasattr(content, "text"): print(content.text.value)
client.delete_agent(agent.id)client.threads.delete(thread.id)Installation
Section titled “Installation”# Primary framework (required)pip install agent-framework
# Add-on for Azure AI Agents service access (optional)pip install azure-ai-agents azure-identityProvider-specific agent-framework sub-packages:
pip install agent-framework-foundry # Microsoft Foundry chat client (FoundryChatClient)pip install agent-framework-openai # OpenAI / Azure OpenAI chat clientspip install agent-framework-a2a --pre # A2A protocol (beta)pip install agent-framework-declarative # Declarative YAML agents and workflowsFurther Reading
Section titled “Further Reading”- Comprehensive Python guide — the
agent-frameworkcore, with an API map - Model providers —
FoundryChatClient,OpenAIChatClient,AnthropicClient azure-ai-agentsreference on Microsoft Learn —AgentsClient, threads, runs, tool sets and vector stores- Official
azure-ai-agentsPyPI page
Revision history
Section titled “Revision history”| Date | Version | Changes |
|---|---|---|
| 2026-10-25 | 1.22.0 | Added the deprecation of the classic Agents service that azure-ai-agents targets (retirement on 31 March 2027, per Microsoft Learn), and replaced the current model placeholder in the classic example with a deployment name, because the classic service does not support models after GPT-5. |