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

Files

T

Eduard van Valkenburg 0cd40f8354 Python: [BREAKING] Refactor middleware layering and split Anthropic raw client (#4746 )

* [BREAKING] Refactor middleware layering and raw clients

Reorder chat client layers so function invocation wraps chat middleware, and chat middleware stays outside telemetry while still running for each inner model call. Add middleware pipeline caching, refresh docs and samples, and split Anthropic into raw and public clients to match the standard layering model.

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

* Tighten typing ignores in ancillary modules

Add targeted typing ignores in workflow visualization and lab modules so pyright stays clean alongside the middleware refactor work.

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

* Fix categorize_middleware to unpack tuple/Sequence and use relative MRO assertions

- Broaden isinstance check in categorize_middleware from list to Sequence
  so tuples and other Sequence types are properly unpacked instead of
  being appended as a single item.
- Replace fragile hardcoded MRO index assertions in anthropic test with
  relative ordering via mro.index().
- Add regression tests for categorize_middleware with tuple, list, and
  None inputs.

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

* Fix middleware string decomposition, add middleware param to FunctionInvocationLayer, and add tests (#4710)

- Guard categorize_middleware Sequence check against str/bytes to prevent
  character-by-character decomposition of accidentally passed strings
- Add explicit middleware parameter to FunctionInvocationLayer.get_response
  and merge it into client_kwargs before categorization, fixing the
  inconsistency where only OpenAIChatClient supported this parameter
- Add assertions that RawAnthropicClient does not inherit convenience layers
- Add chat middleware cache test with non-empty base middleware
- Add tests for single unwrapped middleware item and string input

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

* Apply pre-commit auto-fixes

* Apply pre-commit auto-fixes

* Address review feedback for #4710: review comment fixes

---------

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

0cd40f8354 · 2026-03-20 00:43:37 +00:00

History

agent_and_run_level_middleware.py

Python: [BREAKING] Refactor middleware layering and split Anthropic raw client (#4746 )

2026-03-20 00:43:37 +00:00

chat_middleware.py

Python: Add load_dotenv() to samples for .env file support (#4043 )

2026-02-19 10:55:13 +00:00

class_based_middleware.py

Python: Add load_dotenv() to samples for .env file support (#4043 )

2026-02-19 10:55:13 +00:00

decorator_middleware.py

Python: Add load_dotenv() to samples for .env file support (#4043 )

2026-02-19 10:55:13 +00:00

exception_handling_with_middleware.py

Python: Add load_dotenv() to samples for .env file support (#4043 )

2026-02-19 10:55:13 +00:00

function_based_middleware.py

Python: Add load_dotenv() to samples for .env file support (#4043 )

2026-02-19 10:55:13 +00:00

middleware_termination.py

Python: Add load_dotenv() to samples for .env file support (#4043 )

2026-02-19 10:55:13 +00:00

override_result_with_middleware.py

Python: Add load_dotenv() to samples for .env file support (#4043 )

2026-02-19 10:55:13 +00:00

README.md

Python: [BREAKING] Refactor middleware layering and split Anthropic raw client (#4746 )

2026-03-20 00:43:37 +00:00

runtime_context_delegation.py

Python: Add load_dotenv() to samples for .env file support (#4043 )

2026-02-19 10:55:13 +00:00

session_behavior_middleware.py

Python: Add load_dotenv() to samples for .env file support (#4043 )

2026-02-19 10:55:13 +00:00

shared_state_middleware.py

Python: Add load_dotenv() to samples for .env file support (#4043 )

2026-02-19 10:55:13 +00:00

usage_tracking_middleware.py

Python: [BREAKING] Refactor middleware layering and split Anthropic raw client (#4746 )

2026-03-20 00:43:37 +00:00

README.md

Middleware samples

This folder contains focused middleware samples for Agent, chat clients, tools, sessions, and runtime context behavior.

Files

File	Description
`agent_and_run_level_middleware.py`	Demonstrates combining agent-level and run-level middleware.
`chat_middleware.py`	Shows class-based and function-based chat middleware that can observe, modify, and override model calls.
`class_based_middleware.py`	Shows class-based agent and function middleware.
`decorator_middleware.py`	Demonstrates middleware registration with decorators.
`exception_handling_with_middleware.py`	Shows how middleware can handle failures and recover cleanly.
`function_based_middleware.py`	Shows function-based agent and function middleware.
`middleware_termination.py`	Demonstrates stopping a middleware pipeline early.
`override_result_with_middleware.py`	Shows how middleware can replace the normal result.
`runtime_context_delegation.py`	Demonstrates delegating work with runtime context data.
`session_behavior_middleware.py`	Shows how middleware interacts with session-backed runs.
`shared_state_middleware.py`	Demonstrates sharing mutable state across middleware invocations.
`usage_tracking_middleware.py`	Demonstrates one chat middleware function that tracks per-call usage in non-streaming and streaming tool-loop runs.

Running the usage tracking sample

The new usage tracking sample uses OpenAIResponsesClient, so set the usual OpenAI responses environment variables first:

export OPENAI_API_KEY="your-openai-api-key"
export OPENAI_RESPONSES_MODEL_ID="gpt-4.1-mini"

Then run:

uv run samples/02-agents/middleware/usage_tracking_middleware.py

The sample forces a tool call so you can see middleware output for each inner model call in both non-streaming and streaming modes.