agent-framework/python/samples/02-agents/providers/azure_ai/README.md

Azure AI Agent Examples

This folder contains examples demonstrating different ways to create and use agents with the Azure AI client from the agent_framework.azure package. These examples use the AzureAIClient with the azure-ai-projects 2.x (V2) API surface (see changelog). For V1 (azure-ai-agents 1.x) samples using AzureAIAgentClient, see the Azure AI V1 examples folder.

Examples

File	Description
azure_ai_basic.py	The simplest way to create an agent using AzureAIProjectAgentProvider. Demonstrates both streaming and non-streaming responses with function tools. Shows automatic agent creation and basic weather functionality.
azure_ai_provider_methods.py	Comprehensive guide to AzureAIProjectAgentProvider methods: create_agent() for creating new agents, get_agent() for retrieving existing agents (by name, reference, or details), and as_agent() for wrapping SDK objects without HTTP calls.
azure_ai_use_latest_version.py	Demonstrates how to reuse the latest version of an existing agent instead of creating a new agent version on each instantiation by using provider.get_agent() to retrieve the latest version.
azure_ai_with_agent_as_tool.py	Shows how to use the agent-as-tool pattern with Azure AI agents, where one agent delegates work to specialized sub-agents wrapped as tools using as_tool(). Demonstrates hierarchical agent architectures.
azure_ai_with_agent_to_agent.py	Shows how to use Agent-to-Agent (A2A) capabilities with Azure AI agents to enable communication with other agents using the A2A protocol. Requires an A2A connection configured in your Azure AI project.
azure_ai_with_azure_ai_search.py	Shows how to use Azure AI Search with Azure AI agents to search through indexed data and answer user questions with proper citations. Requires an Azure AI Search connection and index configured in your Azure AI project.
azure_ai_with_bing_grounding.py	Shows how to use Bing Grounding search with Azure AI agents to search the web for current information and provide grounded responses with citations. Requires a Bing connection configured in your Azure AI project.
azure_ai_with_bing_custom_search.py	Shows how to use Bing Custom Search with Azure AI agents to search custom search instances and provide responses with relevant results. Requires a Bing Custom Search connection and instance configured in your Azure AI project.
azure_ai_with_browser_automation.py	Shows how to use Browser Automation with Azure AI agents to perform automated web browsing tasks and provide responses based on web interactions. Requires a Browser Automation connection configured in your Azure AI project.
azure_ai_with_code_interpreter.py	Shows how to use AzureAIClient.get_code_interpreter_tool() with Azure AI agents to write and execute Python code for mathematical problem solving and data analysis.
azure_ai_with_code_interpreter_file_generation.py	Shows how to retrieve file IDs from code interpreter generated files using both streaming and non-streaming approaches.
azure_ai_with_code_interpreter_file_download.py	Shows how to download files generated by code interpreter using the OpenAI containers API.
azure_ai_with_content_filtering.py	Shows how to enable content filtering (RAI policy) on Azure AI agents using RaiConfig. Requires creating an RAI policy in Azure AI Foundry portal first.
azure_ai_with_existing_agent.py	Shows how to work with a pre-existing agent by providing the agent name and version to the Azure AI client. Demonstrates agent reuse patterns for production scenarios.
azure_ai_with_existing_conversation.py	Demonstrates how to use an existing conversation created on the service side with Azure AI agents. Shows two approaches: specifying conversation ID at the client level and using AgentSession with an existing conversation ID.
azure_ai_with_application_endpoint.py	Demonstrates calling the Azure AI application-scoped endpoint.
azure_ai_with_explicit_settings.py	Shows how to create an agent with explicitly configured AzureAIClient settings, including project endpoint, model deployment, and credentials rather than relying on environment variable defaults.
azure_ai_with_file_search.py	Shows how to use AzureAIClient.get_file_search_tool() with Azure AI agents to upload files, create vector stores, and enable agents to search through uploaded documents to answer user questions.
azure_ai_with_hosted_mcp.py	Shows how to integrate hosted Model Context Protocol (MCP) tools with Azure AI Agent using AzureAIClient.get_mcp_tool().
azure_ai_with_local_mcp.py	Shows how to integrate local Model Context Protocol (MCP) tools with Azure AI agents.
azure_ai_with_response_format.py	Shows how to use structured outputs (response format) with Azure AI agents using Pydantic models to enforce specific response schemas.
azure_ai_with_runtime_json_schema.py	Shows how to use structured outputs (response format) with Azure AI agents using a JSON schema to enforce specific response schemas.
azure_ai_with_search_context_agentic.py	Shows how to use AzureAISearchContextProvider with agentic mode. Uses Knowledge Bases for multi-hop reasoning across documents with query planning. Recommended for most scenarios - slightly slower with more token consumption for query planning, but more accurate results.
azure_ai_with_search_context_semantic.py	Shows how to use AzureAISearchContextProvider with semantic mode. Fast hybrid search with vector + keyword search and semantic ranking for RAG. Best for simple queries where speed is critical.
azure_ai_with_sharepoint.py	Shows how to use SharePoint grounding with Azure AI agents to search through SharePoint content and answer user questions with proper citations. Requires a SharePoint connection configured in your Azure AI project.
azure_ai_with_session.py	Demonstrates session management with Azure AI agents, including automatic session creation for stateless conversations and explicit session management for maintaining conversation context across multiple interactions.
azure_ai_with_image_generation.py	Shows how to use AzureAIClient.get_image_generation_tool() with Azure AI agents to generate images based on text prompts.
azure_ai_with_memory_search.py	Shows how to use memory search functionality with Azure AI agents for conversation persistence. Demonstrates creating memory stores and enabling agents to search through conversation history.
azure_ai_with_microsoft_fabric.py	Shows how to use Microsoft Fabric with Azure AI agents to query Fabric data sources and provide responses based on data analysis. Requires a Microsoft Fabric connection configured in your Azure AI project.
azure_ai_with_openapi.py	Shows how to integrate OpenAPI specifications with Azure AI agents using dictionary-based tool configuration. Demonstrates using external REST APIs for dynamic data lookup.
azure_ai_with_reasoning.py	Shows how to enable reasoning for a model that supports it.
azure_ai_with_web_search.py	Shows how to use AzureAIClient.get_web_search_tool() with Azure AI agents to perform web searches and retrieve up-to-date information from the internet.

