Agent Framework Azure Ai Py

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.

Security Scan

The skill's documentation and examples match its stated purpose (Azure Agent Framework), but the runtime instructions reference Azure credentials and several environment variables/authorization headers that are not declared in the skill metadata — this mismatch and the examples that show connecting to private MCP endpoints or using bearer tokens warrant caution.

Purpose & Capability

The SKILL.md content clearly implements an Azure Agent Framework helper (creating agents, tools, threads, streaming). That purpose is coherent. However, the skill metadata declares no required environment variables or primary credential, while the runtime instructions repeatedly reference AZURE_AI_PROJECT_ENDPOINT, AZURE_AI_MODEL_DEPLOYMENT_NAME, BING_CONNECTION_ID, and use Azure credentials (AzureCliCredential / DefaultAzureCredential). The metadata omission is an inconsistency that could hide required privileged access.

Instruction Scope

Instructions are detailed and mostly within scope (agent creation, tools, streaming, threads). They include sample code that: (1) creates HTTP clients with Authorization headers (bearer tokens), (2) references uploading files and downloading file IDs, (3) saves conversation/thread IDs to disk (conversation.json), and (4) uses environment variables like BING_CONNECTION_ID and github_pat in examples. The instructions therefore expect access to credentials and potentially internal MCP endpoints; those accesses are not reflected in the declared requirements and expand the runtime data surface.

Install Mechanism

This is an instruction-only skill (no install spec, no code files). That minimizes disk-write/install risk; there is no remote download step to analyze.

Credentials

Although the registry metadata lists no required env vars or primary credential, the SKILL.md repeatedly expects Azure credentials and several environment values (AZURE_AI_PROJECT_ENDPOINT, AZURE_AI_MODEL_DEPLOYMENT_NAME, BING_CONNECTION_ID, BING_CUSTOM_CONNECTION_ID, github_pat in an example, and bearer tokens for MCP headers). Asking for Azure credentials and token-bearing headers is reasonable for this functionality, but the metadata should declare them — the omission is disproportionate and reduces transparency about what secrets you must provide.

Persistence & Privilege

always:false and default autonomous invocation are normal. The skill's examples persist conversation/thread IDs to a file and show usage of server-managed persistent agents and MCP integrations. Writing conversation metadata to disk and connecting to external MCP endpoints are expected for persistent agent scenarios, but you should be aware persistent agents and MCP tools can access and store conversation context and may call external services.

What to consider before installing

This skill appears to be a legitimate set of usage examples for the Microsoft Agent Framework on Azure, but the SKILL.md requires credentials and environment variables that the skill metadata does not declare. Before installing or using it: - Treat it as code examples, not a packaged binary; nothing is installed, but the runtime will require Azure credentials (use AzureCliCredential or DefaultAzureCredential) and may need BING_CONNECTION_ID or other tokens for hosted web search or MCP access. - Do not reuse high-privilege secrets: test with a least-privilege Azure identity or a separate test subscription. - Verify any MCP endpoint you configure (the examples allow setting custom URLs and Authorization headers) — only connect to MCP servers you control or fully trust. - Be cautious about providing GitHub PATs, bearer tokens, or other API keys referenced in examples; only supply them when you understand exactly which tool or endpoint needs them. - If you plan to persist conversation IDs or save threads to disk, ensure that files (eg. conversation.json) are stored in a safe location and do not contain secrets. - Prefer to obtain the skill from a verifiable source (repository/homepage) — the registry metadata lists no homepage; ask the publisher for provenance. If you want to proceed, request updated metadata that declares the exact environment variables and credential types required, or run the examples in an isolated environment with limited privileges first.

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

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

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

Environment Variables

export AZURE_AI_PROJECT_ENDPOINT="https://<project>.services.ai.azure.com/api/projects/<project-id>"
export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini"
export BING_CONNECTION_ID="your-bing-connection-id"  # For web search

Authentication

from azure.identity.aio import AzureCliCredential, DefaultAzureCredential

# Development
credential = AzureCliCredential()

# Production
credential = DefaultAzureCredential()

Core Workflow

Basic Agent

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

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

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

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

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

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

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

Reference Files

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