Skip to content

Commit c2fec6b

Browse files
huimiuhuimiu
authored
Python: Add foundry hosted agents samples for python (#4648)
* Add two hosted agent samples using the foundry agent * Refactor formatting and improve readability in main.py * Add agent-framework dependency to requirements and update copyright notice in main.py files * Refactor agent imports and update credential handling in hosted agent samples * Update agent framework dependency in requirements for hosted agents * chore: update Python version to 3.14 and improve Dockerfile for hosted agents * feat: add hosted agent samples for Azure AI with local tools and multi-agent workflows * fix: update Azure AI client import and refactor agent initialization in hotel agent sample * feat: add hosted agent samples for Seattle hotel search and writer-reviewer workflow * fix: correct agent name in YAML configuration for local tools agent
1 parent 705ed47 commit c2fec6b

15 files changed

Lines changed: 905 additions & 0 deletions

File tree

‎python/samples/05-end-to-end/hosted_agents/README.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# Hosted Agent Samples
2+
3+
These samples demonstrate how to build and host AI agents in Python using the [Azure AI AgentServer SDK](https://pypi.org/project/azure-ai-agentserver-agentframework/) 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.
4+
5+
## Samples
6+
7+
| Sample | Description |
8+
| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
9+
| [`agent_with_hosted_mcp`](./agent_with_hosted_mcp/) | Hosted MCP tool that connects to Microsoft Learn via `https://learn.microsoft.com/api/mcp` |
10+
| [`agent_with_text_search_rag`](./agent_with_text_search_rag/) | Retrieval-augmented generation using a custom `BaseContextProvider` with Contoso Outdoors sample data |
11+
| [`agents_in_workflow`](./agents_in_workflow/) | Concurrent workflow that combines researcher, marketer, and legal specialist agents |
12+
| [`agent_with_local_tools`](./agent_with_local_tools/) | Local Python tool execution for Seattle hotel search |
13+
| [`writer_reviewer_agents_in_workflow`](./writer_reviewer_agents_in_workflow/) | Writer/Reviewer workflow using `AzureOpenAIResponsesClient` |
14+
15+
## Common Prerequisites
16+
17+
Before running any sample, ensure you have:
18+
19+
1. Python 3.10 or later
20+
2. [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) installed
21+
3. An Azure OpenAI resource or a Microsoft Foundry project with a chat model deployment
22+
23+
### Authenticate with Azure CLI
24+
25+
All samples rely on Azure credentials. For local development, the simplest approach is Azure CLI authentication:
26+
27+
```powershell
28+
az login
29+
az account show
30+
```
31+
32+
## Running a Sample
33+
34+
Each sample folder contains its own `requirements.txt`. Run commands from the specific sample directory you want to try.
35+
36+
### Recommended: `uv`
37+
38+
The sample dependencies include preview packages, so allow prerelease installs:
39+
40+
```powershell
41+
cd <sample-directory>
42+
uv venv .venv
43+
uv pip install --prerelease=allow -r requirements.txt
44+
uv run main.py
45+
```
46+
47+
### Alternative: `venv`
48+
49+
Windows PowerShell:
50+
51+
```powershell
52+
cd <sample-directory>
53+
python -m venv .venv
54+
.\.venv\Scripts\Activate.ps1
55+
pip install -r requirements.txt
56+
python main.py
57+
```
58+
59+
macOS/Linux:
60+
61+
```bash
62+
cd <sample-directory>
63+
python -m venv .venv
64+
source .venv/bin/activate
65+
pip install -r requirements.txt
66+
python main.py
67+
```
68+
69+
Each sample starts a hosted agent locally on `http://localhost:8088/`.
70+
71+
## Environment Variable Setup
72+
73+
You can either export variables in your shell or create a local `.env` file in the sample directory.
74+
75+
Example `.env` for Azure OpenAI samples:
76+
77+
```dotenv
78+
AZURE_OPENAI_ENDPOINT=https://<your-openai-resource>.openai.azure.com/
79+
AZURE_OPENAI_CHAT_DEPLOYMENT_NAME=gpt-4.1
80+
```
81+
82+
Example `.env` for Foundry project samples:
83+
84+
```dotenv
85+
PROJECT_ENDPOINT=https://<your-resource>.services.ai.azure.com/api/projects/<your-project>
86+
MODEL_DEPLOYMENT_NAME=gpt-4.1
87+
```
88+
89+
## Interacting with the Agent
90+
91+
After starting a sample, send requests to the Responses endpoint.
92+
93+
PowerShell:
94+
95+
```powershell
96+
$body = @{
97+
input = "Your question here"
98+
stream = $false
99+
} | ConvertTo-Json
100+
101+
Invoke-RestMethod -Uri "http://localhost:8088/responses" -Method Post -Body $body -ContentType "application/json"
102+
```
103+
104+
curl:
105+
106+
```bash
107+
curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
108+
-d '{"input":"Your question here","stream":false}'
109+
```
110+
111+
Example prompts by sample:
112+
113+
| Sample | Example input |
114+
| ------------------------------------ | ---------------------------------------------------------------------------- |
115+
| `agent_with_hosted_mcp` | `What does Microsoft Learn say about managed identities in Azure?` |
116+
| `agent_with_text_search_rag` | `What is Contoso Outdoors' return policy for refunds?` |
117+
| `agents_in_workflow` | `Create a launch strategy for a budget-friendly electric SUV.` |
118+
| `agent_with_local_tools` | `Find me Seattle hotels from 2025-03-15 to 2025-03-18 under $200 per night.` |
119+
| `writer_reviewer_agents_in_workflow` | `Write a slogan for a new affordable electric SUV.` |
120+
121+
## Deploying to Microsoft Foundry
122+
123+
Each sample includes a `Dockerfile` and `agent.yaml` for deployment. For deployment steps, follow the hosted agents guidance in Microsoft Foundry:
124+
125+
- [Hosted agents overview](https://learn.microsoft.com/en-us/azure/ai-foundry/agents/concepts/hosted-agents)
126+
- [Create a hosted agent with CLI](https://learn.microsoft.com/en-us/azure/ai-foundry/agents/concepts/hosted-agents?tabs=cli#create-a-hosted-agent)
127+
- [Create a hosted agent in Visual Studio Code](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/vs-code-agents-workflow-pro-code?tabs=windows-powershell&pivots=python)
128+
129+
## Troubleshooting
130+
131+
### Missing Azure credentials
132+
133+
If startup fails with authentication errors, run `az login` and verify the selected subscription with `az account show`.
134+
135+
### Preview package install issues
136+
137+
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`.
138+
139+
### ARM64 container images fail after deployment
140+
141+
If you build images locally on ARM64 hardware such as Apple Silicon, build for `linux/amd64`:
142+
143+
```bash
144+
docker build --platform=linux/amd64 -t image .
145+
```

‎python/samples/05-end-to-end/hosted_agents/agent_with_local_tools/.dockerignore‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Virtual environments
2+
.venv/
3+
venv/
4+
env/
5+
.python-version
6+
7+
# Environment files with secrets
8+
.env
9+
.env.*
10+
*.local
11+
12+
# Python build artifacts
13+
__pycache__/
14+
*.py[cod]
15+
*$py.class
16+
*.so
17+
.Python
18+
build/
19+
develop-eggs/
20+
dist/
21+
downloads/
22+
eggs/
23+
.eggs/
24+
lib/
25+
lib64/
26+
parts/
27+
sdist/
28+
var/
29+
wheels/
30+
*.egg-info/
31+
.installed.cfg
32+
*.egg
33+
34+
# Testing
35+
.tox/
36+
.nox/
37+
.coverage
38+
.coverage.*
39+
htmlcov/
40+
.pytest_cache/
41+
.mypy_cache/
42+
43+
# IDE and OS files
44+
.DS_Store
45+
.idea/
46+
.vscode/
47+
*.swp
48+
*.swo
49+
*~
50+
51+
# Foundry config
52+
.foundry/
53+
build-source-*/
54+
55+
# Git
56+
.git/
57+
.gitignore
58+
59+
# Docker
60+
.dockerignore
61+
62+
# Documentation
63+
docs/
64+
*.md
65+
!README.md
66+
LICENSE

‎python/samples/05-end-to-end/hosted_agents/agent_with_local_tools/.env.sample‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# IMPORTANT: Never commit .env to version control - add it to .gitignore
2+
PROJECT_ENDPOINT=
3+
MODEL_DEPLOYMENT_NAME=

‎python/samples/05-end-to-end/hosted_agents/agent_with_local_tools/Dockerfile‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
FROM python:3.14-slim
2+
3+
WORKDIR /app
4+
5+
COPY ./ .
6+
7+
RUN pip install --upgrade pip && \
8+
if [ -f requirements.txt ]; then \
9+
pip install -r requirements.txt; \
10+
else \
11+
echo "No requirements.txt found"; \
12+
fi
13+
14+
EXPOSE 8088
15+
16+
CMD ["python", "main.py"]

‎python/samples/05-end-to-end/hosted_agents/agent_with_local_tools/README.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
**IMPORTANT!** All samples and other resources made available in this GitHub repository ("samples") are designed to assist in accelerating development of agents, solutions, and agent workflows for various scenarios. Review all provided resources and carefully test output behavior in the context of your use case. AI responses may be inaccurate and AI actions should be monitored with human oversight. Learn more in the transparency documents for [Agent Service](https://learn.microsoft.com/en-us/azure/ai-foundry/responsible-ai/agents/transparency-note) and [Agent Framework](https://github.com/microsoft/agent-framework/blob/main/TRANSPARENCY_FAQ.md).
2+
3+
Agents, solutions, or other output you create may be subject to legal and regulatory requirements, may require licenses, or may not be suitable for all industries, scenarios, or use cases. By using any sample, you are acknowledging that any output created using those samples are solely your responsibility, and that you will comply with all applicable laws, regulations, and relevant safety standards, terms of service, and codes of conduct.
4+
5+
Third-party samples contained in this folder are subject to their own designated terms, and they have not been tested or verified by Microsoft or its affiliates.
6+
7+
Microsoft has no responsibility to you or others with respect to any of these samples or any resulting output.
8+
9+
# What this sample demonstrates
10+
11+
This sample demonstrates a **key advantage of code-based hosted agents**:
12+
13+
- **Local Python tool execution** - Run custom Python functions as agent tools
14+
15+
Code-based agents can execute **any Python code** you write. This sample includes a Seattle Hotel Agent with a `get_available_hotels` tool that searches for available hotels based on check-in/check-out dates and budget preferences.
16+
17+
The agent is hosted using the [Azure AI AgentServer SDK](https://pypi.org/project/azure-ai-agentserver-agentframework/) and can be deployed to Microsoft Foundry using the Azure Developer CLI.
18+
19+
## How It Works
20+
21+
### Local Tools Integration
22+
23+
In [main.py](main.py), the agent uses a local Python function (`get_available_hotels`) that simulates a hotel availability API. This demonstrates how code-based agents can execute custom server-side logic that prompt agents cannot access.
24+
25+
The tool accepts:
26+
27+
- **check_in_date** - Check-in date in YYYY-MM-DD format
28+
- **check_out_date** - Check-out date in YYYY-MM-DD format
29+
- **max_price** - Maximum price per night in USD (optional, defaults to $500)
30+
31+
### Agent Hosting
32+
33+
The agent is hosted using the [Azure AI AgentServer SDK](https://pypi.org/project/azure-ai-agentserver-agentframework/),
34+
which provisions a REST API endpoint compatible with the OpenAI Responses protocol.
35+
36+
### Agent Deployment
37+
38+
The hosted agent can be deployed to Microsoft Foundry using the Azure Developer CLI [ai agent](https://learn.microsoft.com/en-us/azure/ai-foundry/agents/concepts/hosted-agents?view=foundry&tabs=cli#create-a-hosted-agent) extension.
39+
40+
## Running the Agent Locally
41+
42+
### Prerequisites
43+
44+
Before running this sample, ensure you have:
45+
46+
1. **Microsoft Foundry Project**
47+
- Project created in [Microsoft Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/what-is-foundry?view=foundry#microsoft-foundry-portals)
48+
- Chat model deployed (e.g., `gpt-4o` or `gpt-4.1`)
49+
- Note your project endpoint URL and model deployment name
50+
51+
2. **Azure CLI**
52+
- Installed and authenticated
53+
- Run `az login` and verify with `az account show`
54+
55+
3. **Python 3.10 or higher**
56+
- Verify your version: `python --version`
57+
58+
### Environment Variables
59+
60+
Set the following environment variables (matching `agent.yaml`):
61+
62+
- `PROJECT_ENDPOINT` - Your Microsoft Foundry project endpoint URL (required)
63+
- `MODEL_DEPLOYMENT_NAME` - The deployment name for your chat model (defaults to `gpt-4.1-mini`)
64+
65+
This sample loads environment variables from a local `.env` file if present.
66+
67+
Create a `.env` file in this directory with the following content:
68+
69+
```
70+
PROJECT_ENDPOINT=https://<your-resource>.services.ai.azure.com/api/projects/<your-project>
71+
MODEL_DEPLOYMENT_NAME=gpt-4.1-mini
72+
```
73+
74+
Or set them via PowerShell:
75+
76+
```powershell
77+
# Replace with your actual values
78+
$env:PROJECT_ENDPOINT="https://<your-resource>.services.ai.azure.com/api/projects/<your-project>"
79+
$env:MODEL_DEPLOYMENT_NAME="gpt-4.1-mini"
80+
```
81+
82+
### Running the Sample
83+
84+
**Recommended (`uv`):**
85+
86+
We recommend using [uv](https://docs.astral.sh/uv/) to create and manage the virtual environment for this sample.
87+
88+
```bash
89+
uv venv .venv
90+
uv pip install --prerelease=allow -r requirements.txt
91+
uv run main.py
92+
```
93+
94+
The sample depends on preview packages, so `--prerelease=allow` is required when installing with `uv`.
95+
96+
**Alternative (`venv`):**
97+
98+
If you do not have `uv` installed, you can use Python's built-in `venv` module instead:
99+
100+
**Windows (PowerShell):**
101+
102+
```powershell
103+
python -m venv .venv
104+
.\.venv\Scripts\Activate.ps1
105+
pip install -r requirements.txt
106+
python main.py
107+
```
108+
109+
**macOS/Linux:**
110+
111+
```bash
112+
python -m venv .venv
113+
source .venv/bin/activate
114+
pip install -r requirements.txt
115+
python main.py
116+
```
117+
118+
This will start the hosted agent locally on `http://localhost:8088/`.
119+
120+
### Interacting with the Agent
121+
122+
**PowerShell (Windows):**
123+
124+
```powershell
125+
$body = @{
126+
input = "I need a hotel in Seattle from 2025-03-15 to 2025-03-18, budget under $200 per night"
127+
stream = $false
128+
} | ConvertTo-Json
129+
130+
Invoke-RestMethod -Uri http://localhost:8088/responses -Method Post -Body $body -ContentType "application/json"
131+
```
132+
133+
**Bash/curl (Linux/macOS):**
134+
135+
```bash
136+
curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
137+
-d '{"input": "Find me hotels in Seattle for March 20-23, 2025 under $200 per night","stream":false}'
138+
```
139+
140+
The agent will use the `get_available_hotels` tool to search for available hotels matching your criteria.
141+
142+
### Deploying the Agent to Microsoft Foundry
143+
144+
To deploy your agent to Microsoft Foundry, follow the comprehensive deployment guide at https://learn.microsoft.com/en-us/azure/ai-foundry/agents/concepts/hosted-agents?view=foundry&tabs=cli
145+
146+
## Troubleshooting
147+
148+
### Images built on Apple Silicon or other ARM64 machines do not work on our service
149+
150+
We **recommend using `azd` cloud build**, which always builds images with the correct architecture.
151+
152+
If you choose to **build locally**, and your machine is **not `linux/amd64`** (for example, an Apple Silicon Mac), the image will **not be compatible with our service**, causing runtime failures.
153+
154+
**Fix for local builds**
155+
156+
Use this command to build the image locally:
157+
158+
```shell
159+
docker build --platform=linux/amd64 -t image .
160+
```
161+
162+
This forces the image to be built for the required `amd64` architecture.

0 commit comments

Comments
 (0)