Environment Variables

Before running the examples, you need to set up your environment variables. You can do this in one of two ways:

Option 1: Using a .env file (Recommended)

1. Copy the .env.example file from the python directory to create a .env file:

   cp ../../../../.env.example ../../../../.env
   

2. Edit the .env file and add your values:

   AZURE_AI_PROJECT_ENDPOINT="your-project-endpoint"
   AZURE_AI_MODEL_DEPLOYMENT_NAME="your-model-deployment-name"
   

Option 2: Using environment variables directly

Set the environment variables in your shell:

export AZURE_AI_PROJECT_ENDPOINT="your-project-endpoint"
export AZURE_AI_MODEL_DEPLOYMENT_NAME="your-model-deployment-name"

Required Variables

• AZURE_AI_PROJECT_ENDPOINT: Your Azure AI project endpoint (required for all examples)
• AZURE_AI_MODEL_DEPLOYMENT_NAME: The name of your model deployment (required for all examples)

Authentication

All examples use AzureCliCredential for authentication by default. Before running the examples:

1. Install the Azure CLI
2. Run az login to authenticate with your Azure account
3. Ensure you have appropriate permissions to the Azure AI project

Alternatively, you can replace AzureCliCredential with other authentication options like DefaultAzureCredential or environment-based credentials.

Running the Examples

Each example can be run independently. Navigate to this directory and run any example:

python azure_ai_basic.py
python azure_ai_with_code_interpreter.py
# ... etc

The examples demonstrate various patterns for working with Azure AI agents, from basic usage to advanced scenarios like session management and structured outputs.