agent-framework/python/samples/05-end-to-end/hosted_agents

Hosted Agent Samples

These samples demonstrate how to build and host AI agents in Python using the Azure AI AgentServer SDK together with Microsoft Agent Framework. Each sample runs locally as a hosted agent and includes Dockerfile and agent.yaml assets for deployment to Microsoft Foundry.

Samples

Sample	Description
agent_with_hosted_mcp	Hosted MCP tool that connects to Microsoft Learn via https://learn.microsoft.com/api/mcp
agent_with_text_search_rag	Retrieval-augmented generation using a custom BaseContextProvider with Contoso Outdoors sample data
agents_in_workflow	Concurrent workflow that combines researcher, marketer, and legal specialist agents
agent_with_local_tools	Local Python tool execution for Seattle hotel search
writer_reviewer_agents_in_workflow	Writer/Reviewer workflow using AzureOpenAIResponsesClient

Common Prerequisites

Before running any sample, ensure you have:

1. Python 3.10 or later
2. Azure CLI installed
3. An Azure OpenAI resource or a Microsoft Foundry project with a chat model deployment

Authenticate with Azure CLI

All samples rely on Azure credentials. For local development, the simplest approach is Azure CLI authentication:

az login
az account show

Running a Sample

Each sample folder contains its own requirements.txt. Run commands from the specific sample directory you want to try.

Recommended: uv

The sample dependencies include preview packages, so allow prerelease installs:

cd <sample-directory>
uv venv .venv
uv pip install --prerelease=allow -r requirements.txt
uv run main.py

Alternative: venv

Windows PowerShell:

cd <sample-directory>
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python main.py

macOS/Linux:

cd <sample-directory>
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python main.py

Each sample starts a hosted agent locally on http://localhost:8088/.

Environment Variable Setup

You can either export variables in your shell or create a local .env file in the sample directory.

Example .env for Azure OpenAI samples:

AZURE_OPENAI_ENDPOINT=https://<your-openai-resource>.openai.azure.com/
AZURE_OPENAI_CHAT_DEPLOYMENT_NAME=gpt-4.1

Example .env for Foundry project samples:

PROJECT_ENDPOINT=https://<your-resource>.services.ai.azure.com/api/projects/<your-project>
MODEL_DEPLOYMENT_NAME=gpt-4.1

Interacting with the Agent

After starting a sample, send requests to the Responses endpoint.

PowerShell:

$body = @{
		input = "Your question here"
		stream = $false
} | ConvertTo-Json

Invoke-RestMethod -Uri "http://localhost:8088/responses" -Method Post -Body $body -ContentType "application/json"

curl:

curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
	-d '{"input":"Your question here","stream":false}'

Example prompts by sample:

Sample	Example input
agent_with_hosted_mcp	What does Microsoft Learn say about managed identities in Azure?
agent_with_text_search_rag	What is Contoso Outdoors' return policy for refunds?
agents_in_workflow	Create a launch strategy for a budget-friendly electric SUV.
agent_with_local_tools	Find me Seattle hotels from 2025-03-15 to 2025-03-18 under $200 per night.
writer_reviewer_agents_in_workflow	Write a slogan for a new affordable electric SUV.

Deploying to Microsoft Foundry

Each sample includes a Dockerfile and agent.yaml for deployment. For deployment steps, follow the hosted agents guidance in Microsoft Foundry:

• Hosted agents overview
• Create a hosted agent with CLI
• Create a hosted agent in Visual Studio Code

Troubleshooting

Missing Azure credentials

If startup fails with authentication errors, run az login and verify the selected subscription with az account show.

Preview package install issues

These samples depend on preview packages such as azure-ai-agentserver-agentframework. Use uv pip install --prerelease=allow -r requirements.txt or pip install -r requirements.txt.

ARM64 container images fail after deployment

If you build images locally on ARM64 hardware such as Apple Silicon, build for linux/amd64:

docker build --platform=linux/amd64 -t image .