mirror of https://github.com/microsoft/agent-framework.git synced 2026-06-16 21:04:09 +08:00

Files

T

Tao Chen ce8b6305d8 Python: Foundry hosted agent V2 (#5379 )

* Python: Wrapper + Samples 1st (#5177)

* Experiment

* Update dependency and add non streaming

* Add more samples

* Rename samples

* Add invocations

* Comments 1

* Comments 2

* Comments 3

* Improve README

* Add local shell sample

* WIP: Add eval and memory samples

* Update user agent prefix

* Update user agent prefix doc

* Update dependency (#5215)

* Add tests and more content types (#5235)

* Add tests

* fix tests and sample

* Fix formatting

* Remove function approval contents

* Python: Refine samples and upgrade packages (#5261)

* Refine samples and upgrade pacakges

* Upgrade to a new package that fixes a bug

* Update model env var

* Move samples (#5281)

* Python: Upgrade agentserver packages (#5284)

* Upgrade agentserver packages

* Fix new types

* Python: Add special handling for workflows (#5298)

* Add special handling for workflows

* Address comments

* Improve samples (#5372)

* Python: Add more types (#5378)

* Add more type supports

* Upgrade packages

* Remove TODOs in README

* Fix README

* Comments and mypy

* User agent scoped

* Fix README

* Fix pre commit

* Fix pre commit 2

* Fix pre commit 3

* Fix pre commit 4

* Fix pre commit 5

* Fix pre commit 6

* Add azure-monitor-opentelemetry to dev deps

Fixes Samples & Markdown CI failure. The PR's new transitive dep on
azure-monitor-opentelemetry-exporter (via azure-ai-agentserver-core) makes
pyright resolve the azure.monitor.opentelemetry namespace, flipping the
check_md_code_blocks diagnostic for `configure_azure_monitor` from
reportMissingImports (filtered) to reportAttributeAccessIssue (not filtered).
Installing the umbrella azure-monitor-opentelemetry package in dev makes
pyright resolve the symbol correctly, matching the install guidance the
observability README already gives users.

---------

Co-authored-by: Evan Mattson <evan.mattson@microsoft.com>

ce8b6305d8 · 2026-04-21 05:21:27 +00:00

History

01-get-started

Python: [BREAKING] update to v1.0.0 (#5062 )

2026-04-02 15:26:30 +00:00

02-agents

Python: Foundry hosted agent V2 (#5379 )

2026-04-21 05:21:27 +00:00

03-workflows

Python: Stop emitting duplicate reasoning content from OpenAI response.reasoning_text.done and response.reasoning_summary_text.done events (#5162 )

2026-04-09 22:44:59 +00:00

04-hosting

Python: Foundry hosted agent V2 (#5379 )

2026-04-21 05:21:27 +00:00

05-end-to-end

Python: Foundry hosted agent V2 (#5379 )

2026-04-21 05:21:27 +00:00

autogen-migration

Fix handoff workflow context management and improve AG-UI demo (#5136 )

2026-04-08 04:08:24 +00:00

semantic-kernel-migration

Fix handoff workflow context management and improve AG-UI demo (#5136 )

2026-04-08 04:08:24 +00:00

shared

Python: Phase 2: Embedding clients for Ollama, Bedrock, and Azure AI Inference (#4207 )

2026-02-25 17:45:08 +00:00

__init__.py

Python telemetry (#223 )

2025-07-28 07:33:42 +00:00

AGENTS.md

Python: [BREAKING] update to v1.0.0 (#5062 )

2026-04-02 15:26:30 +00:00

README.md

Python: [BREAKING] update to v1.0.0 (#5062 )

2026-04-02 15:26:30 +00:00

SAMPLE_GUIDELINES.md

Python: [BREAKING] Python: Provider-leading client design & OpenAI package extraction (#4818 )

2026-03-25 09:56:29 +00:00

README.md

Python Samples

This directory contains samples demonstrating the capabilities of Microsoft Agent Framework for Python.

Structure

Folder	Description
`01-get-started/`	Progressive tutorial: hello agent → hosting
`02-agents/`	Deep-dive by concept: tools, middleware, providers, orchestrations
`03-workflows/`	Workflow patterns: sequential, concurrent, state, declarative
`04-hosting/`	Deployment: Azure Functions, Durable Tasks, A2A
`05-end-to-end/`	Full applications, evaluation, demos

Getting Started

Start with 01-get-started/ and work through the numbered files:

01_hello_agent.py — Create and run your first agent
02_add_tools.py — Add function tools with @tool
03_multi_turn.py — Multi-turn conversations with AgentSession
04_memory.py — Agent memory with ContextProvider
05_first_workflow.py — Build a workflow with executors and edges
06_host_your_agent.py — Host your agent via Azure Functions

Prerequisites

pip install agent-framework

Environment Variables

Samples call load_dotenv() to automatically load environment variables from a .env file in the python/ directory. This is a convenience for local development and testing.

For local development, set up your environment using any of these methods:

Option 1: Using a .env file (recommended for local development):

Copy .env.example to .env in the python/ directory:
```
cp .env.example .env
```
Edit .env and set your values (API keys, endpoints, etc.)

Option 2: Export environment variables directly:

export FOUNDRY_PROJECT_ENDPOINT="your-foundry-project-endpoint"
export FOUNDRY_MODEL="gpt-4o"

Option 3: Using env_file_path parameter (for per-client configuration):

All client classes (e.g., OpenAIChatClient, OpenAIChatCompletionClient) support an env_file_path parameter to load environment variables from a specific file:

from agent_framework.openai import OpenAIChatClient

# Load from a custom .env file
client = OpenAIChatClient(env_file_path="path/to/custom.env")

This allows different clients to use different configuration files if needed.

For the generic OpenAI clients (OpenAIChatClient and OpenAIChatCompletionClient), routing precedence is:

Explicit Azure inputs such as credential, azure_endpoint, or api_version
OPENAI_API_KEY / explicit OpenAI API-key parameters
Azure environment fallback such as AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_API_KEY

If you keep both OpenAI and Azure variables in your shell, the generic clients stay on OpenAI until you pass an explicit Azure input.

For the getting-started samples, you'll need at minimum:

FOUNDRY_PROJECT_ENDPOINT="your-foundry-project-endpoint"
FOUNDRY_MODEL="gpt-4o"

Consolidated sample env inventory

This is the single source of truth for package-level environment variables read by packages included by agent-framework-core[all]. It intentionally excludes variables that are only read by standalone samples, package sample folders, or tests. When package code adds, removes, or renames an environment variable, update this table in the same change.

Example values below are illustrative. For entries not backed by a single public class, the class column names the closest public surface, helper, or package-level initialization point that reads the variable.

package	class	env var	example value
`agent-framework-anthropic`	`AnthropicClient`	`ANTHROPIC_API_KEY`	`sk-ant-api03-...`
`agent-framework-anthropic`	`AnthropicClient`	`ANTHROPIC_CHAT_MODEL`	`claude-sonnet-4-5-20250929`
`agent-framework-foundry`	`FoundryEmbeddingClient`	`FOUNDRY_MODELS_ENDPOINT`	`https://my-endpoint.inference.ai.azure.com`
`agent-framework-foundry`	`FoundryEmbeddingClient`	`FOUNDRY_MODELS_API_KEY`	`env-key`
`agent-framework-foundry`	`FoundryEmbeddingClient`	`FOUNDRY_EMBEDDING_MODEL`	`text-embedding-3-small`
`agent-framework-foundry`	`FoundryEmbeddingClient`	`FOUNDRY_IMAGE_EMBEDDING_MODEL`	`Cohere-embed-v3-english`
`agent-framework-azure-ai-search`	`AzureAISearchContextProvider`	`AZURE_SEARCH_ENDPOINT`	`https://my-search.search.windows.net`
`agent-framework-azure-ai-search`	`AzureAISearchContextProvider`	`AZURE_SEARCH_API_KEY`	`search-key`
`agent-framework-azure-ai-search`	`AzureAISearchContextProvider`	`AZURE_SEARCH_INDEX_NAME`	`hotels-index`
`agent-framework-azure-ai-search`	`AzureAISearchContextProvider`	`AZURE_SEARCH_KNOWLEDGE_BASE_NAME`	`hotels-kb`
`agent-framework-azure-cosmos`	`CosmosHistoryProvider`	`AZURE_COSMOS_ENDPOINT`	`https://my-cosmos.documents.azure.com:443/`
`agent-framework-azure-cosmos`	`CosmosHistoryProvider`	`AZURE_COSMOS_DATABASE_NAME`	`agent-history`
`agent-framework-azure-cosmos`	`CosmosHistoryProvider`	`AZURE_COSMOS_CONTAINER_NAME`	`messages`
`agent-framework-azure-cosmos`	`CosmosHistoryProvider`	`AZURE_COSMOS_KEY`	`C2F...==`
`agent-framework-bedrock`	`BedrockChatClient`	`BEDROCK_REGION`	`us-east-1`
`agent-framework-bedrock`	`BedrockChatClient`	`BEDROCK_CHAT_MODEL`	`anthropic.claude-3-5-sonnet-20241022-v2:0`
`agent-framework-bedrock`	`BedrockEmbeddingClient`	`BEDROCK_REGION`	`us-east-1`
`agent-framework-bedrock`	`BedrockEmbeddingClient`	`BEDROCK_EMBEDDING_MODEL`	`amazon.titan-embed-text-v2:0`
`agent-framework-bedrock`	`BedrockChatClient / BedrockEmbeddingClient`	`AWS_ACCESS_KEY_ID`	`AKIAIOSFODNN7EXAMPLE`
`agent-framework-bedrock`	`BedrockChatClient / BedrockEmbeddingClient`	`AWS_SECRET_ACCESS_KEY`	`wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY`
`agent-framework-bedrock`	`BedrockChatClient / BedrockEmbeddingClient`	`AWS_SESSION_TOKEN`	`IQoJb3JpZ2luX2VjEO7//////////wEaCXVzLXdlc3QtMiJHMEUCIQD...`
`agent-framework-copilotstudio`	`CopilotStudioAgent`	`COPILOTSTUDIOAGENT__ENVIRONMENTID`	`00000000-0000-0000-0000-000000000000`
`agent-framework-copilotstudio`	`CopilotStudioAgent`	`COPILOTSTUDIOAGENT__SCHEMANAME`	`cr123_agentname`
`agent-framework-copilotstudio`	`CopilotStudioAgent`	`COPILOTSTUDIOAGENT__TENANTID`	`11111111-1111-1111-1111-111111111111`
`agent-framework-copilotstudio`	`CopilotStudioAgent`	`COPILOTSTUDIOAGENT__AGENTAPPID`	`22222222-2222-2222-2222-222222222222`
`agent-framework-core`	`enable_instrumentation()`	`ENABLE_INSTRUMENTATION`	`true`
`agent-framework-core`	`enable_instrumentation()`	`ENABLE_SENSITIVE_DATA`	`false`
`agent-framework-core`	`enable_instrumentation()`	`ENABLE_CONSOLE_EXPORTERS`	`true`
`agent-framework-core`	`enable_instrumentation()`	`OTEL_EXPORTER_OTLP_ENDPOINT`	`http://localhost:4317`
`agent-framework-core`	`enable_instrumentation()`	`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	`http://localhost:4318/v1/traces`
`agent-framework-core`	`enable_instrumentation()`	`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`	`http://localhost:4318/v1/metrics`
`agent-framework-core`	`enable_instrumentation()`	`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`	`http://localhost:4318/v1/logs`
`agent-framework-core`	`enable_instrumentation()`	`OTEL_EXPORTER_OTLP_PROTOCOL`	`grpc`
`agent-framework-core`	`enable_instrumentation()`	`OTEL_EXPORTER_OTLP_HEADERS`	`api-key=demo`
`agent-framework-core`	`enable_instrumentation()`	`OTEL_EXPORTER_OTLP_TRACES_HEADERS`	`api-key=trace-demo`
`agent-framework-core`	`enable_instrumentation()`	`OTEL_EXPORTER_OTLP_METRICS_HEADERS`	`api-key=metric-demo`
`agent-framework-core`	`enable_instrumentation()`	`OTEL_EXPORTER_OTLP_LOGS_HEADERS`	`api-key=log-demo`
`agent-framework-core`	`enable_instrumentation()`	`OTEL_SERVICE_NAME`	`sample-agent`
`agent-framework-core`	`enable_instrumentation()`	`OTEL_SERVICE_VERSION`	`1.0.0`
`agent-framework-core`	`enable_instrumentation()`	`OTEL_RESOURCE_ATTRIBUTES`	`deployment.environment=dev,service.namespace=agent-framework`
`agent-framework-devui`	`DevUI server`	`DEVUI_AUTH_TOKEN`	`my-devui-token`
`agent-framework-foundry`	`FoundryChatClient`	`FOUNDRY_PROJECT_ENDPOINT`	`https://my-project.services.ai.azure.com/api/projects/my-project`
`agent-framework-foundry`	`FoundryChatClient`	`FOUNDRY_MODEL`	`gpt-4o`
`agent-framework-foundry`	`FoundryAgent`	`FOUNDRY_AGENT_NAME`	`travel-planner`
`agent-framework-foundry`	`FoundryAgent`	`FOUNDRY_AGENT_VERSION`	`v1`
`agent-framework-github-copilot`	`GitHubCopilotAgent`	`GITHUB_COPILOT_CLI_PATH`	`copilot`
`agent-framework-github-copilot`	`GitHubCopilotAgent`	`GITHUB_COPILOT_MODEL`	`gpt-5`
`agent-framework-github-copilot`	`GitHubCopilotAgent`	`GITHUB_COPILOT_TIMEOUT`	`60`
`agent-framework-github-copilot`	`GitHubCopilotAgent`	`GITHUB_COPILOT_LOG_LEVEL`	`info`
`agent-framework-mem0`	`agent_framework_mem0 package import`	`MEM0_TELEMETRY`	`false`
`agent-framework-ollama`	`OllamaChatClient`	`OLLAMA_HOST`	`http://localhost:11434`
`agent-framework-ollama`	`OllamaChatClient`	`OLLAMA_MODEL`	`llama3.1:8b`
`agent-framework-openai`	`OpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClient`	`OPENAI_API_KEY`	`sk-proj-...`
`agent-framework-openai`	`OpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClient`	`OPENAI_MODEL`	`gpt-4o-mini`
`agent-framework-openai`	`OpenAIChatClient`	`OPENAI_CHAT_MODEL`	`gpt-4.1-mini`
`agent-framework-openai`	`OpenAIChatCompletionClient`	`OPENAI_CHAT_COMPLETION_MODEL`	`gpt-4o`
`agent-framework-openai`	`OpenAIEmbeddingClient`	`OPENAI_EMBEDDING_MODEL`	`text-embedding-3-small`
`agent-framework-openai`	`OpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClient`	`OPENAI_BASE_URL`	`https://api.openai.com/v1/`
`agent-framework-openai`	`OpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClient`	`OPENAI_ORG_ID`	`org_123456789`
`agent-framework-openai`	`OpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClient`	`AZURE_OPENAI_ENDPOINT`	`https://my-resource.openai.azure.com/`
`agent-framework-openai`	`OpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClient`	`AZURE_OPENAI_API_KEY`	`sk-azure-...`
`agent-framework-openai`	`OpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClient`	`AZURE_OPENAI_API_VERSION`	`2024-10-21`
`agent-framework-openai`	`OpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClient`	`AZURE_OPENAI_BASE_URL`	`https://my-resource.openai.azure.com/openai/v1/`
`agent-framework-openai`	`OpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClient`	`AZURE_OPENAI_MODEL`	`gpt-4o`
`agent-framework-openai`	`OpenAIChatClient`	`AZURE_OPENAI_CHAT_MODEL`	`gpt-4.1`
`agent-framework-openai`	`OpenAIChatCompletionClient`	`AZURE_OPENAI_CHAT_COMPLETION_MODEL`	`gpt-4o-mini`
`agent-framework-openai`	`OpenAIEmbeddingClient`	`AZURE_OPENAI_EMBEDDING_MODEL`	`text-embedding-3-large`
`agent-framework-openai`	`OpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClient`	`AZURE_OPENAI_RESOURCE_URL`	`https://cognitiveservices.azure.com/`

agent-framework-openai supports the Azure OpenAI client-specific deployment aliases listed above; keep packages/openai/README.md as the authoritative reference for the exact fallback order and package-specific behavior.

Note for production: In production environments, set environment variables through your deployment platform (e.g., Azure App Settings, Kubernetes ConfigMaps/Secrets) rather than using .env files. The load_dotenv() call in samples will have no effect when a .env file is not present, allowing environment variables to be loaded from the system.

For Azure authentication, run az login before running samples.

Note on XML tags

Some sample files include XML-style snippet tags (for example <snippet_name> and </snippet_name>). These are used by our documentation tooling and can be ignored or removed when you use the samples outside this repository.

Additional Resources

Agent Framework Documentation
AGENTS.md — Structure documentation for maintainers
SAMPLE_GUIDELINES.md — Coding conventions for samples