mirror of
https://github.com/microsoft/agent-framework.git
synced 2026-06-16 21:04:09 +08:00
Eduard van Valkenburg
838a7fd61d
* Replace Role and FinishReason classes with NewType + Literal
- Remove EnumLike metaclass from _types.py
- Replace Role class with NewType('Role', str) + RoleLiteral
- Replace FinishReason class with NewType('FinishReason', str) + FinishReasonLiteral
- Update all usages across codebase to use string literals
- Remove .value access patterns (direct string comparison now works)
- Add backward compatibility for legacy dict serialization format
- Update tests to reflect new string-based types
Addresses #3591, #3615
* Simplify ChatResponse and AgentResponse type hints (#3592)
- Remove overloads from ChatResponse.__init__
- Remove text parameter from ChatResponse.__init__
- Remove | dict[str, Any] from finish_reason and usage_details params
- Remove **kwargs from AgentResponse.__init__
- Both now accept ChatMessage | Sequence[ChatMessage] | None for messages
- Update docstrings and examples to reflect changes
- Fix tests that were using removed kwargs
- Fix Role type hint usage in ag-ui utils
* Remove text parameter from ChatResponseUpdate and AgentResponseUpdate (#3597)
- Remove text parameter from ChatResponseUpdate.__init__
- Remove text parameter from AgentResponseUpdate.__init__
- Remove **kwargs from both update classes
- Simplify contents parameter type to Sequence[Content] | None
- Update all usages to use contents=[Content.from_text(...)] pattern
- Fix imports in test files
- Update docstrings and examples
* Rename from_chat_response_updates to from_updates (#3593)
- ChatResponse.from_chat_response_updates โ ChatResponse.from_updates
- ChatResponse.from_chat_response_generator โ ChatResponse.from_update_generator
- AgentResponse.from_agent_run_response_updates โ AgentResponse.from_updates
* Remove try_parse_value method from ChatResponse and AgentResponse (#3595)
- Remove try_parse_value method from ChatResponse
- Remove try_parse_value method from AgentResponse
- Remove try_parse_value calls from from_updates and from_update_generator methods
- Update samples to use try/except with response.value instead
- Update tests to use response.value pattern
- Users should now use response.value with try/except for safe parsing
* Add agent_id to AgentResponse and clarify author_name documentation (#3596)
- Add agent_id parameter to AgentResponse class
- Document that author_name is on ChatMessage objects, not responses
- Update ChatResponse docstring with author_name note
- Update AgentResponse docstring with author_name note
* Simplify ChatMessage.__init__ signature (#3618)
- Make contents a positional argument accepting Sequence[Content | str]
- Auto-convert strings in contents to TextContent
- Remove overloads, keep text kwarg for backward compatibility with serialization
- Update _parse_content_list to handle string items
- Update all usages across codebase to use new format: ChatMessage("role", ["text"])
* Allow Content as input on run and get_response
- Update prepare_messages and normalize_messages to accept Content
- Update type signatures in _agents.py and _clients.py
- Add tests for Content input handling
* Fix ChatMessage usage across packages and samples
Update all remaining ChatMessage(role=..., text=...) to use new
ChatMessage('role', ['text']) signature.
* Fix Role string usage and response format parsing
- Fix redis provider: remove .value access on string literals
- Fix durabletask ensure_response_format: set _response_format before accessing .value
* Fix ollama .value and ai_model_id issues, handle None in content list
- Fix ollama _chat_client: remove .value on string literals
- Fix ollama _chat_client: rename ai_model_id to model_id
- Fix _parse_content_list: skip None values gracefully
* Fix A2AAgent type signature to include Content
* Fix Role/FinishReason NewType dict annotations and improve test coverage to 95%
* Fix mypy errors for Role/FinishReason NewType usage
* Fix Role.TOOL and Role.ASSISTANT usage in _orchestrator_helpers.py
* Fix Role NewType usage in durabletask _models.py
838a7fd61d
ยท
2026-02-04 10:13:23 +00:00
History
Python Samples
This directory contains samples demonstrating the capabilities of Microsoft Agent Framework for Python.
Agents
A2A (Agent-to-Agent)
| File | Description |
|---|---|
getting_started/agents/a2a/agent_with_a2a.py |
Agent2Agent (A2A) Protocol Integration Sample |
Anthropic
| File | Description |
|---|---|
getting_started/agents/anthropic/anthropic_basic.py |
Agent with Anthropic Client |
getting_started/agents/anthropic/anthropic_advanced.py |
Advanced sample with thinking and hosted tools. |
Azure AI (based on azure-ai-agents V1 package)
Azure AI (based on azure-ai-projects V2 package)
Azure OpenAI
Copilot Studio
| File | Description |
|---|---|
getting_started/agents/copilotstudio/copilotstudio_basic.py |
Copilot Studio Agent Basic Example |
getting_started/agents/copilotstudio/copilotstudio_with_explicit_settings.py |
Copilot Studio Agent with Explicit Settings Example |
Custom
| File | Description |
|---|---|
getting_started/agents/custom/custom_agent.py |
Custom Agent Implementation Example |
getting_started/agents/custom/custom_chat_client.py |
Custom Chat Client Implementation Example |
Ollama
The recommended way to use Ollama is via the native OllamaChatClient from the agent-framework-ollama package.
| File | Description |
|---|---|
getting_started/agents/ollama/ollama_agent_basic.py |
Basic Ollama Agent with native Ollama Chat Client |
getting_started/agents/ollama/ollama_agent_reasoning.py |
Ollama Agent with reasoning capabilities |
getting_started/agents/ollama/ollama_chat_client.py |
Direct usage of Ollama Chat Client |
getting_started/agents/ollama/ollama_chat_multimodal.py |
Ollama Chat Client with multimodal (image) input |
getting_started/agents/ollama/ollama_with_openai_chat_client.py |
Alternative: Ollama via OpenAI Chat Client |
OpenAI
Chat Client
| File | Description |
|---|---|
getting_started/chat_client/azure_ai_chat_client.py |
Azure AI Chat Client Direct Usage Example |
getting_started/chat_client/azure_assistants_client.py |
Azure OpenAI Assistants Client Direct Usage Example |
getting_started/chat_client/azure_chat_client.py |
Azure Chat Client Direct Usage Example |
getting_started/chat_client/azure_responses_client.py |
Azure OpenAI Responses Client Direct Usage Example |
getting_started/chat_client/chat_response_cancellation.py |
Chat Response Cancellation Example |
getting_started/chat_client/openai_assistants_client.py |
OpenAI Assistants Client Direct Usage Example |
getting_started/chat_client/openai_chat_client.py |
OpenAI Chat Client Direct Usage Example |
getting_started/chat_client/openai_responses_client.py |
OpenAI Responses Client Direct Usage Example |
Context Providers
Mem0
| File | Description |
|---|---|
getting_started/context_providers/mem0/mem0_basic.py |
Basic Mem0 integration example |
getting_started/context_providers/mem0/mem0_oss.py |
Mem0 OSS (Open Source) integration example |
getting_started/context_providers/mem0/mem0_threads.py |
Mem0 with thread management example |
Redis
| File | Description |
|---|---|
getting_started/context_providers/redis/redis_basics.py |
Basic Redis provider example |
getting_started/context_providers/redis/redis_conversation.py |
Redis conversation context management example |
getting_started/context_providers/redis/redis_threads.py |
Redis with thread management example |
Other
| File | Description |
|---|---|
getting_started/context_providers/simple_context_provider.py |
Simple context provider implementation example |
getting_started/context_providers/aggregate_context_provider.py |
Shows how to combine multiple context providers using an AggregateContextProvider |
Declarative
| File | Description |
|---|---|
getting_started/declarative/azure_openai_responses_agent.py |
Basic agent using Azure OpenAI with structured responses |
getting_started/declarative/get_weather_agent.py |
Agent with custom function tools using declarative bindings |
getting_started/declarative/inline_yaml.py |
Agent created from inline YAML string |
getting_started/declarative/mcp_tool_yaml.py |
MCP tool configuration with API key and Azure Foundry connection auth |
getting_started/declarative/microsoft_learn_agent.py |
Agent with MCP server integration for Microsoft Learn documentation |
getting_started/declarative/openai_responses_agent.py |
Basic agent using OpenAI directly |
DevUI
| File | Description |
|---|---|
getting_started/devui/fanout_workflow/workflow.py |
Complex fan-out/fan-in workflow example |
getting_started/devui/foundry_agent/agent.py |
Azure AI Foundry agent example |
getting_started/devui/in_memory_mode.py |
In-memory mode example for DevUI |
getting_started/devui/spam_workflow/workflow.py |
Spam detection workflow example |
getting_started/devui/weather_agent_azure/agent.py |
Weather agent using Azure OpenAI example |
getting_started/devui/workflow_agents/workflow.py |
Workflow with multiple agents example |
Evaluation
| File | Description |
|---|---|
getting_started/evaluation/red_teaming/red_team_agent_sample.py |
Red team agent evaluation sample for Azure AI Foundry |
getting_started/evaluation/self_reflection/self_reflection.py |
LLM self-reflection with AI Foundry graders example |
demos/workflow_evaluation/run_evaluation.py |
Multi-agent workflow evaluation demo with travel planning agents evaluated using Azure AI Foundry evaluators |
MCP (Model Context Protocol)
| File | Description |
|---|---|
getting_started/mcp/agent_as_mcp_server.py |
Agent as MCP Server Example |
getting_started/mcp/mcp_api_key_auth.py |
MCP Authentication Example |
Middleware
Multimodal Input
| File | Description |
|---|---|
getting_started/multimodal_input/azure_chat_multimodal.py |
Azure OpenAI Chat with multimodal (image) input example |
getting_started/multimodal_input/azure_responses_multimodal.py |
Azure OpenAI Responses with multimodal (image) input example |
getting_started/multimodal_input/openai_chat_multimodal.py |
OpenAI Chat with multimodal (image) input example |
Azure Functions
| Sample | Description |
|---|---|
getting_started/azure_functions/01_single_agent/ |
Host a single agent in Azure Functions with Durable Extension HTTP endpoints and per-session state. |
getting_started/azure_functions/02_multi_agent/ |
Register multiple agents in one function app with dedicated run routes and a health check endpoint. |
getting_started/azure_functions/03_reliable_streaming/ |
Implement reliable streaming for durable agents using Redis Streams with cursor-based resumption. |
getting_started/azure_functions/04_single_agent_orchestration_chaining/ |
Chain sequential agent executions inside a durable orchestration while preserving the shared thread context. |
getting_started/azure_functions/05_multi_agent_orchestration_concurrency/ |
Run two agents concurrently within a durable orchestration and combine their domain-specific outputs. |
getting_started/azure_functions/06_multi_agent_orchestration_conditionals/ |
Route orchestration logic based on structured agent responses for spam detection and reply drafting. |
getting_started/azure_functions/07_single_agent_orchestration_hitl/ |
Implement a human-in-the-loop approval loop that iterates on agent output inside a durable orchestration. |
getting_started/azure_functions/08_mcp_server/ |
Configure agents as both HTTP endpoints and MCP tools for flexible integration patterns. |
Durable Task
These samples demonstrate durable agent hosting using the Durable Task Scheduler with a worker-client architecture pattern, enabling distributed agent execution with persistent conversation state.
| Sample | Description |
|---|---|
getting_started/durabletask/01_single_agent/ |
Host a single conversational agent with worker-client architecture and agent state management. |
getting_started/durabletask/02_multi_agent/ |
Host multiple domain-specific agents and route requests based on question topic. |
getting_started/durabletask/03_single_agent_streaming/ |
Implement reliable streaming using Redis Streams with cursor-based resumption for durable agents. |
getting_started/durabletask/04_single_agent_orchestration_chaining/ |
Chain multiple agent invocations using durable orchestration while preserving conversation context. |
getting_started/durabletask/05_multi_agent_orchestration_concurrency/ |
Run multiple agents concurrently within an orchestration and aggregate their responses. |
getting_started/durabletask/06_multi_agent_orchestration_conditionals/ |
Implement conditional branching with spam detection using structured outputs and activity functions. |
getting_started/durabletask/07_single_agent_orchestration_hitl/ |
Human-in-the-loop pattern with external event handling, timeouts, and iterative refinement. |
Observability
| File | Description |
|---|---|
getting_started/observability/advanced_manual_setup_console_output.py |
Advanced manual observability setup with console output |
getting_started/observability/advanced_zero_code.py |
Zero-code observability setup example |
getting_started/observability/agent_observability.py |
Agent observability example |
getting_started/observability/agent_with_foundry_tracing.py |
Any chat client setup with Azure Foundry Observability |
getting_started/observability/azure_ai_agent_observability.py |
Azure AI agent observability example |
getting_started/observability/configure_otel_providers_with_env_var.py |
Setup observability using environment variables |
getting_started/observability/configure_otel_providers_with_parameters.py |
Setup observability using parameters |
getting_started/observability/workflow_observability.py |
Workflow observability example |
Threads
| File | Description |
|---|---|
getting_started/threads/custom_chat_message_store_thread.py |
Implementation of custom chat message store state |
getting_started/threads/redis_chat_message_store_thread.py |
Basic example of using Redis chat message store |
getting_started/threads/suspend_resume_thread.py |
Demonstrates how to suspend and resume a service-managed thread |
Tools
Note: Many tool samples set approval_mode="never_require" to keep the examples concise. For production scenarios,
keep approval_mode="always_require" unless you are confident in the tool behavior and approval flow. See
getting_started/tools/function_tool_with_approval.py and
getting_started/tools/function_tool_with_approval_and_threads.py, plus the workflow approval samples in
getting_started/workflows/tool-approval/, for end-to-end approval handling.
| File | Description |
|---|---|
getting_started/tools/function_tool_declaration_only.py |
Function declarations without implementations for testing agent reasoning |
getting_started/tools/function_tool_from_dict_with_dependency_injection.py |
Creating local tools from dictionary definitions using dependency injection |
getting_started/tools/function_tool_recover_from_failures.py |
Graceful error handling when tools raise exceptions |
getting_started/tools/function_tool_with_approval.py |
User approval workflows for function calls without threads |
getting_started/tools/function_tool_with_approval_and_threads.py |
Tool approval workflows using threads for conversation history management |
getting_started/tools/function_tool_with_max_exceptions.py |
Limiting tool failure exceptions using max_invocation_exceptions |
getting_started/tools/function_tool_with_max_invocations.py |
Limiting total tool invocations using max_invocations |
getting_started/tools/tool_in_class.py |
Using the tool decorator with class methods for stateful tools |
Workflows
View the list of Workflows samples here.
Sample Guidelines
For information on creating new samples, see SAMPLE_GUIDELINES.md.