agent/agent-framework
1
0
Fork 0
mirror of https://github.com/microsoft/agent-framework.git synced 2026-06-16 21:04:09 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
feature/hosted-dwf
agent-framework/python/samples
T
Evan Mattson 866a325b48 Python: [BREAKING] Standardize orchestration terminal outputs as AgentResponse (#5301) 
* Fix orchestration outputs so as_agent() returns the final answer only. Align other orchestration outputs

* Fix orchestration output issues from review comments

1. Sample cleanup: Remove commented-out FoundryChatClient block and update
   prerequisites to reference OPENAI_CHAT_MODEL_ID instead of FOUNDRY_* vars.

2. Sequential approval output: Change _EndWithConversation.end_with_agent_executor_response
   from a no-op sink to yield response.agent_response. When the last participant is
   AgentApprovalExecutor (via with_request_info), _EndWithConversation is the output
   executor so the yield produces the terminal answer. When the last participant is a
   regular AgentExecutor, _EndWithConversation is not in output_executors so the yield
   is silently filtered out.

3. Forward data events through WorkflowExecutor: _process_workflow_result now also
   forwards 'data' events from sub-workflows so that emit_intermediate_data=True on
   AgentExecutor works correctly when wrapped in AgentApprovalExecutor.

4. Concurrent docstring: Update _AggregateAgentConversations docstring to say
   'deterministic participant order' instead of 'completion order'.

5. Add test_concurrent_intermediate_outputs_emits_data_events verifying that
   ConcurrentBuilder(intermediate_outputs=True) emits per-participant data events
   alongside the single aggregated output event.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Add tests for sequential workflow with_request_info and intermediate_outputs (#5301)

Address PR review comments 2, 3, and 5:

- Add test_sequential_request_info_last_participant_emits_output:
  Verifies that when the last participant is wrapped via with_request_info()
  (AgentApprovalExecutor), the workflow still emits a terminal output after
  approval, exercising the _EndWithConversation.end_with_agent_executor_response
  fallback path.

- Add test_sequential_request_info_with_intermediate_outputs_emits_data_events:
  Verifies that emit_intermediate_data=True works correctly through
  AgentApprovalExecutor wrapping—WorkflowExecutor._process_result already
  forwards data events from sub-workflows, so intermediate agent responses
  surface as data events in the parent workflow.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix pyright type errors from AgentResponse output refactor (#5301)

Update cast() calls in _group_chat.py and _magentic.py to use
WorkflowContext[Never, AgentResponse] instead of the old
WorkflowContext[Never, list[Message]], matching the updated method
signatures in _base_group_chat_orchestrator.py.

Fix _sequential.py _EndWithConversation.end_with_agent_executor_response
to declare WorkflowContext[Any, AgentResponse] so yield_output accepts
AgentResponse[None].

Fix _workflow_executor.py data event forwarding to handle nullable
executor_id.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix pyright reportUnknownVariableType in _agent.py (#5301)

Extract event.data into a typed local variable before the isinstance
check to avoid pyright narrowing it to AgentResponse[Unknown].

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix pyright reportMissingImports for orjson in file history samples (#5301)

Add pyright: ignore[reportMissingImports] to orjson imports that are
already guarded by try/except ImportError, matching the existing pattern
used elsewhere in the samples.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Address review feedback for #5301: review comment fixes

* Address review feedback for #5301: review comment fixes

* Revert sequential_workflow_as_agent sample to FoundryChatClient

Reverts the mistaken switch from FoundryChatClient to OpenAIChatClient
in the sequential workflow as agent sample.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Address ultrareview feedback: emit_data_events rename + WorkflowAgent reasoning conversion

Layered on top of the prior review-feedback work in this branch.

Renames:
- AgentExecutor.emit_intermediate_data -> emit_data_events (mechanical
  rename; orchestration semantics live at the orchestration layer, not
  the general-purpose executor). Forwarded through MagenticAgentExecutor,
  AgentApprovalExecutor, and all orchestration call sites.
- HandoffAgentExecutor._check_terminate_and_yield -> _should_terminate
  (pure predicate; no longer yields anything). HandoffBuilder docstring
  rewritten to describe the new per-agent AgentResponse output contract.

WorkflowAgent reasoning-content conversion:
- Add _rewrite_text_to_reasoning(contents) and _msg_as_reasoning(msg)
  helpers; the as_agent() path now reframes text content from data events
  as text_reasoning Content blocks before merging into the AgentResponse.
- Consumers iterate msg.contents and branch on content.type — same path
  they already use for Claude thinking and OpenAI reasoning. No new
  field on Message/AgentResponse/WorkflowEvent.
- Streaming branch constructs fresh AgentResponseUpdate instances instead
  of mutating shared payloads (regression test added).
- Helper _msg_maybe_reasoning consolidates the conditional rewrite at
  three call sites in the non-streaming conversion.

Tests:
- TestWorkflowAgentReasoningHelpers + TestWorkflowAgentDataEventReasoningConversion
  add 9 new tests covering helpers, non-streaming, streaming, mixed content,
  already-reasoning passthrough, and mutation-safety regression.
- Updated test_sequential_as_agent_with_intermediate_outputs_includes_chain
  to assert text_reasoning content for intermediate agents.

* Fix pyright: widen event.data to Any to avoid partial-unknown narrowing

The streaming conversion path narrowed event.data via isinstance against
generic AgentResponse, producing AgentResponse[Unknown] and tripping
reportUnknownVariableType/reportUnknownMemberType. Binding data: Any
before the check keeps runtime behavior identical while restoring a fully
known type for downstream access.

* Clean up design

* Scope to agent output semantics only

* yield AgentResponseUpdate streaming, AgentResponse non-streaming

* Fix mypy/pyright: widen cast types at GroupChat callsites

Eight callsites in _group_chat.py still cast to WorkflowContext[Never,
AgentResponse] but the base orchestrator methods now accept the wider
WorkflowContext[Never, AgentResponse | AgentResponseUpdate] (mode-aware
yields). W_OutT is invariant, so the narrower cast is not assignable.
Magentic was widened in the same commit; this catches the GroupChat
callsites that were missed.

* Python: skip flaky Foundry / Foundry Hosting integration tests (#5553)

These two integration tests have been failing in the merge queue across
multiple unrelated PRs (5301, 5531). Both are marked `@pytest.mark.flaky`
with 3 retries, but all attempts fail back-to-back. Skipping both with a
reason pointing to #5553 so they can be fixed properly without continuing
to block unrelated merges.

- packages/foundry_hosting/tests/test_responses_int.py::TestOptions::test_temperature_and_max_tokens
- packages/foundry/tests/foundry/test_foundry_embedding_client.py::TestFoundryEmbeddingIntegration::test_text_embedding_live

Also includes a one-line uv.lock specifier-ordering normalization
auto-applied by the poe-check pre-commit hook.

---------

Co-authored-by: Copilot <copilot@github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
866a325b48 · 2026-04-29 00:35:36 +00:00
History
..
01-get-started
Python: Add requirements.txt and .env.example to the a2a/ sample for pip-based setup (#5510)
2026-04-27 22:22:07 +00:00
02-agents
Python: update FoundryAgent for hosted agent sessions (#5447)
2026-04-24 09:25:03 +00:00
03-workflows
Python: [BREAKING] Standardize orchestration terminal outputs as AgentResponse (#5301)
2026-04-29 00:35:36 +00:00
04-hosting
Python: Update hosting agent samples + fixes (#5485)
2026-04-28 04:24:05 +00:00
05-end-to-end
Bump vite in /python/samples/05-end-to-end/chatkit-integration/frontend (#5126)
2026-04-28 08:08:36 +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: (core): Add functional workflow API (#4238)
2026-04-24 09:41:20 +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:

  1. 01_hello_agent.py — Create and run your first agent
  2. 02_add_tools.py — Add function tools with @tool
  3. 03_multi_turn.py — Multi-turn conversations with AgentSession
  4. 04_memory.py — Agent memory with ContextProvider
  5. 05_functional_workflow_with_agents.py — Call agents inside a functional workflow
  6. 06_functional_workflow_basics.py — Write a workflow as a plain async function
  7. 07_first_graph_workflow.py — Build a workflow with executors and edges
  8. 08_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):

  1. Copy .env.example to .env in the python/ directory: 
    cp .env.example .env
  2. 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:

  1. Explicit Azure inputs such as credential, azure_endpoint, or api_version
  2. OPENAI_API_KEY / explicit OpenAI API-key parameters
  3. 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

Reference in New Issue View Git Blame Copy Permalink