Python: Agent and Function middleware

[dmytrostruk]

Motivation and Context

Related: #734
Follow-up: #802

This PR includes middleware for Agent and Function invocations. Middleware implementation can be a class or function.

Examples:

• class_based_middleware.py
• exception_handling_with_middleware.py
• function_based_middleware.py
• override_result_with_middleware.py

Agent invocation class-based middleware:

class MyAgentMiddleware(AgentMiddleware):
    async def process(
        self,
        context: AgentInvocationContext,
        next: Callable[[AgentInvocationContext], Awaitable[None]],
    ) -> None:
        # Logic before invocation
        await next(context)
        # Logic after invocation

Agent invocation function-based middleware:

async def my_agent_middleware(
    context: AgentInvocationContext,
    next: Callable[[AgentInvocationContext], Awaitable[None]],
) -> None:
    # Logic before invocation
    await next(context)
    # Logic after invocation

Function invocation class-based middleware:

class MyFunctionMiddleware(FunctionMiddleware):
    async def process(
        self,
        context: FunctionInvocationContext,
        next: Callable[[FunctionInvocationContext], Awaitable[None]],
    ) -> None:
        # Logic before invocation
        await next(context)
        # Logic after invocation

Function invocation function-based middleware:

async def my_function_middleware(
    context: FunctionInvocationContext,
    next: Callable[[FunctionInvocationContext], Awaitable[None]],
) -> None:
    # Logic before invocation
    await next(context)
    # Logic after invocation

Agent initialization:

agent = OpenAIChatClient().create_agent(
    name="WeatherAgent",
    instructions="You are a helpful weather assistant.",
    tools=get_weather,
    middlewares=[MyAgentMiddleware(), my_function_middleware]
)

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/main/agent_framework
_agents.py	186	25	86%	172–174, 181, 279, 337–339, 341–344, 351, 361, 434–435, 437, 440, 563–564, 566, 569, 628, 660, 705
_clients.py	98	11	88%	183, 215–216, 260, 326, 351, 412, 438, 469, 502, 504
_middleware.py	233	10	95%	303, 369–370, 464, 497, 499–500, 502, 505, 599
_tools.py	349	33	90%	161, 207, 353, 355, 357, 449–451, 496, 554, 586, 617–619, 627–629, 649, 651–652, 684, 762–763, 845–846, 850, 869–871, 892–893, 901–902
telemetry.py	489	107	78%	94, 250, 275, 280–282, 284–296, 300–311, 314–317, 320–328, 331–332, 336, 339, 350, 415, 431–432, 434–435, 437–441, 443, 450–452, 454, 492, 494, 496, 579–582, 668–671, 711, 860–862, 966, 973, 975, 977, 979, 981, 983, 985, 987, 989, 991, 995, 1005, 1031–1032, 1043, 1046–1049, 1062–1066, 1069, 1089, 1127
TOTAL	8002	1260	84%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
947	94 💤	0 ❌	0 🔥	26.074s ⏱️

[Copilot]

Pull Request Overview

This PR implements middleware functionality for agent and function invocations in the Python Agent Framework. It allows developers to intercept and process agent calls and function executions with custom logic before and after execution.

Key changes:

• Added middleware infrastructure supporting both class-based and function-based middleware implementations
• Integrated middleware pipelines into agent execution flow with automatic classification and routing
• Updated agent creation APIs to accept middleware parameters

Reviewed Changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
python/samples/getting_started/middleware/function_based_middleware.py	Example demonstrating function-based middleware for security checking and logging
python/samples/getting_started/middleware/class_based_middleware.py	Example demonstrating class-based middleware with the same functionality
python/packages/workflow/agent_framework_workflow/_agent.py	Updated workflow agent to support new middleware-aware execution signature
python/packages/main/agent_framework/_tools.py	Added middleware pipeline integration to function execution infrastructure
python/packages/main/agent_framework/_middleware.py	Core middleware implementation with context objects, base classes, and execution pipelines
python/packages/main/agent_framework/_clients.py	Updated client creation to accept middleware parameters and filter them from execution kwargs
python/packages/main/agent_framework/_agents.py	Major refactoring to integrate middleware pipelines into agent execution flow
python/packages/main/agent_framework/init.py	Exposed middleware types in the public API

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}