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

Files

T

Evan Mattson da32e8cf80 Python: (core): Add functional workflow API (#4238 )

* Add functional workflow api

* cleanup

* More cleanup

* address copilot feedback

* Address PR feedbacK

* updates

* PR feedback

* Address review comments on functional workflow samples

- Swap 05/06 get-started samples: agent workflow first (motivates
  why workflows exist), simple text workflow second
- Rename text_pipeline → text_workflow, poem_pipeline → poem_workflow
- Add @step to agent workflow sample (05) to demonstrate caching
- Switch agent samples to AzureOpenAIResponsesClient with Foundry
- Remove .as_agent() from agent_integration.py to focus on the key
  difference between inline agent calls vs @step-cached calls
- Add commented-out Agent.run example in hitl_review.py
- Add clarifying comment in _functional.py that event streaming is
  buffered (not true per-token streaming)
- Add naive_group_chat.py functional sample: round-robin group chat
  as a plain Python loop
- Update READMEs to reflect new file names and group chat sample

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

* Fix pyright type errors

* Address PR review comments on functional workflow API

1. Allow request_info inside @step: Auto-inject RunContext into step
   functions that declare a RunContext parameter (by type or name 'ctx'),
   and expose get_run_context() for programmatic access.

2. Handle None responses: Log a warning when a response value is None,
   and document the behavior in request_info docstring.

3. Add executor_bypassed event type: Replace executor_invoked +
   executor_completed with a single executor_bypassed event when a step
   replays from cache, making cached vs live execution explicit.

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

* Add regression tests for PR review comments on functional workflow API

The three review comments (request_info in @step, None response handling,
executor_bypassed event type) were already addressed in 7da7db4e. This
commit adds cross-cutting regression tests that exercise the interactions
between these features:

- HITL in step with caching: preceding step bypassed on resume
- Full checkpoint lifecycle with HITL step (interrupt -> resume -> restore)
- None response inside step-level request_info logs warning
- WorkflowInterrupted from step does not emit executor_failed

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

* Address PR #4238 review comments on functional workflow API

Comment 1 (request_info in @step): Already supported. Added comment in
StepWrapper.__call__ explaining why WorkflowInterrupted (BaseException)
safely bypasses the except Exception handler.

Comment 2 (None response): Added docstring to _get_response clarifying
the (found, value) return tuple semantics and None handling.

Comment 3 (bypass event type): executor_bypassed is already a dedicated
event type in WorkflowEventType. Updated comment at the bypass site to
make the deliberate event type choice explicit.

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

* Add experimental API warnings to functional workflow module

Mark all public classes and decorators (workflow, step, RunContext,
FunctionalWorkflow, StepWrapper, FunctionalWorkflowAgent) as
experimental and subject to change or removal.

* Address PR #4238 review comments from @eavanvalkenburg

- RunContext docstring leads with purpose (opt-in handle for HITL,
  custom events, state) so readers importing it from the public surface
  understand its role before the mechanics (#2993513452).
- Rename `06_first_functional_workflow.py` to
  `06_functional_workflow_basics.py`; the previous filename was
  confusing since it followed `05_functional_workflow_with_agents.py`
  (#2993531979).
- Simplify `05_functional_workflow_with_agents.py` to call agents
  directly without a @step wrapper; the step-vs-no-step contrast lives
  in `03-workflows/functional/agent_integration.py`, keeping the
  get-started sample minimal (#2993525532).
- Switch functional samples to `FoundryChatClient` for consistency with
  the rest of 01-get-started and 03-workflows (follow-up on #2876988570).
- Use walrus in `hitl_review.py` final-state assertion (#2993572182).
- Add expected-output block to `basic_streaming_pipeline.py` (#2993557609).
- Clarify in `parallel_pipeline.py` that `@step` composes with
  `asyncio.gather` (#2993597282).
- `naive_group_chat.py` threads `list[Message]` between turns instead
  of stringifying the transcript, preserving role/authorship (#2993583231).

Drive-by: pre-commit hook sorts an unrelated import block in
`samples/04-hosting/foundry-hosted-agents/responses/02_local_tools/main.py`.

* Fix 10 functional-workflow API bugs from /ultrareview pass

- bug_001: `ctx.request_info()` without an explicit `request_id` now derives
  a deterministic `auto::<index>` id from the call-counter, so HITL resume
  works correctly on the documented default path.  A uuid was regenerated on
  every replay, making resume impossible.

- bug_002: `StepWrapper.__call__` no longer deepcopies arguments on the
  cache-hit replay branch.  The copy is only performed on the live-execution
  path (for the event log) and falls back to the original mapping if deepcopy
  fails, so steps whose args aren't deepcopyable (locks, sockets, sessions)
  can still resume from checkpoint.

- bug_007: `_set_responses` now prunes each resolved `request_id` from
  `_pending_requests`, and the cache-hit branch in `request_info` does the
  same.  Previously, answered requests were re-serialized into every
  subsequent checkpoint and the final checkpoint falsely claimed pending
  requests even after the workflow completed.

- bug_008: `_compute_signature_hash` now mixes the function's `co_code` and
  `co_names` into the checkpoint signature, so changes to the workflow body
  invalidate older checkpoints even when steps are accessed via module /
  class attributes (which `_discover_step_names` can't see statically).
  `RunContext._record_observed_step` records observed step names for
  diagnostics.

- bug_010: `FunctionalWorkflow.run()` docstring corrected — says "at least
  one of message/responses/checkpoint_id" and explicitly notes `responses`
  may be combined with `checkpoint_id` (the validator already allowed this).

- bug_013: `FunctionalWorkflowAgent` now surfaces `request_info` events as
  `FunctionApprovalRequestContent` items (mirroring graph `WorkflowAgent`),
  threads `responses=` and `checkpoint_id=` through to the underlying
  workflow, and exposes `pending_requests`.  Previously `.as_agent()`
  returned empty `AgentResponse` for HITL workflows — effectively unusable.

- bug_014: `FunctionalWorkflow` now clears `_last_message`,
  `_last_step_cache`, and `_last_pending_request_ids` on clean completion.
  `run()` validates that `responses=` keys intersect the currently-pending
  request set (or raises with a clear error) instead of silently replaying
  against stale singleton state from a prior run.

- bug_015: `FunctionalWorkflow.as_agent` signature now matches graph
  `Workflow.as_agent`: accepts `name`, `description`, `context_providers`,
  and `**kwargs`.  `FunctionalWorkflowAgent` stores the overrides.

- bug_017: `RunContext.set_state` raises `ValueError` for underscore-
  prefixed keys (the framework's `_step_cache` / `_original_message` keys
  would silently clobber user state on checkpoint save and user
  underscore-prefixed state was dropped on restore).  Docstring documents
  the reserved prefix.

- merged_bug_003: Workflow function arity is validated at decoration time.
  Multiple non-ctx parameters raise `ValueError` immediately (previously
  every arg past the first was silently dropped at call time).  Passing a
  non-None `message` to a ctx-only workflow raises `ValueError` instead of
  silently discarding the message.

Test coverage: +18 regression tests covering every fix.  Full workflow
suite now 766 passed, 1 skipped, 2 xfailed; full core suite 2338 passed.

* Deslop functional.py fix commit

- Remove dead instrumentation added in the prior commit that was never
  consumed: `RunContext._observed_step_names`,
  `RunContext._record_observed_step`, `FunctionalWorkflow._runtime_step_names`,
  and `FunctionalWorkflowAgent._extra_kwargs`.  The signature hash relies on
  `co_code` alone, which covers the attribute-access case without the
  collection-scaffolding.
- Trim over-explanatory comments that restated what the code does or what
  it no longer does.  Keep only the comments that answer "why" for the
  non-obvious bits (deterministic id contract, defensive deepcopy, stale
  replay guard).
- Compress the `_compute_signature_hash` and FunctionalWorkflow `__init__`
  block docstrings without losing the user-facing reasoning.

Net -49 lines.  Regression lock preserved (766 passed, 1 skipped, 2 xfailed).

* Fix functional workflow review feedback

---------

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

da32e8cf80 · 2026-04-24 09:41:20 +00:00

History

01-get-started

Python: (core): Add functional workflow API (#4238 )

2026-04-24 09:41:20 +00:00

02-agents

Python: update FoundryAgent for hosted agent sessions (#5447 )

2026-04-24 09:25:03 +00:00

03-workflows

Python: (core): Add functional workflow API (#4238 )

2026-04-24 09:41:20 +00:00

04-hosting

Python: update FoundryAgent for hosted agent sessions (#5447 )

2026-04-24 09:25:03 +00:00

05-end-to-end

Python: feat(evals): add ground_truth support for similarity evaluator (#5234 )

2026-04-21 19:40:53 +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:

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_functional_workflow_with_agents.py — Call agents inside a functional workflow
06_functional_workflow_basics.py — Write a workflow as a plain async function
07_first_graph_workflow.py — Build a workflow with executors and edges
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):

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