mirror of
https://github.com/microsoft/agent-framework.git
synced 2026-06-16 21:04:09 +08:00
Eduard van Valkenburg
a2856d3b92
* restructure: Python samples into progressive 01-05 layout - 01-get-started/: 6 numbered steps (hello agent → hosting) - 02-agents/: all agent concept samples (tools, middleware, providers, etc.) - 03-workflows/: ALL existing workflow samples preserved as-is - 04-hosting/: azure-functions, durabletask, a2a - 05-end-to-end/: demos, evaluation, hosted agents - Old files moved to _to_delete/ for review - Added AGENTS.md with structure documentation - autogen-migration/ and semantic-kernel-migration/ preserved at root * fix: switch to AzureOpenAI Foundry, fix CI failures - Switch all 01-get-started samples to AzureOpenAIResponsesClient with Azure AI Foundry project endpoint (AZURE_AI_PROJECT_ENDPOINT + AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME + AzureCliCredential) - Add _to_delete/ and 05-end-to-end/ to pyrightconfig.samples.json excludes - Fix test paths in packages/ that referenced old getting_started/ dirs: durabletask conftest + streaming test, azurefunctions conftest, devui conftest + capture_messages + openai_sdk_integration - Fix workflow_as_agent_human_in_the_loop.py import (sibling import) - Update hosting READMEs and tool comment paths - Replace root README.md with new structure overview - Update AGENTS.md to document Azure OpenAI Foundry as default provider * cleanup: remove _to_delete folder, copy resource files to active dirs All files in _to_delete/ were either: - Exact duplicates of files in the new structure (240 files) - Same file with only comment path updates (100 files) - One import-fix diff (workflow_as_agent_human_in_the_loop.py) - One superseded minimal_sample.py Resource files (sample.pdf, countries.json, employees.pdf, weather.json) copied to 02-agents/sample_assets/ and 02-agents/resources/ since active samples reference them. * fix: address PR review comments, centralize resources, remove root duplicates - Fix type annotation in 04_memory.py (string union -> proper types) - Fix old sample paths in observability files - Fix grammar/spelling in observability samples - Move sample_assets/ and resources/ to shared/ folder - Remove 8 duplicate observability files from 02-agents root - Update resource path references in multimodal_input and provider samples * fix: update broken links from old getting_started paths to new structure - Update relative paths in READMEs: getting_started/ → 01-get-started/, 02-agents/, 03-workflows/, 04-hosting/, 05-end-to-end/ - Fix absolute GitHub URLs in package READMEs - Fix broken link in ollama package README * fix: convert absolute GitHub URLs to relative paths for link checker Absolute URLs to python/samples/ on main branch 404 until PR merges. Converted to relative paths that linkspector can verify locally. * fix: update link for handoff sample moved to orchestrations/ * fix: update chatkit-integration README path from demos/ to 05-end-to-end/ * fix: update broken links in orchestrations README to match flat directory structure
149 lines
6.3 KiB
Markdown
149 lines
6.3 KiB
Markdown
# Durable Task Samples
|
|
|
|
This directory contains samples for durable agent hosting using the Durable Task Scheduler. These samples demonstrate the worker-client architecture pattern, enabling distributed agent execution with persistent conversation state.
|
|
|
|
## Sample Catalog
|
|
|
|
### Basic Patterns
|
|
- **[01_single_agent](01_single_agent/)**: Host a single conversational agent and interact with it via a client. Demonstrates basic worker-client architecture and agent state management.
|
|
- **[02_multi_agent](02_multi_agent/)**: Host multiple domain-specific agents (physicist and chemist) and route requests to the appropriate agent based on the question topic.
|
|
- **[03_single_agent_streaming](03_single_agent_streaming/)**: Enable reliable, resumable streaming using Redis Streams with agent response callbacks. Demonstrates non-blocking agent execution and cursor-based resumption for disconnected clients.
|
|
|
|
### Orchestration Patterns
|
|
- **[04_single_agent_orchestration_chaining](04_single_agent_orchestration_chaining/)**: Chain multiple invocations of the same agent using durable orchestration, preserving conversation context across sequential runs.
|
|
- **[05_multi_agent_orchestration_concurrency](05_multi_agent_orchestration_concurrency/)**: Run multiple agents concurrently within an orchestration, aggregating their responses in parallel.
|
|
- **[06_multi_agent_orchestration_conditionals](06_multi_agent_orchestration_conditionals/)**: Implement conditional branching in orchestrations with spam detection and email assistant agents. Demonstrates structured outputs with Pydantic models and activity functions for side effects.
|
|
- **[07_single_agent_orchestration_hitl](07_single_agent_orchestration_hitl/)**: Human-in-the-loop pattern with external event handling, timeouts, and iterative refinement based on human feedback. Shows long-running workflows with external interactions.
|
|
|
|
## Running the Samples
|
|
|
|
These samples are designed to be run locally in a cloned repository.
|
|
|
|
### Prerequisites
|
|
|
|
The following prerequisites are required to run the samples:
|
|
|
|
- [Python 3.9 or later](https://www.python.org/downloads/)
|
|
- [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) installed and authenticated (`az login`) or an API key for the Azure OpenAI service
|
|
- [Azure OpenAI Service](https://learn.microsoft.com/azure/ai-services/openai/how-to/create-resource) with a deployed model (gpt-4o-mini or better is recommended)
|
|
- [Durable Task Scheduler](https://learn.microsoft.com/azure/azure-functions/durable/durable-task-scheduler/develop-with-durable-task-scheduler) (local emulator or Azure-hosted)
|
|
- [Docker](https://docs.docker.com/get-docker/) installed if running the Durable Task Scheduler emulator locally
|
|
|
|
### Configuring RBAC Permissions for Azure OpenAI
|
|
|
|
These samples are configured to use the Azure OpenAI service with RBAC permissions to access the model. You'll need to configure the RBAC permissions for the Azure OpenAI service to allow the Python app to access the model.
|
|
|
|
Below is an example of how to configure the RBAC permissions for the Azure OpenAI service to allow the current user to access the model.
|
|
|
|
Bash (Linux/macOS/WSL):
|
|
|
|
```bash
|
|
az role assignment create \
|
|
--assignee "yourname@contoso.com" \
|
|
--role "Cognitive Services OpenAI User" \
|
|
--scope /subscriptions/<your-subscription-id>/resourceGroups/<your-resource-group-name>/providers/Microsoft.CognitiveServices/accounts/<your-openai-resource-name>
|
|
```
|
|
|
|
PowerShell:
|
|
|
|
```powershell
|
|
az role assignment create `
|
|
--assignee "yourname@contoso.com" `
|
|
--role "Cognitive Services OpenAI User" `
|
|
--scope /subscriptions/<your-subscription-id>/resourceGroups/<your-resource-group-name>/providers/Microsoft.CognitiveServices/accounts/<your-openai-resource-name>
|
|
```
|
|
|
|
More information on how to configure RBAC permissions for Azure OpenAI can be found in the [Azure OpenAI documentation](https://learn.microsoft.com/azure/ai-services/openai/how-to/create-resource?pivots=cli).
|
|
|
|
### Setting an API key for the Azure OpenAI service
|
|
|
|
As an alternative to configuring Azure RBAC permissions, you can set an API key for the Azure OpenAI service by setting the `AZURE_OPENAI_API_KEY` environment variable.
|
|
|
|
Bash (Linux/macOS/WSL):
|
|
|
|
```bash
|
|
export AZURE_OPENAI_API_KEY="your-api-key"
|
|
```
|
|
|
|
PowerShell:
|
|
|
|
```powershell
|
|
$env:AZURE_OPENAI_API_KEY="your-api-key"
|
|
```
|
|
|
|
### Start Durable Task Scheduler
|
|
|
|
Most samples use the Durable Task Scheduler (DTS) to support hosted agents and durable orchestrations. DTS also allows you to view the status of orchestrations and their inputs and outputs from a web UI.
|
|
|
|
To run the Durable Task Scheduler locally, you can use the following `docker` command:
|
|
|
|
```bash
|
|
docker run -d --name dts-emulator -p 8080:8080 -p 8082:8082 mcr.microsoft.com/dts/dts-emulator:latest
|
|
```
|
|
|
|
The DTS dashboard will be available at `http://localhost:8082`.
|
|
|
|
### Environment Configuration
|
|
|
|
Each sample reads configuration from environment variables. You'll need to set the following environment variables:
|
|
|
|
Bash (Linux/macOS/WSL):
|
|
|
|
```bash
|
|
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
|
|
export AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="your-deployment-name"
|
|
```
|
|
|
|
PowerShell:
|
|
|
|
```powershell
|
|
$env:AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
|
|
$env:AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="your-deployment-name"
|
|
```
|
|
|
|
### Installing Dependencies
|
|
|
|
Navigate to the sample directory and install dependencies. For example:
|
|
|
|
```bash
|
|
cd samples/04-hosting/durabletask/01_single_agent
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
If you're using `uv` for package management:
|
|
|
|
```bash
|
|
uv pip install -r requirements.txt
|
|
```
|
|
|
|
### Running the Samples
|
|
|
|
Each sample follows a worker-client architecture. Most samples provide separate `worker.py` and `client.py` files, though some include a combined `sample.py` for convenience.
|
|
|
|
**Running with separate worker and client:**
|
|
|
|
In one terminal, start the worker:
|
|
|
|
```bash
|
|
python worker.py
|
|
```
|
|
|
|
In another terminal, run the client:
|
|
|
|
```bash
|
|
python client.py
|
|
```
|
|
|
|
**Running with combined sample:**
|
|
|
|
```bash
|
|
python sample.py
|
|
```
|
|
|
|
### Viewing the Sample Output
|
|
|
|
The sample output is displayed directly in the terminal where you ran the Python script. Agent responses are printed to stdout with log formatting for better readability.
|
|
|
|
You can also see the state of agents and orchestrations in the Durable Task Scheduler dashboard at `http://localhost:8082`.
|
|
|