---
title: "Microsoft Agent Framework Azure AI: review, setup & limitations · Undominated.ai"
canonical: https://undominated.ai/skills/microsoft-agent-framework-azure-ai/
description: "Shows how to build a persistent Azure AI Foundry agent with the Python agent-framework SDK, DefaultAzureCredential, and hosted tools."
---

# Microsoft Agent Framework Azure AI: review, setup & limitations · Undominated.ai

> Shows how to build a persistent Azure AI Foundry agent with the Python agent-framework SDK, DefaultAzureCredential, and hosted tools.

[← Explore all skills](/skills/)

AGENT FRAMEWORKS / Microsoft

# Microsoft Agent Framework Azure AI

Shows how to build a persistent Azure AI Foundry agent with the Python agent-framework SDK, DefaultAzureCredential, and hosted tools.

 [See setup guidance ↓](#setup)[Original source ↗](https://github.com/microsoft/agent-skills/tree/354361d83247c76a1c21e802e0d4887c4d8323a3/.github/plugins/azure-sdk-python/skills/agent-framework-azure-ai-py)

SOURCE REVIEW

 Reviewed 2026-10-15
 Evidence 3 linked sources
 Publisher Microsoft
 Licence [MIT ↗](https://github.com/microsoft/agent-skills/blob/354361d83247c76a1c21e802e0d4887c4d8323a3/LICENSE)
 Revision 354361d83247
 [Read what was—and wasn’t—checked ↓](#review)

“Build Azure AI Foundry agents using the Microsoft Agent Framework Python SDK (agent-framework-azure-ai). Use when creating persistent agents with AzureAIAgentsProvider, using hosted tools (code interpreter, file search, web search), integrating MCP servers, managing conversation threads, or implementing streaming responses. Covers function tools, structured outputs, and multi-tool agents.”

 [Microsoft · upstream description ↗](https://github.com/microsoft/agent-skills/blob/354361d83247c76a1c21e802e0d4887c4d8323a3/.github/plugins/azure-sdk-python/skills/agent-framework-azure-ai-py/SKILL.md) Our analysis follows below.

01 / THE REASONING

## Why this made the selection.

 - Authentication is pinned to DefaultAzureCredential rather than connection strings.
- Hosted tools, threads, and MCP each have a separate reference file.

### A good fit for

 - Creating a persistent Azure AI Foundry agent with the Python agent-framework SDK
- Adding hosted code interpreter, file search, or web search tools
- Integrate a persistent Azure-hosted agent while making tool and thread ownership explicit.

### Weigh up before choosing

 - The skill says to avoid connection strings and account keys.
- Clients are supposed to be context managers, and handlers are async.
- The repository README's install line points at microsoft/skills, while this file's own install lines are pip commands for the SDK.
- This review did not execute the skill.
- Hosted MCP tools and client-managed MCP have different execution/data paths. API and credential-chain behavior depend on installed SDK versions and deployment policy.
- The get_weather function in the examples returns a fixed string and does not call a weather data service.

02 / THE REVIEW RECORD

## What we actually inspected.

Source review has boundaries. A clear record is more useful than a “safe” badge.

### Material inspected

 - .github/plugins/azure-sdk-python/skills/agent-framework-azure-ai-py/SKILL.md
- .github/plugins/azure-sdk-python/skills/agent-framework-azure-ai-py/references/tools.md
- LICENSE
- README.md

### Our findings

 - The pinned skill installs with pip install agent-framework --pre and pip install agent-framework-azure-ai --pre, and it names the package agent-framework-azure-ai.
- Every sample is under a rule to prefer DefaultAzureCredential and to avoid connection strings.
- Conventions require async with on the provider, tools passed as functions, and get_new_thread for multi-turn conversations.
- Detail for hosted tools, MCP, threads, and structured outputs is linked from references/tools.md, references/mcp.md, references/threads.md, and references/advanced.md.
- The definition distinguishes create/get service calls from wrapping an existing SDK agent and emphasizes deterministic async resource cleanup.

### Not established by this review

 - The skill was not executed inside a host agent.
- Not executed: it was not installed or run.

The review applies to the material and revision named here. A newer upstream release can change its behavior.

03 / PUT IT TO WORK

## Add a skill to your workflow.

[Upstream setup instructions ↗](https://github.com/microsoft/agent-skills/blob/354361d83247c76a1c21e802e0d4887c4d8323a3/README.md)

DOCUMENTED COMMAND

 npx skills add microsoft/skills Copy command ↗

Run in your terminal to choose your AI tools, project or global scope, and installation method. This short command follows the current upstream version; the review covers the revision shown above.

 - Run the README command and select agent-framework-azure-ai-py in its wizard. The command installs from the current default branch, not the reviewed revision 354361d83247c76a1c21e802e0d4887c4d8323a3.
- pip install agent-framework --pre (or agent-framework-azure-ai --pre), from the SKILL.md, installs the pre-release Python SDK the skill teaches. It does not install the skill.
- Set AZURE_AI_PROJECT_ENDPOINT and AZURE_AI_MODEL_DEPLOYMENT_NAME and sign in for DefaultAzureCredential before running any example.
- For manual installation instead, download the complete bundle from https://undominated.ai/resources/skills/microsoft-agent-framework-azure-ai/bundle.zip and extract it into a new directory. It holds SKILL.md and 4 supporting files unchanged at revision 354361d8, the upstream licence and an attribution file.
- Place the extracted directory in your host's documented skills directory, named agent-framework-azure-ai-py. Keep SKILL.md and the licence together.

### Before you start

 - Node.js/npm for the skills installer
- Python with the pre-release agent-framework packages to run the examples
- An Azure AI Foundry project and model deployment

### Compatibility

Agent Skills hosts · Python · Azure AI Foundry / Azure OpenAI

### Implementation

Markdown · Python

### Microsoft Agent Framework SDK architecture guidance

 - Create and get agents on the Azure AI service
- Use hosted tools that execute code or search files
- Read environment variables for the project endpoint
- Creates hosted agents/threads and sends prompts/files to Azure; configured tools can execute code or contact external MCP services.

### Cost model

MIT licence plus an Azure AI Foundry account; hosted tools consume Azure usage the file does not price.

THE COMPLETE REVIEWED DEFINITION

## Read it before you reuse it.

Original source bytes, with attribution. Review the host-specific setup notes above.

 Copy definition ↗ [Download complete resource + licence ↗](/resources/skills/microsoft-agent-framework-azure-ai/bundle.zip)[Raw Markdown ↗](/resources/skills/microsoft-agent-framework-azure-ai/definition.md)
 ---
name: agent-framework-azure-ai-py
description: Build Azure AI Foundry agents using the Microsoft Agent Framework Python SDK (agent-framework-azure-ai). Use when creating persistent agents with AzureAIAgentsProvider, using hosted tools (code interpreter, file search, web search), integrating MCP servers, managing conversation threads, or implementing streaming responses. Covers function tools, structured outputs, and multi-tool agents.
license: MIT
metadata:
 author: Microsoft
 version: "1.0.0"
 package: agent-framework-azure-ai
---

# Agent Framework Azure Hosted Agents

Build persistent agents on Azure AI Foundry using the Microsoft Agent Framework Python SDK.

## Architecture

```
User Query → AzureAIAgentsProvider → Azure AI Agent Service (Persistent)
 ↓
 Agent.run() / Agent.run_stream()
 ↓
 Tools: Functions | Hosted (Code/Search/Web) | MCP
 ↓
 AgentThread (conversation persistence)
```

## Installation

```bash
# Full framework (recommended)
pip install agent-framework --pre

# Or Azure-specific package only
pip install agent-framework-azure-ai --pre
```

## Environment Variables

```bash
export AZURE_AI_PROJECT_ENDPOINT="https://<project>.services.ai.azure.com/api/projects/<project-id>" # Required for all auth methods
export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini" # Required for all auth methods
export BING_CONNECTION_ID="your-bing-connection-id" # For web search
export AZURE_TOKEN_CREDENTIALS=prod # Required only if DefaultAzureCredential is used in production
```

## Authentication & Lifecycle

> **🔑 Two rules apply to every code sample below:**
>
> 1. **Prefer `DefaultAzureCredential`.** It works locally (Azure CLI / VS Code / Developer CLI) and in Azure (managed identity, workload identity) with no code change. Avoid connection strings, account/API keys — they bypass Entra audit and rotation.
> - Local dev: `DefaultAzureCredential` works as-is.
> - Production: set `AZURE_TOKEN_CREDENTIALS=prod` (or `AZURE_TOKEN_CREDENTIALS=<specific_credential>`) to constrain the credential chain to production-safe credentials.
> 2. **Wrap every client in a context manager** so HTTP transports, sockets, and token caches are released deterministically:
> - Sync: `with <Client>(...) as client:`
> - Async: `async with <Client>(...) as client:` **and** `async with DefaultAzureCredential() as credential:` (from `azure.identity.aio`)
>
> Snippets may abbreviate this setup, but production code should always follow both rules.

```python
from azure.identity.aio import AzureCliCredential, DefaultAzureCredential, ManagedIdentityCredential

# Development
credential = AzureCliCredential()

# Production
# Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>
credential = DefaultAzureCredential(require_envvar=True)
# Or use a specific credential directly in production:
# See https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#credential-classes
# credential = ManagedIdentityCredential()
```

## Core Workflow

### Basic Agent

```python
import asyncio
from agent_framework.azure import AzureAIAgentsProvider
from azure.identity.aio import AzureCliCredential

async def main():
 async with (
 AzureCliCredential() as credential,
 AzureAIAgentsProvider(credential=credential) as provider,
 ):
 agent = await provider.create_agent(
 name="MyAgent",
 instructions="You are a helpful assistant.",
 )

 result = await agent.run("Hello!")
 print(result.text)

asyncio.run(main())
```

### Agent with Function Tools

```python
from typing import Annotated
from pydantic import Field
from agent_framework.azure import AzureAIAgentsProvider
from azure.identity.aio import AzureCliCredential

def get_weather(
 location: Annotated[str, Field(description="City name to get weather for")],
) -> str:
 """Get the current weather for a location."""
 return f"Weather in {location}: 72°F, sunny"

def get_current_time() -> str:
 """Get the current UTC time."""
 from datetime import datetime, timezone
 return datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")

async def main():
 async with (
 AzureCliCredential() as credential,
 AzureAIAgentsProvider(credential=credential) as provider,
 ):
 agent = await provider.create_agent(
 name="WeatherAgent",
 instructions="You help with weather and time queries.",
 tools=[get_weather, get_current_time], # Pass functions directly
 )

 result = await agent.run("What's the weather in Seattle?")
 print(result.text)
```

### Agent with Hosted Tools

```python
from agent_framework import (
 HostedCodeInterpreterTool,
 HostedFileSearchTool,
 HostedWebSearchTool,
)
from agent_framework.azure import AzureAIAgentsProvider
from azure.identity.aio import AzureCliCredential

async def main():
 async with (
 AzureCliCredential() as credential,
 AzureAIAgentsProvider(credential=credential) as provider,
 ):
 agent = await provider.create_agent(
 name="MultiToolAgent",
 instructions="You can execute code, search files, and search the web.",
 tools=[
 HostedCodeInterpreterTool(),
 HostedWebSearchTool(name="Bing"),
 ],
 )

 result = await agent.run("Calculate the factorial of 20 in Python")
 print(result.text)
```

### Streaming Responses

```python
async def main():
 async with (
 AzureCliCredential() as credential,
 AzureAIAgentsProvider(credential=credential) as provider,
 ):
 agent = await provider.create_agent(
 name="StreamingAgent",
 instructions="You are a helpful assistant.",
 )

 print("Agent: ", end="", flush=True)
 async for chunk in agent.run_stream("Tell me a short story"):
 if chunk.text:
 print(chunk.text, end="", flush=True)
 print()
```

### Conversation Threads

```python
from agent_framework.azure import AzureAIAgentsProvider
from azure.identity.aio import AzureCliCredential

async def main():
 async with (
 AzureCliCredential() as credential,
 AzureAIAgentsProvider(credential=credential) as provider,
 ):
 agent = await provider.create_agent(
 name="ChatAgent",
 instructions="You are a helpful assistant.",
 tools=[get_weather],
 )

 # Create thread for conversation persistence
 thread = agent.get_new_thread()

 # First turn
 result1 = await agent.run("What's the weather in Seattle?", thread=thread)
 print(f"Agent: {result1.text}")

 # Second turn - context is maintained
 result2 = await agent.run("What about Portland?", thread=thread)
 print(f"Agent: {result2.text}")

 # Save thread ID for later resumption
 print(f"Conversation ID: {thread.conversation_id}")
```

### Structured Outputs

```python
from pydantic import BaseModel, ConfigDict
from agent_framework.azure import AzureAIAgentsProvider
from azure.identity.aio import AzureCliCredential

class WeatherResponse(BaseModel):
 model_config = ConfigDict(extra="forbid")

 location: str
 temperature: float
 unit: str
 conditions: str

async def main():
 async with (
 AzureCliCredential() as credential,
 AzureAIAgentsProvider(credential=credential) as provider,
 ):
 agent = await provider.create_agent(
 name="StructuredAgent",
 instructions="Provide weather information in structured format.",
 response_format=WeatherResponse,
 )

 result = await agent.run("Weather in Seattle?")
 weather = WeatherResponse.model_validate_json(result.text)
 print(f"{weather.location}: {weather.temperature}°{weather.unit}")
```

## Provider Methods

| Method | Description |
|--------|-------------|
| `create_agent()` | Create new agent on Azure AI service |
| `get_agent(agent_id)` | Retrieve existing agent by ID |
| `as_agent(sdk_agent)` | Wrap SDK Agent object (no HTTP call) |

## Hosted Tools Quick Reference

| Tool | Import | Purpose |
|------|--------|---------|
| `HostedCodeInterpreterTool` | `from agent_framework import HostedCodeInterpreterTool` | Execute Python code |
| `HostedFileSearchTool` | `from agent_framework import HostedFileSearchTool` | Search vector stores |
| `HostedWebSearchTool` | `from agent_framework import HostedWebSearchTool` | Bing web search |
| `HostedMCPTool` | `from agent_framework import HostedMCPTool` | Service-managed MCP |
| `MCPStreamableHTTPTool` | `from agent_framework import MCPStreamableHTTPTool` | Client-managed MCP |

## Complete Example

```python
import asyncio
from typing import Annotated
from pydantic import BaseModel, Field
from agent_framework import (
 HostedCodeInterpreterTool,
 HostedWebSearchTool,
 MCPStreamableHTTPTool,
)
from agent_framework.azure import AzureAIAgentsProvider
from azure.identity.aio import AzureCliCredential

def get_weather(
 location: Annotated[str, Field(description="City name")],
) -> str:
 """Get weather for a location."""
 return f"Weather in {location}: 72°F, sunny"

class AnalysisResult(BaseModel):
 summary: str
 key_findings: list[str]
 confidence: float

async def main():
 async with (
 AzureCliCredential() as credential,
 MCPStreamableHTTPTool(
 name="Docs MCP",
 url="https://learn.microsoft.com/api/mcp",
 ) as mcp_tool,
 AzureAIAgentsProvider(credential=credential) as provider,
 ):
 agent = await provider.create_agent(
 name="ResearchAssistant",
 instructions="You are a research assistant with multiple capabilities.",
 tools=[
 get_weather,
 HostedCodeInterpreterTool(),
 HostedWebSearchTool(name="Bing"),
 mcp_tool,
 ],
 )

 thread = agent.get_new_thread()

 # Non-streaming
 result = await agent.run(
 "Search for Python best practices and summarize",
 thread=thread,
 )
 print(f"Response: {result.text}")

 # Streaming
 print("\nStreaming: ", end="")
 async for chunk in agent.run_stream("Continue with examples", thread=thread):
 if chunk.text:
 print(chunk.text, end="", flush=True)
 print()

 # Structured output
 result = await agent.run(
 "Analyze findings",
 thread=thread,
 response_format=AnalysisResult,
 )
 analysis = AnalysisResult.model_validate_json(result.text)
 print(f"\nConfidence: {analysis.confidence}")

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

## Conventions

- Always use async context managers: `async with provider:`
- Pass functions directly to `tools=` parameter (auto-converted to AIFunction)
- Use `Annotated[type, Field(description=...)]` for function parameters
- Use `get_new_thread()` for multi-turn conversations
- Prefer `HostedMCPTool` for service-managed MCP, `MCPStreamableHTTPTool` for client-managed

## Best Practices

1. **This SDK is async-first — use `async def` handlers and `async with` throughout.**
2. **Always use context managers for clients and async credentials.** Wrap every client in `with Client(...) as client:` (sync) or `async with Client(...) as client:` (async). For async `DefaultAzureCredential` from `azure.identity.aio`, also use `async with credential:` so tokens and transports are cleaned up.

## Reference Files

- [references/tools.md](references/tools.md): Detailed hosted tool patterns
- [references/mcp.md](references/mcp.md): MCP integration (hosted + local)
- [references/threads.md](references/threads.md): Thread and conversation management
- [references/advanced.md](references/advanced.md): OpenAPI, citations, structured outputs

The download contains SKILL.md . Extract the whole bundle; the supporting files are required. Inspect the included MANIFEST.json for file hashes.

By **Microsoft**. [Exact upstream source ↗](https://github.com/microsoft/agent-skills/blob/354361d83247c76a1c21e802e0d4887c4d8323a3/.github/plugins/azure-sdk-python/skills/agent-framework-azure-ai-py/SKILL.md) · [Licence](/resources/skills/microsoft-agent-framework-azure-ai/LICENSE.txt) · [Attribution](/resources/skills/microsoft-agent-framework-azure-ai/ATTRIBUTION.txt)

SHA-256 d79a8fefd6753474846e72b926437d7bbcddef5cd3f4fb89fb7c03f38ac4434e

 Read the applicable licence MIT License

 Copyright (c) Microsoft Corporation.

 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights
 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:

 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.

 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE

04 / FOLLOW THE EVIDENCE

## The source trail.

Our notes are separate from the original resource. Check upstream before adopting a new version.

 - [Microsoft Agent Framework skill definition ↗](https://github.com/microsoft/agent-skills/blob/354361d83247c76a1c21e802e0d4887c4d8323a3/.github/plugins/azure-sdk-python/skills/agent-framework-azure-ai-py/SKILL.md) Checked 2026-10-14 https://github.com/microsoft/agent-skills/blob/354361d83247c76a1c21e802e0d4887c4d8323a3/.github/plugins/azure-sdk-python/skills/agent-framework-azure-ai-py/SKILL.md Supports: summary, whySelected, bestFor, limitations
- [Microsoft agent-skills license ↗](https://github.com/microsoft/agent-skills/blob/354361d83247c76a1c21e802e0d4887c4d8323a3/LICENSE) Checked 2026-10-14 https://github.com/microsoft/agent-skills/blob/354361d83247c76a1c21e802e0d4887c4d8323a3/LICENSE Supports: license
- [Pinned definition rechecked for the 2026-10-15 resource wave ↗](https://raw.githubusercontent.com/microsoft/agent-skills/354361d83247c76a1c21e802e0d4887c4d8323a3/.github/plugins/azure-sdk-python/skills/agent-framework-azure-ai-py/SKILL.md) Checked 2026-10-15 https://raw.githubusercontent.com/microsoft/agent-skills/354361d83247c76a1c21e802e0d4887c4d8323a3/.github/plugins/azure-sdk-python/skills/agent-framework-azure-ai-py/SKILL.md Supports: upstreamDescription, limitations, review

KEEP COMPARING

## Other approaches to consider.

Related by category or shared topics. These are alternatives to inspect, not a measured quality order.

 [### Azure AI Language Conversations for Python ↗ Pins Microsoft's Python conversation-analysis skill, which tells new code to use token credentials and reserves API keys for unmigrated keyed deployments.](/skills/microsoft-azure-ai-language-conversations-py/)[### Microsoft Docs Research ↗ Finds current Microsoft documentation with task-specific queries and retrieves full pages when excerpts are insufficient.](/skills/microsoft-microsoft-docs/)[### AI Runway AKS setup ↗ Pins Microsoft's AI Runway AKS setup skill, which requires confirmation before install, deployment, or GPU provisioning.](/skills/microsoft-airunway-aks-setup/)

 [AI Tools ↗](/tools/)[Skills ↗](/skills/)[Agents ↗](/agents/)[MCP Servers ↗](/mcp-servers/)[Workflows ↗](/workflows/)

## Continue your investigation

 - [Choose a toolkit](/tools/)
- [Inspect execution hosts](/agents/)
- [Check tool access](/mcp-servers/)
- [Check project dependencies](/check-repo/)
