mirror of
https://github.com/microsoft/agent-framework.git
synced 2026-06-16 21:04:09 +08:00
Python: restructure: Python samples into progressive 01-05 layout (#3862)
* restructure: Python samples into progressive 01-05 layout - 01-get-started/: 6 numbered steps (hello agent → hosting) - 02-agents/: all agent concept samples (tools, middleware, providers, etc.) - 03-workflows/: ALL existing workflow samples preserved as-is - 04-hosting/: azure-functions, durabletask, a2a - 05-end-to-end/: demos, evaluation, hosted agents - Old files moved to _to_delete/ for review - Added AGENTS.md with structure documentation - autogen-migration/ and semantic-kernel-migration/ preserved at root * fix: switch to AzureOpenAI Foundry, fix CI failures - Switch all 01-get-started samples to AzureOpenAIResponsesClient with Azure AI Foundry project endpoint (AZURE_AI_PROJECT_ENDPOINT + AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME + AzureCliCredential) - Add _to_delete/ and 05-end-to-end/ to pyrightconfig.samples.json excludes - Fix test paths in packages/ that referenced old getting_started/ dirs: durabletask conftest + streaming test, azurefunctions conftest, devui conftest + capture_messages + openai_sdk_integration - Fix workflow_as_agent_human_in_the_loop.py import (sibling import) - Update hosting READMEs and tool comment paths - Replace root README.md with new structure overview - Update AGENTS.md to document Azure OpenAI Foundry as default provider * cleanup: remove _to_delete folder, copy resource files to active dirs All files in _to_delete/ were either: - Exact duplicates of files in the new structure (240 files) - Same file with only comment path updates (100 files) - One import-fix diff (workflow_as_agent_human_in_the_loop.py) - One superseded minimal_sample.py Resource files (sample.pdf, countries.json, employees.pdf, weather.json) copied to 02-agents/sample_assets/ and 02-agents/resources/ since active samples reference them. * fix: address PR review comments, centralize resources, remove root duplicates - Fix type annotation in 04_memory.py (string union -> proper types) - Fix old sample paths in observability files - Fix grammar/spelling in observability samples - Move sample_assets/ and resources/ to shared/ folder - Remove 8 duplicate observability files from 02-agents root - Update resource path references in multimodal_input and provider samples * fix: update broken links from old getting_started paths to new structure - Update relative paths in READMEs: getting_started/ → 01-get-started/, 02-agents/, 03-workflows/, 04-hosting/, 05-end-to-end/ - Fix absolute GitHub URLs in package READMEs - Fix broken link in ollama package README * fix: convert absolute GitHub URLs to relative paths for link checker Absolute URLs to python/samples/ on main branch 404 until PR merges. Converted to relative paths that linkspector can verify locally. * fix: update link for handoff sample moved to orchestrations/ * fix: update chatkit-integration README path from demos/ to 05-end-to-end/ * fix: update broken links in orchestrations README to match flat directory structure
This commit is contained in:
Eduard van Valkenburg
@@ -0,0 +1,293 @@
|
||||
# Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
import asyncio
|
||||
import time
|
||||
from collections.abc import Awaitable, Callable
|
||||
from random import randint
|
||||
from typing import Annotated
|
||||
|
||||
from agent_framework import (
|
||||
AgentContext,
|
||||
AgentMiddleware,
|
||||
AgentResponse,
|
||||
FunctionInvocationContext,
|
||||
tool,
|
||||
)
|
||||
from agent_framework.azure import AzureAIAgentClient
|
||||
from azure.identity.aio import AzureCliCredential
|
||||
from pydantic import Field
|
||||
|
||||
"""
|
||||
Agent-Level and Run-Level MiddlewareTypes Example
|
||||
|
||||
This sample demonstrates the difference between agent-level and run-level middleware:
|
||||
|
||||
- Agent-level middleware: Applied to ALL runs of the agent (persistent across runs)
|
||||
- Run-level middleware: Applied to specific runs only (isolated per run)
|
||||
|
||||
The example shows:
|
||||
1. Agent-level security middleware that validates all requests
|
||||
2. Agent-level performance monitoring across all runs
|
||||
3. Run-level context middleware for specific use cases (high priority, debugging)
|
||||
4. Run-level caching middleware for expensive operations
|
||||
|
||||
Agent Middleware Execution Order:
|
||||
When both agent-level and run-level *agent* middleware are configured, they execute
|
||||
in this order:
|
||||
|
||||
1. Agent-level middleware (outermost) - executes first, in the order they were registered
|
||||
2. Run-level middleware (innermost) - executes next, in the order they were passed to run()
|
||||
3. Agent execution - the actual agent logic runs last
|
||||
|
||||
For example, with agent middleware [A1, A2] and run middleware [R1, R2]:
|
||||
Request -> A1 -> A2 -> R1 -> R2 -> Agent -> R2 -> R1 -> A2 -> A1 -> Response
|
||||
|
||||
This means:
|
||||
- Agent middleware wraps ALL run middleware and the agent
|
||||
- Run middleware wraps only the agent for that specific run
|
||||
- Each middleware can modify the context before AND after calling next()
|
||||
|
||||
Note: Function and chat middleware (e.g., ``function_logging_middleware``) execute
|
||||
during tool invocation *inside* the agent execution, not in the outer agent-middleware
|
||||
chain shown above. They follow the same ordering principle: agent-level function/chat
|
||||
middleware runs before run-level function/chat middleware.
|
||||
"""
|
||||
|
||||
|
||||
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
|
||||
@tool(approval_mode="never_require")
|
||||
def get_weather(
|
||||
location: Annotated[str, Field(description="The location to get the weather for.")],
|
||||
) -> str:
|
||||
"""Get the weather for a given location."""
|
||||
conditions = ["sunny", "cloudy", "rainy", "stormy"]
|
||||
return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
|
||||
|
||||
|
||||
# Agent-level middleware (applied to ALL runs)
|
||||
class SecurityAgentMiddleware(AgentMiddleware):
|
||||
"""Agent-level security middleware that validates all requests."""
|
||||
|
||||
async def process(self, context: AgentContext, call_next: Callable[[], Awaitable[None]]) -> None:
|
||||
print("[SecurityMiddleware] Checking security for all requests...")
|
||||
|
||||
# Check for security violations in the last user message
|
||||
last_message = context.messages[-1] if context.messages else None
|
||||
if last_message and last_message.text:
|
||||
query = last_message.text.lower()
|
||||
if any(word in query for word in ["password", "secret", "credentials"]):
|
||||
print("[SecurityMiddleware] Security violation detected! Blocking request.")
|
||||
return # Don't call call_next() to prevent execution
|
||||
|
||||
print("[SecurityMiddleware] Security check passed.")
|
||||
context.metadata["security_validated"] = True
|
||||
await call_next()
|
||||
|
||||
|
||||
async def performance_monitor_middleware(
|
||||
context: AgentContext,
|
||||
call_next: Callable[[], Awaitable[None]],
|
||||
) -> None:
|
||||
"""Agent-level performance monitoring for all runs."""
|
||||
print("[PerformanceMonitor] Starting performance monitoring...")
|
||||
start_time = time.time()
|
||||
|
||||
await call_next()
|
||||
|
||||
end_time = time.time()
|
||||
duration = end_time - start_time
|
||||
print(f"[PerformanceMonitor] Total execution time: {duration:.3f}s")
|
||||
context.metadata["execution_time"] = duration
|
||||
|
||||
|
||||
# Run-level middleware (applied to specific runs only)
|
||||
class HighPriorityMiddleware(AgentMiddleware):
|
||||
"""Run-level middleware for high priority requests."""
|
||||
|
||||
async def process(self, context: AgentContext, call_next: Callable[[], Awaitable[None]]) -> None:
|
||||
print("[HighPriority] Processing high priority request with expedited handling...")
|
||||
|
||||
# Read metadata set by agent-level middleware
|
||||
if context.metadata.get("security_validated"):
|
||||
print("[HighPriority] Security validation confirmed from agent middleware")
|
||||
|
||||
# Set high priority flag
|
||||
context.metadata["priority"] = "high"
|
||||
context.metadata["expedited"] = True
|
||||
|
||||
await call_next()
|
||||
print("[HighPriority] High priority processing completed")
|
||||
|
||||
|
||||
async def debugging_middleware(
|
||||
context: AgentContext,
|
||||
call_next: Callable[[], Awaitable[None]],
|
||||
) -> None:
|
||||
"""Run-level debugging middleware for troubleshooting specific runs."""
|
||||
print("[Debug] Debug mode enabled for this run")
|
||||
print(f"[Debug] Messages count: {len(context.messages)}")
|
||||
print(f"[Debug] Is streaming: {context.stream}")
|
||||
|
||||
# Log existing metadata from agent middleware
|
||||
if context.metadata:
|
||||
print(f"[Debug] Existing metadata: {context.metadata}")
|
||||
|
||||
context.metadata["debug_enabled"] = True
|
||||
|
||||
await call_next()
|
||||
|
||||
print("[Debug] Debug information collected")
|
||||
|
||||
|
||||
class CachingMiddleware(AgentMiddleware):
|
||||
"""Run-level caching middleware for expensive operations."""
|
||||
|
||||
def __init__(self) -> None:
|
||||
self.cache: dict[str, AgentResponse] = {}
|
||||
|
||||
async def process(self, context: AgentContext, call_next: Callable[[], Awaitable[None]]) -> None:
|
||||
# Create a simple cache key from the last message
|
||||
last_message = context.messages[-1] if context.messages else None
|
||||
cache_key: str = last_message.text if last_message and last_message.text else "no_message"
|
||||
|
||||
if cache_key in self.cache:
|
||||
print(f"[Cache] Cache HIT for: '{cache_key[:30]}...'")
|
||||
context.result = self.cache[cache_key] # type: ignore
|
||||
return # Don't call call_next(), return cached result
|
||||
|
||||
print(f"[Cache] Cache MISS for: '{cache_key[:30]}...'")
|
||||
context.metadata["cache_key"] = cache_key
|
||||
|
||||
await call_next()
|
||||
|
||||
# Cache the result if we have one
|
||||
if context.result:
|
||||
self.cache[cache_key] = context.result # type: ignore
|
||||
print("[Cache] Result cached for future use")
|
||||
|
||||
|
||||
async def function_logging_middleware(
|
||||
context: FunctionInvocationContext,
|
||||
call_next: Callable[[], Awaitable[None]],
|
||||
) -> None:
|
||||
"""Function middleware that logs all function calls."""
|
||||
function_name = context.function.name
|
||||
args = context.arguments
|
||||
print(f"[FunctionLog] Calling function: {function_name} with args: {args}")
|
||||
|
||||
await call_next()
|
||||
|
||||
print(f"[FunctionLog] Function {function_name} completed")
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
"""Example demonstrating agent-level and run-level middleware."""
|
||||
print("=== Agent-Level and Run-Level MiddlewareTypes Example ===\n")
|
||||
|
||||
# For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
|
||||
# authentication option.
|
||||
async with (
|
||||
AzureCliCredential() as credential,
|
||||
AzureAIAgentClient(credential=credential).as_agent(
|
||||
name="WeatherAgent",
|
||||
instructions="You are a helpful weather assistant.",
|
||||
tools=get_weather,
|
||||
# Agent-level middleware: applied to ALL runs
|
||||
middleware=[
|
||||
SecurityAgentMiddleware(),
|
||||
performance_monitor_middleware,
|
||||
function_logging_middleware,
|
||||
],
|
||||
) as agent,
|
||||
):
|
||||
print("Agent created with agent-level middleware:")
|
||||
print(" - SecurityMiddleware (blocks sensitive requests)")
|
||||
print(" - PerformanceMonitor (tracks execution time)")
|
||||
print(" - FunctionLogging (logs all function calls)")
|
||||
print()
|
||||
|
||||
# Run 1: Normal query with no run-level middleware
|
||||
print("=" * 60)
|
||||
print("RUN 1: Normal query (agent-level middleware only)")
|
||||
print("=" * 60)
|
||||
query = "What's the weather like in Paris?"
|
||||
print(f"User: {query}")
|
||||
result = await agent.run(query)
|
||||
print(f"Agent: {result.text if result.text else 'No response'}")
|
||||
print()
|
||||
|
||||
# Run 2: High priority request with run-level middleware
|
||||
print("=" * 60)
|
||||
print("RUN 2: High priority request (agent + run-level middleware)")
|
||||
print("=" * 60)
|
||||
query = "What's the weather in Tokyo? This is urgent!"
|
||||
print(f"User: {query}")
|
||||
result = await agent.run(
|
||||
query,
|
||||
middleware=[HighPriorityMiddleware()], # Run-level middleware
|
||||
)
|
||||
print(f"Agent: {result.text if result.text else 'No response'}")
|
||||
print()
|
||||
|
||||
# Run 3: Debug mode with run-level debugging middleware
|
||||
print("=" * 60)
|
||||
print("RUN 3: Debug mode (agent + run-level debugging)")
|
||||
print("=" * 60)
|
||||
query = "What's the weather in London?"
|
||||
print(f"User: {query}")
|
||||
result = await agent.run(
|
||||
query,
|
||||
middleware=[debugging_middleware], # Run-level middleware
|
||||
)
|
||||
print(f"Agent: {result.text if result.text else 'No response'}")
|
||||
print()
|
||||
|
||||
# Run 4: Multiple run-level middleware
|
||||
print("=" * 60)
|
||||
print("RUN 4: Multiple run-level middleware (caching + debug)")
|
||||
print("=" * 60)
|
||||
caching = CachingMiddleware()
|
||||
query = "What's the weather in New York?"
|
||||
print(f"User: {query}")
|
||||
result = await agent.run(
|
||||
query,
|
||||
middleware=[caching, debugging_middleware], # Multiple run-level middleware
|
||||
)
|
||||
print(f"Agent: {result.text if result.text else 'No response'}")
|
||||
print()
|
||||
|
||||
# Run 5: Test cache hit with same query
|
||||
print("=" * 60)
|
||||
print("RUN 5: Test cache hit (same query as Run 4)")
|
||||
print("=" * 60)
|
||||
print(f"User: {query}") # Same query as Run 4
|
||||
result = await agent.run(
|
||||
query,
|
||||
middleware=[caching], # Same caching middleware instance
|
||||
)
|
||||
print(f"Agent: {result.text if result.text else 'No response'}")
|
||||
print()
|
||||
|
||||
# Run 6: Security violation test
|
||||
print("=" * 60)
|
||||
print("RUN 6: Security test (should be blocked by agent middleware)")
|
||||
print("=" * 60)
|
||||
query = "What's the secret weather password for Berlin?"
|
||||
print(f"User: {query}")
|
||||
result = await agent.run(query)
|
||||
print(f"Agent: {result.text if result and result.text else 'Request was blocked by security middleware'}")
|
||||
print()
|
||||
|
||||
# Run 7: Normal query again (no run-level middleware interference)
|
||||
print("=" * 60)
|
||||
print("RUN 7: Normal query again (agent-level middleware only)")
|
||||
print("=" * 60)
|
||||
query = "What's the weather in Sydney?"
|
||||
print(f"User: {query}")
|
||||
result = await agent.run(query)
|
||||
print(f"Agent: {result.text if result.text else 'No response'}")
|
||||
print()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
@@ -0,0 +1,247 @@
|
||||
# Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
import asyncio
|
||||
from collections.abc import Awaitable, Callable
|
||||
from random import randint
|
||||
from typing import Annotated
|
||||
|
||||
from agent_framework import (
|
||||
ChatContext,
|
||||
ChatMiddleware,
|
||||
ChatResponse,
|
||||
Message,
|
||||
MiddlewareTermination,
|
||||
chat_middleware,
|
||||
tool,
|
||||
)
|
||||
from agent_framework.azure import AzureAIAgentClient
|
||||
from azure.identity.aio import AzureCliCredential
|
||||
from pydantic import Field
|
||||
|
||||
"""
|
||||
Chat MiddlewareTypes Example
|
||||
|
||||
This sample demonstrates how to use chat middleware to observe and override
|
||||
inputs sent to AI models. Chat middleware intercepts chat requests before they reach
|
||||
the underlying AI service, allowing you to:
|
||||
|
||||
1. Observe and log input messages
|
||||
2. Modify input messages before sending to AI
|
||||
3. Override the entire response
|
||||
|
||||
The example covers:
|
||||
- Class-based chat middleware inheriting from ChatMiddleware
|
||||
- Function-based chat middleware with @chat_middleware decorator
|
||||
- MiddlewareTypes registration at agent level (applies to all runs)
|
||||
- MiddlewareTypes registration at run level (applies to specific run only)
|
||||
"""
|
||||
|
||||
|
||||
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
|
||||
@tool(approval_mode="never_require")
|
||||
def get_weather(
|
||||
location: Annotated[str, Field(description="The location to get the weather for.")],
|
||||
) -> str:
|
||||
"""Get the weather for a given location."""
|
||||
conditions = ["sunny", "cloudy", "rainy", "stormy"]
|
||||
return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
|
||||
|
||||
|
||||
class InputObserverMiddleware(ChatMiddleware):
|
||||
"""Class-based middleware that observes and modifies input messages."""
|
||||
|
||||
def __init__(self, replacement: str | None = None):
|
||||
"""Initialize with a replacement for user messages."""
|
||||
self.replacement = replacement
|
||||
|
||||
async def process(
|
||||
self,
|
||||
context: ChatContext,
|
||||
call_next: Callable[[], Awaitable[None]],
|
||||
) -> None:
|
||||
"""Observe and modify input messages before they are sent to AI."""
|
||||
print("[InputObserverMiddleware] Observing input messages:")
|
||||
|
||||
for i, message in enumerate(context.messages):
|
||||
content = message.text if message.text else str(message.contents)
|
||||
print(f" Message {i + 1} ({message.role}): {content}")
|
||||
|
||||
print(f"[InputObserverMiddleware] Total messages: {len(context.messages)}")
|
||||
|
||||
# Modify user messages by creating new messages with enhanced text
|
||||
modified_messages: list[Message] = []
|
||||
modified_count = 0
|
||||
|
||||
for message in context.messages:
|
||||
if message.role == "user" and message.text:
|
||||
original_text = message.text
|
||||
updated_text = original_text
|
||||
|
||||
if self.replacement:
|
||||
updated_text = self.replacement
|
||||
print(f"[InputObserverMiddleware] Updated: '{original_text}' -> '{updated_text}'")
|
||||
|
||||
modified_message = Message(message.role, [updated_text])
|
||||
modified_messages.append(modified_message)
|
||||
modified_count += 1
|
||||
else:
|
||||
modified_messages.append(message)
|
||||
|
||||
# Replace messages in context
|
||||
context.messages[:] = modified_messages
|
||||
|
||||
# Continue to next middleware or AI execution
|
||||
await call_next()
|
||||
|
||||
# Observe that processing is complete
|
||||
print("[InputObserverMiddleware] Processing completed")
|
||||
|
||||
|
||||
@chat_middleware
|
||||
async def security_and_override_middleware(
|
||||
context: ChatContext,
|
||||
call_next: Callable[[], Awaitable[None]],
|
||||
) -> None:
|
||||
"""Function-based middleware that implements security filtering and response override."""
|
||||
print("[SecurityMiddleware] Processing input...")
|
||||
|
||||
# Security check - block sensitive information
|
||||
blocked_terms = ["password", "secret", "api_key", "token"]
|
||||
|
||||
for message in context.messages:
|
||||
if message.text:
|
||||
message_lower = message.text.lower()
|
||||
for term in blocked_terms:
|
||||
if term in message_lower:
|
||||
print(f"[SecurityMiddleware] BLOCKED: Found '{term}' in message")
|
||||
|
||||
# Override the response instead of calling AI
|
||||
context.result = ChatResponse(
|
||||
messages=[
|
||||
Message(
|
||||
role="assistant",
|
||||
text="I cannot process requests containing sensitive information. "
|
||||
"Please rephrase your question without including passwords, secrets, or other "
|
||||
"sensitive data.",
|
||||
)
|
||||
]
|
||||
)
|
||||
|
||||
# Set terminate flag to stop execution
|
||||
raise MiddlewareTermination
|
||||
|
||||
# Continue to next middleware or AI execution
|
||||
await call_next()
|
||||
|
||||
|
||||
async def class_based_chat_middleware() -> None:
|
||||
"""Demonstrate class-based middleware at agent level."""
|
||||
print("\n" + "=" * 60)
|
||||
print("Class-based Chat MiddlewareTypes (Agent Level)")
|
||||
print("=" * 60)
|
||||
|
||||
# For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
|
||||
# authentication option.
|
||||
async with (
|
||||
AzureCliCredential() as credential,
|
||||
AzureAIAgentClient(credential=credential).as_agent(
|
||||
name="EnhancedChatAgent",
|
||||
instructions="You are a helpful AI assistant.",
|
||||
# Register class-based middleware at agent level (applies to all runs)
|
||||
middleware=[InputObserverMiddleware()],
|
||||
tools=get_weather,
|
||||
) as agent,
|
||||
):
|
||||
query = "What's the weather in Seattle?"
|
||||
print(f"User: {query}")
|
||||
result = await agent.run(query)
|
||||
print(f"Final Response: {result.text if result.text else 'No response'}")
|
||||
|
||||
|
||||
async def function_based_chat_middleware() -> None:
|
||||
"""Demonstrate function-based middleware at agent level."""
|
||||
print("\n" + "=" * 60)
|
||||
print("Function-based Chat MiddlewareTypes (Agent Level)")
|
||||
print("=" * 60)
|
||||
|
||||
async with (
|
||||
AzureCliCredential() as credential,
|
||||
AzureAIAgentClient(credential=credential).as_agent(
|
||||
name="FunctionMiddlewareAgent",
|
||||
instructions="You are a helpful AI assistant.",
|
||||
# Register function-based middleware at agent level
|
||||
middleware=[security_and_override_middleware],
|
||||
) as agent,
|
||||
):
|
||||
# Scenario with normal query
|
||||
print("\n--- Scenario 1: Normal Query ---")
|
||||
query = "Hello, how are you?"
|
||||
print(f"User: {query}")
|
||||
result = await agent.run(query)
|
||||
print(f"Final Response: {result.text if result.text else 'No response'}")
|
||||
|
||||
# Scenario with security violation
|
||||
print("\n--- Scenario 2: Security Violation ---")
|
||||
query = "What is my password for this account?"
|
||||
print(f"User: {query}")
|
||||
result = await agent.run(query)
|
||||
print(f"Final Response: {result.text if result.text else 'No response'}")
|
||||
|
||||
|
||||
async def run_level_middleware() -> None:
|
||||
"""Demonstrate middleware registration at run level."""
|
||||
print("\n" + "=" * 60)
|
||||
print("Run-level Chat MiddlewareTypes")
|
||||
print("=" * 60)
|
||||
|
||||
async with (
|
||||
AzureCliCredential() as credential,
|
||||
AzureAIAgentClient(credential=credential).as_agent(
|
||||
name="RunLevelAgent",
|
||||
instructions="You are a helpful AI assistant.",
|
||||
tools=get_weather,
|
||||
# No middleware at agent level
|
||||
) as agent,
|
||||
):
|
||||
# Scenario 1: Run without any middleware
|
||||
print("\n--- Scenario 1: No MiddlewareTypes ---")
|
||||
query = "What's the weather in Tokyo?"
|
||||
print(f"User: {query}")
|
||||
result = await agent.run(query)
|
||||
print(f"Response: {result.text if result.text else 'No response'}")
|
||||
|
||||
# Scenario 2: Run with specific middleware for this call only (both enhancement and security)
|
||||
print("\n--- Scenario 2: With Run-level MiddlewareTypes ---")
|
||||
print(f"User: {query}")
|
||||
result = await agent.run(
|
||||
query,
|
||||
middleware=[
|
||||
InputObserverMiddleware(replacement="What's the weather in Madrid?"),
|
||||
security_and_override_middleware,
|
||||
],
|
||||
)
|
||||
print(f"Response: {result.text if result.text else 'No response'}")
|
||||
|
||||
# Scenario 3: Security test with run-level middleware
|
||||
print("\n--- Scenario 3: Security Test with Run-level MiddlewareTypes ---")
|
||||
query = "Can you help me with my secret API key?"
|
||||
print(f"User: {query}")
|
||||
result = await agent.run(
|
||||
query,
|
||||
middleware=[security_and_override_middleware],
|
||||
)
|
||||
print(f"Response: {result.text if result.text else 'No response'}")
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
"""Run all chat middleware examples."""
|
||||
print("Chat MiddlewareTypes Examples")
|
||||
print("========================")
|
||||
|
||||
await class_based_chat_middleware()
|
||||
await function_based_chat_middleware()
|
||||
await run_level_middleware()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
@@ -0,0 +1,125 @@
|
||||
# Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
import asyncio
|
||||
import time
|
||||
from collections.abc import Awaitable, Callable
|
||||
from random import randint
|
||||
from typing import Annotated
|
||||
|
||||
from agent_framework import (
|
||||
AgentContext,
|
||||
AgentMiddleware,
|
||||
AgentResponse,
|
||||
FunctionInvocationContext,
|
||||
FunctionMiddleware,
|
||||
Message,
|
||||
tool,
|
||||
)
|
||||
from agent_framework.azure import AzureAIAgentClient
|
||||
from azure.identity.aio import AzureCliCredential
|
||||
from pydantic import Field
|
||||
|
||||
"""
|
||||
Class-based MiddlewareTypes Example
|
||||
|
||||
This sample demonstrates how to implement middleware using class-based approach by inheriting
|
||||
from AgentMiddleware and FunctionMiddleware base classes. The example includes:
|
||||
|
||||
- SecurityAgentMiddleware: Checks for security violations in user queries and blocks requests
|
||||
containing sensitive information like passwords or secrets
|
||||
- LoggingFunctionMiddleware: Logs function execution details including timing and parameters
|
||||
|
||||
This approach is useful when you need stateful middleware or complex logic that benefits
|
||||
from object-oriented design patterns.
|
||||
"""
|
||||
|
||||
|
||||
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
|
||||
@tool(approval_mode="never_require")
|
||||
def get_weather(
|
||||
location: Annotated[str, Field(description="The location to get the weather for.")],
|
||||
) -> str:
|
||||
"""Get the weather for a given location."""
|
||||
conditions = ["sunny", "cloudy", "rainy", "stormy"]
|
||||
return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
|
||||
|
||||
|
||||
class SecurityAgentMiddleware(AgentMiddleware):
|
||||
"""Agent middleware that checks for security violations."""
|
||||
|
||||
async def process(
|
||||
self,
|
||||
context: AgentContext,
|
||||
call_next: Callable[[], Awaitable[None]],
|
||||
) -> None:
|
||||
# Check for potential security violations in the query
|
||||
# Look at the last user message
|
||||
last_message = context.messages[-1] if context.messages else None
|
||||
if last_message and last_message.text:
|
||||
query = last_message.text
|
||||
if "password" in query.lower() or "secret" in query.lower():
|
||||
print("[SecurityAgentMiddleware] Security Warning: Detected sensitive information, blocking request.")
|
||||
# Override the result with warning message
|
||||
context.result = AgentResponse(
|
||||
messages=[Message("assistant", ["Detected sensitive information, the request is blocked."])]
|
||||
)
|
||||
# Simply don't call call_next() to prevent execution
|
||||
return
|
||||
|
||||
print("[SecurityAgentMiddleware] Security check passed.")
|
||||
await call_next()
|
||||
|
||||
|
||||
class LoggingFunctionMiddleware(FunctionMiddleware):
|
||||
"""Function middleware that logs function calls."""
|
||||
|
||||
async def process(
|
||||
self,
|
||||
context: FunctionInvocationContext,
|
||||
call_next: Callable[[], Awaitable[None]],
|
||||
) -> None:
|
||||
function_name = context.function.name
|
||||
print(f"[LoggingFunctionMiddleware] About to call function: {function_name}.")
|
||||
|
||||
start_time = time.time()
|
||||
|
||||
await call_next()
|
||||
|
||||
end_time = time.time()
|
||||
duration = end_time - start_time
|
||||
|
||||
print(f"[LoggingFunctionMiddleware] Function {function_name} completed in {duration:.5f}s.")
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
"""Example demonstrating class-based middleware."""
|
||||
print("=== Class-based MiddlewareTypes Example ===")
|
||||
|
||||
# For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
|
||||
# authentication option.
|
||||
async with (
|
||||
AzureCliCredential() as credential,
|
||||
AzureAIAgentClient(credential=credential).as_agent(
|
||||
name="WeatherAgent",
|
||||
instructions="You are a helpful weather assistant.",
|
||||
tools=get_weather,
|
||||
middleware=[SecurityAgentMiddleware(), LoggingFunctionMiddleware()],
|
||||
) as agent,
|
||||
):
|
||||
# Test with normal query
|
||||
print("\n--- Normal Query ---")
|
||||
query = "What's the weather like in Seattle?"
|
||||
print(f"User: {query}")
|
||||
result = await agent.run(query)
|
||||
print(f"Agent: {result.text}\n")
|
||||
|
||||
# Test with security-related query
|
||||
print("--- Security Test ---")
|
||||
query = "What's the password for the weather service?"
|
||||
print(f"User: {query}")
|
||||
result = await agent.run(query)
|
||||
print(f"Agent: {result.text}\n")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
@@ -0,0 +1,90 @@
|
||||
# Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
import asyncio
|
||||
import datetime
|
||||
|
||||
from agent_framework import (
|
||||
agent_middleware,
|
||||
function_middleware,
|
||||
tool,
|
||||
)
|
||||
from agent_framework.azure import AzureAIAgentClient
|
||||
from azure.identity.aio import AzureCliCredential
|
||||
|
||||
"""
|
||||
Decorator MiddlewareTypes Example
|
||||
|
||||
This sample demonstrates how to use @agent_middleware and @function_middleware decorators
|
||||
to explicitly mark middleware functions without requiring type annotations.
|
||||
|
||||
The framework supports the following middleware detection scenarios:
|
||||
|
||||
1. Both decorator and parameter type specified:
|
||||
- Validates that they match (e.g., @agent_middleware with AgentContext)
|
||||
- Throws exception if they don't match for safety
|
||||
|
||||
2. Only decorator specified:
|
||||
- Relies on decorator to determine middleware type
|
||||
- No type annotations needed - framework handles context types automatically
|
||||
|
||||
3. Only parameter type specified:
|
||||
- Uses type annotations (AgentContext, FunctionInvocationContext) for detection
|
||||
|
||||
4. Neither decorator nor parameter type specified:
|
||||
- Throws exception requiring either decorator or type annotation
|
||||
- Prevents ambiguous middleware that can't be properly classified
|
||||
|
||||
Key benefits of decorator approach:
|
||||
- No type annotations needed (simpler syntax)
|
||||
- Explicit middleware type declaration
|
||||
- Clear intent in code
|
||||
- Prevents type mismatches
|
||||
"""
|
||||
|
||||
|
||||
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
|
||||
@tool(approval_mode="never_require")
|
||||
def get_current_time() -> str:
|
||||
"""Get the current time."""
|
||||
return f"Current time is {datetime.datetime.now().strftime('%H:%M:%S')}"
|
||||
|
||||
|
||||
@agent_middleware # Decorator marks this as agent middleware - no type annotations needed
|
||||
async def simple_agent_middleware(context, call_next): # type: ignore - parameters intentionally untyped to demonstrate decorator functionality
|
||||
"""Agent middleware that runs before and after agent execution."""
|
||||
print("[Agent MiddlewareTypes] Before agent execution")
|
||||
await call_next()
|
||||
print("[Agent MiddlewareTypes] After agent execution")
|
||||
|
||||
|
||||
@function_middleware # Decorator marks this as function middleware - no type annotations needed
|
||||
async def simple_function_middleware(context, call_next): # type: ignore - parameters intentionally untyped to demonstrate decorator functionality
|
||||
"""Function middleware that runs before and after function calls."""
|
||||
print(f"[Function MiddlewareTypes] Before calling: {context.function.name}") # type: ignore
|
||||
await call_next()
|
||||
print(f"[Function MiddlewareTypes] After calling: {context.function.name}") # type: ignore
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
"""Example demonstrating decorator-based middleware."""
|
||||
print("=== Decorator MiddlewareTypes Example ===")
|
||||
|
||||
# For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
|
||||
# authentication option.
|
||||
async with (
|
||||
AzureCliCredential() as credential,
|
||||
AzureAIAgentClient(credential=credential).as_agent(
|
||||
name="TimeAgent",
|
||||
instructions="You are a helpful time assistant. Call get_current_time when asked about time.",
|
||||
tools=get_current_time,
|
||||
middleware=[simple_agent_middleware, simple_function_middleware],
|
||||
) as agent,
|
||||
):
|
||||
query = "What time is it?"
|
||||
print(f"User: {query}")
|
||||
result = await agent.run(query)
|
||||
print(f"Agent: {result.text if result.text else 'No response'}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
@@ -0,0 +1,77 @@
|
||||
# Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
import asyncio
|
||||
from collections.abc import Awaitable, Callable
|
||||
from typing import Annotated
|
||||
|
||||
from agent_framework import FunctionInvocationContext, tool
|
||||
from agent_framework.azure import AzureAIAgentClient
|
||||
from azure.identity.aio import AzureCliCredential
|
||||
from pydantic import Field
|
||||
|
||||
"""
|
||||
Exception Handling with MiddlewareTypes
|
||||
|
||||
This sample demonstrates how to use middleware for centralized exception handling in function calls.
|
||||
The example shows:
|
||||
|
||||
- How to catch exceptions thrown by functions and provide graceful error responses
|
||||
- Overriding function results when errors occur to provide user-friendly messages
|
||||
- Using middleware to implement retry logic, fallback mechanisms, or error reporting
|
||||
|
||||
The middleware catches TimeoutError from an unstable data service and replaces it with
|
||||
a helpful message for the user, preventing raw exceptions from reaching the end user.
|
||||
"""
|
||||
|
||||
|
||||
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
|
||||
@tool(approval_mode="never_require")
|
||||
def unstable_data_service(
|
||||
query: Annotated[str, Field(description="The data query to execute.")],
|
||||
) -> str:
|
||||
"""A simulated data service that sometimes throws exceptions."""
|
||||
# Simulate failure
|
||||
raise TimeoutError("Data service request timed out")
|
||||
|
||||
|
||||
async def exception_handling_middleware(
|
||||
context: FunctionInvocationContext, call_next: Callable[[], Awaitable[None]]
|
||||
) -> None:
|
||||
function_name = context.function.name
|
||||
|
||||
try:
|
||||
print(f"[ExceptionHandlingMiddleware] Executing function: {function_name}")
|
||||
await call_next()
|
||||
print(f"[ExceptionHandlingMiddleware] Function {function_name} completed successfully.")
|
||||
except TimeoutError as e:
|
||||
print(f"[ExceptionHandlingMiddleware] Caught TimeoutError: {e}")
|
||||
# Override function result to provide custom message in response.
|
||||
context.result = (
|
||||
"Request Timeout: The data service is taking longer than expected to respond.",
|
||||
"Respond with message - 'Sorry for the inconvenience, please try again later.'",
|
||||
)
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
"""Example demonstrating exception handling with middleware."""
|
||||
print("=== Exception Handling MiddlewareTypes Example ===")
|
||||
|
||||
# For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
|
||||
# authentication option.
|
||||
async with (
|
||||
AzureCliCredential() as credential,
|
||||
AzureAIAgentClient(credential=credential).as_agent(
|
||||
name="DataAgent",
|
||||
instructions="You are a helpful data assistant. Use the data service tool to fetch information for users.",
|
||||
tools=unstable_data_service,
|
||||
middleware=[exception_handling_middleware],
|
||||
) as agent,
|
||||
):
|
||||
query = "Get user statistics"
|
||||
print(f"User: {query}")
|
||||
result = await agent.run(query)
|
||||
print(f"Agent: {result}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
@@ -0,0 +1,112 @@
|
||||
# Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
import asyncio
|
||||
import time
|
||||
from collections.abc import Awaitable, Callable
|
||||
from random import randint
|
||||
from typing import Annotated
|
||||
|
||||
from agent_framework import (
|
||||
AgentContext,
|
||||
FunctionInvocationContext,
|
||||
tool,
|
||||
)
|
||||
from agent_framework.azure import AzureAIAgentClient
|
||||
from azure.identity.aio import AzureCliCredential
|
||||
from pydantic import Field
|
||||
|
||||
"""
|
||||
Function-based MiddlewareTypes Example
|
||||
|
||||
This sample demonstrates how to implement middleware using simple async functions instead of classes.
|
||||
The example includes:
|
||||
|
||||
- Security middleware that validates agent requests for sensitive information
|
||||
- Logging middleware that tracks function execution timing and parameters
|
||||
- Performance monitoring to measure execution duration
|
||||
|
||||
Function-based middleware is ideal for simple, stateless operations and provides a more
|
||||
lightweight approach compared to class-based middleware. Both agent and function middleware
|
||||
can be implemented as async functions that accept context and call_next parameters.
|
||||
"""
|
||||
|
||||
|
||||
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
|
||||
@tool(approval_mode="never_require")
|
||||
def get_weather(
|
||||
location: Annotated[str, Field(description="The location to get the weather for.")],
|
||||
) -> str:
|
||||
"""Get the weather for a given location."""
|
||||
conditions = ["sunny", "cloudy", "rainy", "stormy"]
|
||||
return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
|
||||
|
||||
|
||||
async def security_agent_middleware(
|
||||
context: AgentContext,
|
||||
call_next: Callable[[], Awaitable[None]],
|
||||
) -> None:
|
||||
"""Agent middleware that checks for security violations."""
|
||||
# Check for potential security violations in the query
|
||||
# For this example, we'll check the last user message
|
||||
last_message = context.messages[-1] if context.messages else None
|
||||
if last_message and last_message.text:
|
||||
query = last_message.text
|
||||
if "password" in query.lower() or "secret" in query.lower():
|
||||
print("[SecurityAgentMiddleware] Security Warning: Detected sensitive information, blocking request.")
|
||||
# Simply don't call call_next() to prevent execution
|
||||
return
|
||||
|
||||
print("[SecurityAgentMiddleware] Security check passed.")
|
||||
await call_next()
|
||||
|
||||
|
||||
async def logging_function_middleware(
|
||||
context: FunctionInvocationContext,
|
||||
call_next: Callable[[], Awaitable[None]],
|
||||
) -> None:
|
||||
"""Function middleware that logs function calls."""
|
||||
function_name = context.function.name
|
||||
print(f"[LoggingFunctionMiddleware] About to call function: {function_name}.")
|
||||
|
||||
start_time = time.time()
|
||||
|
||||
await call_next()
|
||||
|
||||
end_time = time.time()
|
||||
duration = end_time - start_time
|
||||
|
||||
print(f"[LoggingFunctionMiddleware] Function {function_name} completed in {duration:.5f}s.")
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
"""Example demonstrating function-based middleware."""
|
||||
print("=== Function-based MiddlewareTypes Example ===")
|
||||
|
||||
# For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
|
||||
# authentication option.
|
||||
async with (
|
||||
AzureCliCredential() as credential,
|
||||
AzureAIAgentClient(credential=credential).as_agent(
|
||||
name="WeatherAgent",
|
||||
instructions="You are a helpful weather assistant.",
|
||||
tools=get_weather,
|
||||
middleware=[security_agent_middleware, logging_function_middleware],
|
||||
) as agent,
|
||||
):
|
||||
# Test with normal query
|
||||
print("\n--- Normal Query ---")
|
||||
query = "What's the weather like in Tokyo?"
|
||||
print(f"User: {query}")
|
||||
result = await agent.run(query)
|
||||
print(f"Agent: {result.text if result.text else 'No response'}\n")
|
||||
|
||||
# Test with security violation
|
||||
print("--- Security Test ---")
|
||||
query = "What's the secret weather password?"
|
||||
print(f"User: {query}")
|
||||
result = await agent.run(query)
|
||||
print(f"Agent: {result.text if result and result.text else 'No response'}\n")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
@@ -0,0 +1,179 @@
|
||||
# Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
import asyncio
|
||||
from collections.abc import Awaitable, Callable
|
||||
from random import randint
|
||||
from typing import Annotated
|
||||
|
||||
from agent_framework import (
|
||||
AgentContext,
|
||||
AgentMiddleware,
|
||||
AgentResponse,
|
||||
Message,
|
||||
MiddlewareTermination,
|
||||
tool,
|
||||
)
|
||||
from agent_framework.azure import AzureAIAgentClient
|
||||
from azure.identity.aio import AzureCliCredential
|
||||
from pydantic import Field
|
||||
|
||||
"""
|
||||
MiddlewareTypes Termination Example
|
||||
|
||||
This sample demonstrates how middleware can terminate execution using the `context.terminate` flag.
|
||||
The example includes:
|
||||
|
||||
- PreTerminationMiddleware: Terminates execution before calling call_next() to prevent agent processing
|
||||
- PostTerminationMiddleware: Allows processing to complete but terminates further execution
|
||||
|
||||
This is useful for implementing security checks, rate limiting, or early exit conditions.
|
||||
"""
|
||||
|
||||
|
||||
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
|
||||
@tool(approval_mode="never_require")
|
||||
def get_weather(
|
||||
location: Annotated[str, Field(description="The location to get the weather for.")],
|
||||
) -> str:
|
||||
"""Get the weather for a given location."""
|
||||
conditions = ["sunny", "cloudy", "rainy", "stormy"]
|
||||
return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
|
||||
|
||||
|
||||
class PreTerminationMiddleware(AgentMiddleware):
|
||||
"""MiddlewareTypes that terminates execution before calling the agent."""
|
||||
|
||||
def __init__(self, blocked_words: list[str]):
|
||||
self.blocked_words = [word.lower() for word in blocked_words]
|
||||
|
||||
async def process(
|
||||
self,
|
||||
context: AgentContext,
|
||||
call_next: Callable[[], Awaitable[None]],
|
||||
) -> None:
|
||||
# Check if the user message contains any blocked words
|
||||
last_message = context.messages[-1] if context.messages else None
|
||||
if last_message and last_message.text:
|
||||
query = last_message.text.lower()
|
||||
for blocked_word in self.blocked_words:
|
||||
if blocked_word in query:
|
||||
print(f"[PreTerminationMiddleware] Blocked word '{blocked_word}' detected. Terminating request.")
|
||||
|
||||
# Set a custom response
|
||||
context.result = AgentResponse(
|
||||
messages=[
|
||||
Message(
|
||||
role="assistant",
|
||||
text=(
|
||||
f"Sorry, I cannot process requests containing '{blocked_word}'. "
|
||||
"Please rephrase your question."
|
||||
),
|
||||
)
|
||||
]
|
||||
)
|
||||
|
||||
# Terminate to prevent further processing
|
||||
raise MiddlewareTermination(result=context.result)
|
||||
|
||||
await call_next()
|
||||
|
||||
|
||||
class PostTerminationMiddleware(AgentMiddleware):
|
||||
"""MiddlewareTypes that allows processing but terminates after reaching max responses across multiple runs."""
|
||||
|
||||
def __init__(self, max_responses: int = 1):
|
||||
self.max_responses = max_responses
|
||||
self.response_count = 0
|
||||
|
||||
async def process(
|
||||
self,
|
||||
context: AgentContext,
|
||||
call_next: Callable[[], Awaitable[None]],
|
||||
) -> None:
|
||||
print(f"[PostTerminationMiddleware] Processing request (response count: {self.response_count})")
|
||||
|
||||
# Check if we should terminate before processing
|
||||
if self.response_count >= self.max_responses:
|
||||
print(
|
||||
f"[PostTerminationMiddleware] Maximum responses ({self.max_responses}) reached. "
|
||||
"Terminating further processing."
|
||||
)
|
||||
raise MiddlewareTermination
|
||||
|
||||
# Allow the agent to process normally
|
||||
await call_next()
|
||||
|
||||
# Increment response count after processing
|
||||
self.response_count += 1
|
||||
|
||||
|
||||
async def pre_termination_middleware() -> None:
|
||||
"""Demonstrate pre-termination middleware that blocks requests with certain words."""
|
||||
print("\n--- Example 1: Pre-termination MiddlewareTypes ---")
|
||||
async with (
|
||||
AzureCliCredential() as credential,
|
||||
AzureAIAgentClient(credential=credential).as_agent(
|
||||
name="WeatherAgent",
|
||||
instructions="You are a helpful weather assistant.",
|
||||
tools=get_weather,
|
||||
middleware=[PreTerminationMiddleware(blocked_words=["bad", "inappropriate"])],
|
||||
) as agent,
|
||||
):
|
||||
# Test with normal query
|
||||
print("\n1. Normal query:")
|
||||
query = "What's the weather like in Seattle?"
|
||||
print(f"User: {query}")
|
||||
result = await agent.run(query)
|
||||
print(f"Agent: {result.text}")
|
||||
|
||||
# Test with blocked word
|
||||
print("\n2. Query with blocked word:")
|
||||
query = "What's the bad weather in New York?"
|
||||
print(f"User: {query}")
|
||||
result = await agent.run(query)
|
||||
print(f"Agent: {result.text}")
|
||||
|
||||
|
||||
async def post_termination_middleware() -> None:
|
||||
"""Demonstrate post-termination middleware that limits responses across multiple runs."""
|
||||
print("\n--- Example 2: Post-termination MiddlewareTypes ---")
|
||||
async with (
|
||||
AzureCliCredential() as credential,
|
||||
AzureAIAgentClient(credential=credential).as_agent(
|
||||
name="WeatherAgent",
|
||||
instructions="You are a helpful weather assistant.",
|
||||
tools=get_weather,
|
||||
middleware=[PostTerminationMiddleware(max_responses=1)],
|
||||
) as agent,
|
||||
):
|
||||
# First run (should work)
|
||||
print("\n1. First run:")
|
||||
query = "What's the weather in Paris?"
|
||||
print(f"User: {query}")
|
||||
result = await agent.run(query)
|
||||
print(f"Agent: {result.text}")
|
||||
|
||||
# Second run (should be terminated by middleware)
|
||||
print("\n2. Second run (should be terminated):")
|
||||
query = "What about the weather in London?"
|
||||
print(f"User: {query}")
|
||||
result = await agent.run(query)
|
||||
print(f"Agent: {result.text if result and result.text else 'No response (terminated)'}")
|
||||
|
||||
# Third run (should also be terminated)
|
||||
print("\n3. Third run (should also be terminated):")
|
||||
query = "And New York?"
|
||||
print(f"User: {query}")
|
||||
result = await agent.run(query)
|
||||
print(f"Agent: {result.text if result and result.text else 'No response (terminated)'}")
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
"""Example demonstrating middleware termination functionality."""
|
||||
print("=== MiddlewareTypes Termination Example ===")
|
||||
await pre_termination_middleware()
|
||||
await post_termination_middleware()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
@@ -0,0 +1,216 @@
|
||||
# Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
import asyncio
|
||||
import re
|
||||
from collections.abc import Awaitable, Callable
|
||||
from random import randint
|
||||
from typing import Annotated
|
||||
|
||||
from agent_framework import (
|
||||
AgentContext,
|
||||
AgentResponse,
|
||||
AgentResponseUpdate,
|
||||
ChatContext,
|
||||
ChatResponse,
|
||||
ChatResponseUpdate,
|
||||
Message,
|
||||
ResponseStream,
|
||||
Role,
|
||||
tool,
|
||||
)
|
||||
from agent_framework.openai import OpenAIResponsesClient
|
||||
from pydantic import Field
|
||||
|
||||
"""
|
||||
Result Override with MiddlewareTypes (Regular and Streaming)
|
||||
|
||||
This sample demonstrates how to use middleware to intercept and modify function results
|
||||
after execution, supporting both regular and streaming agent responses. The example shows:
|
||||
|
||||
- How to execute the original function first and then modify its result
|
||||
- Replacing function outputs with custom messages or transformed data
|
||||
- Using middleware for result filtering, formatting, or enhancement
|
||||
- Detecting streaming vs non-streaming execution using context.stream
|
||||
- Overriding streaming results with custom async generators
|
||||
|
||||
The weather override middleware lets the original weather function execute normally,
|
||||
then replaces its result with a custom "perfect weather" message. For streaming responses,
|
||||
it creates a custom async generator that yields the override message in chunks.
|
||||
"""
|
||||
|
||||
|
||||
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
|
||||
@tool(approval_mode="never_require")
|
||||
def get_weather(
|
||||
location: Annotated[str, Field(description="The location to get the weather for.")],
|
||||
) -> str:
|
||||
"""Get the weather for a given location."""
|
||||
conditions = ["sunny", "cloudy", "rainy", "stormy"]
|
||||
return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
|
||||
|
||||
|
||||
async def weather_override_middleware(context: ChatContext, call_next: Callable[[], Awaitable[None]]) -> None:
|
||||
"""Chat middleware that overrides weather results for both streaming and non-streaming cases."""
|
||||
|
||||
# Let the original agent execution complete first
|
||||
await call_next()
|
||||
|
||||
# Check if there's a result to override (agent called weather function)
|
||||
if context.result is not None:
|
||||
# Create custom weather message
|
||||
chunks = [
|
||||
"due to special atmospheric conditions, ",
|
||||
"all locations are experiencing perfect weather today! ",
|
||||
"Temperature is a comfortable 22°C with gentle breezes. ",
|
||||
"Perfect day for outdoor activities!",
|
||||
]
|
||||
|
||||
if context.stream and isinstance(context.result, ResponseStream):
|
||||
index = {"value": 0}
|
||||
|
||||
def _update_hook(update: ChatResponseUpdate) -> ChatResponseUpdate:
|
||||
for content in update.contents or []:
|
||||
if not content.text:
|
||||
continue
|
||||
content.text = f"Weather Advisory: [{index['value']}] {content.text}"
|
||||
index["value"] += 1
|
||||
return update
|
||||
|
||||
context.result.with_transform_hook(_update_hook)
|
||||
else:
|
||||
# For non-streaming: just replace with a new message
|
||||
current_text = context.result.text if isinstance(context.result, ChatResponse) else ""
|
||||
custom_message = f"Weather Advisory: [0] {''.join(chunks)} Original message was: {current_text}"
|
||||
context.result = ChatResponse(messages=[Message(role=Role.ASSISTANT, text=custom_message)])
|
||||
|
||||
|
||||
async def validate_weather_middleware(context: ChatContext, call_next: Callable[[], Awaitable[None]]) -> None:
|
||||
"""Chat middleware that simulates result validation for both streaming and non-streaming cases."""
|
||||
await call_next()
|
||||
|
||||
validation_note = "Validation: weather data verified."
|
||||
|
||||
if context.result is None:
|
||||
return
|
||||
|
||||
if context.stream and isinstance(context.result, ResponseStream):
|
||||
|
||||
def _append_validation_note(response: ChatResponse) -> ChatResponse:
|
||||
response.messages.append(Message(role=Role.ASSISTANT, text=validation_note))
|
||||
return response
|
||||
|
||||
context.result.with_finalizer(_append_validation_note)
|
||||
elif isinstance(context.result, ChatResponse):
|
||||
context.result.messages.append(Message(role=Role.ASSISTANT, text=validation_note))
|
||||
|
||||
|
||||
async def agent_cleanup_middleware(context: AgentContext, call_next: Callable[[], Awaitable[None]]) -> None:
|
||||
"""Agent middleware that validates chat middleware effects and cleans the result."""
|
||||
await call_next()
|
||||
|
||||
if context.result is None:
|
||||
return
|
||||
|
||||
validation_note = "Validation: weather data verified."
|
||||
|
||||
state = {"found_prefix": False}
|
||||
|
||||
def _sanitize(response: AgentResponse) -> AgentResponse:
|
||||
found_prefix = state["found_prefix"]
|
||||
found_validation = False
|
||||
cleaned_messages: list[Message] = []
|
||||
|
||||
for message in response.messages:
|
||||
text = message.text
|
||||
if text is None:
|
||||
cleaned_messages.append(message)
|
||||
continue
|
||||
|
||||
if validation_note in text:
|
||||
found_validation = True
|
||||
text = text.replace(validation_note, "").strip()
|
||||
if not text:
|
||||
continue
|
||||
|
||||
if "Weather Advisory:" in text:
|
||||
found_prefix = True
|
||||
text = text.replace("Weather Advisory:", "")
|
||||
|
||||
text = re.sub(r"\[\d+\]\s*", "", text)
|
||||
|
||||
cleaned_messages.append(
|
||||
Message(
|
||||
role=message.role,
|
||||
text=text.strip(),
|
||||
author_name=message.author_name,
|
||||
message_id=message.message_id,
|
||||
additional_properties=message.additional_properties,
|
||||
raw_representation=message.raw_representation,
|
||||
)
|
||||
)
|
||||
|
||||
if not found_prefix:
|
||||
raise RuntimeError("Expected chat middleware prefix not found in agent response.")
|
||||
if not found_validation:
|
||||
raise RuntimeError("Expected validation note not found in agent response.")
|
||||
|
||||
cleaned_messages.append(Message(role=Role.ASSISTANT, text=" Agent: OK"))
|
||||
response.messages = cleaned_messages
|
||||
return response
|
||||
|
||||
if context.stream and isinstance(context.result, ResponseStream):
|
||||
|
||||
def _clean_update(update: AgentResponseUpdate) -> AgentResponseUpdate:
|
||||
for content in update.contents or []:
|
||||
if not content.text:
|
||||
continue
|
||||
text = content.text
|
||||
if "Weather Advisory:" in text:
|
||||
state["found_prefix"] = True
|
||||
text = text.replace("Weather Advisory:", "")
|
||||
text = re.sub(r"\[\d+\]\s*", "", text)
|
||||
content.text = text
|
||||
return update
|
||||
|
||||
context.result.with_transform_hook(_clean_update)
|
||||
context.result.with_finalizer(_sanitize)
|
||||
elif isinstance(context.result, AgentResponse):
|
||||
context.result = _sanitize(context.result)
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
"""Example demonstrating result override with middleware for both streaming and non-streaming."""
|
||||
print("=== Result Override MiddlewareTypes Example ===")
|
||||
|
||||
# For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
|
||||
# authentication option.
|
||||
agent = OpenAIResponsesClient(
|
||||
middleware=[validate_weather_middleware, weather_override_middleware],
|
||||
).as_agent(
|
||||
name="WeatherAgent",
|
||||
instructions="You are a helpful weather assistant. Use the weather tool to get current conditions.",
|
||||
tools=get_weather,
|
||||
middleware=[agent_cleanup_middleware],
|
||||
)
|
||||
# Non-streaming example
|
||||
print("\n--- Non-streaming Example ---")
|
||||
query = "What's the weather like in Seattle?"
|
||||
print(f"User: {query}")
|
||||
result = await agent.run(query)
|
||||
print(f"Agent: {result}")
|
||||
|
||||
# Streaming example
|
||||
print("\n--- Streaming Example ---")
|
||||
query = "What's the weather like in Portland?"
|
||||
print(f"User: {query}")
|
||||
print("Agent: ", end="", flush=True)
|
||||
response = agent.run(query, stream=True)
|
||||
async for chunk in response:
|
||||
if chunk.text:
|
||||
print(chunk.text, end="", flush=True)
|
||||
print("\n")
|
||||
print(f"Final Result: {(await response.get_final_response()).text}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
@@ -0,0 +1,457 @@
|
||||
# Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
import asyncio
|
||||
from collections.abc import Awaitable, Callable
|
||||
from typing import Annotated
|
||||
|
||||
from agent_framework import FunctionInvocationContext, function_middleware, tool
|
||||
from agent_framework.openai import OpenAIChatClient
|
||||
from pydantic import Field
|
||||
|
||||
"""
|
||||
Runtime Context Delegation Patterns
|
||||
|
||||
This sample demonstrates different patterns for passing runtime context (API tokens,
|
||||
session data, etc.) to tools and sub-agents.
|
||||
|
||||
Patterns Demonstrated:
|
||||
|
||||
1. **Pattern 1: Single Agent with MiddlewareTypes & Closure** (Lines 130-180)
|
||||
- Best for: Single agent with multiple tools
|
||||
- How: MiddlewareTypes stores kwargs in container, tools access via closure
|
||||
- Pros: Simple, explicit state management
|
||||
- Cons: Requires container instance per agent
|
||||
|
||||
2. **Pattern 2: Hierarchical Agents with kwargs Propagation** (Lines 190-240)
|
||||
- Best for: Parent-child agent delegation with as_tool()
|
||||
- How: kwargs automatically propagate through as_tool() wrapper
|
||||
- Pros: Automatic, works with nested delegation, clean separation
|
||||
- Cons: None - this is the recommended pattern for hierarchical agents
|
||||
|
||||
3. **Pattern 3: Mixed - Hierarchical with MiddlewareTypes** (Lines 250-300)
|
||||
- Best for: Complex scenarios needing both delegation and state management
|
||||
- How: Combines automatic kwargs propagation with middleware processing
|
||||
- Pros: Maximum flexibility, can transform/validate context at each level
|
||||
- Cons: More complex setup
|
||||
|
||||
Key Concepts:
|
||||
- Runtime Context: Session-specific data like API tokens, user IDs, tenant info
|
||||
- MiddlewareTypes: Intercepts function calls to access/modify kwargs
|
||||
- Closure: Functions capturing variables from outer scope
|
||||
- kwargs Propagation: Automatic forwarding of runtime context through delegation chains
|
||||
"""
|
||||
|
||||
|
||||
class SessionContextContainer:
|
||||
"""Container for runtime session context accessible via closure."""
|
||||
|
||||
def __init__(self) -> None:
|
||||
"""Initialize with None values for runtime context."""
|
||||
self.api_token: str | None = None
|
||||
self.user_id: str | None = None
|
||||
self.session_metadata: dict[str, str] = {}
|
||||
|
||||
async def inject_context_middleware(
|
||||
self,
|
||||
context: FunctionInvocationContext,
|
||||
call_next: Callable[[], Awaitable[None]],
|
||||
) -> None:
|
||||
"""MiddlewareTypes that extracts runtime context from kwargs and stores in container.
|
||||
|
||||
This middleware runs before tool execution and makes runtime context
|
||||
available to tools via the container instance.
|
||||
"""
|
||||
# Extract runtime context from kwargs
|
||||
self.api_token = context.kwargs.get("api_token")
|
||||
self.user_id = context.kwargs.get("user_id")
|
||||
self.session_metadata = context.kwargs.get("session_metadata", {})
|
||||
|
||||
# Log what we captured (for demonstration)
|
||||
if self.api_token or self.user_id:
|
||||
print("[MiddlewareTypes] Captured runtime context:")
|
||||
print(f" - API Token: {'[PRESENT]' if self.api_token else '[NOT PROVIDED]'}")
|
||||
print(f" - User ID: {'[PRESENT]' if self.user_id else '[NOT PROVIDED]'}")
|
||||
print(f" - Session Metadata Keys: {list(self.session_metadata.keys())}")
|
||||
|
||||
# Continue to tool execution
|
||||
await call_next()
|
||||
|
||||
|
||||
# Create a container instance that will be shared via closure
|
||||
runtime_context = SessionContextContainer()
|
||||
|
||||
|
||||
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
|
||||
@tool(approval_mode="never_require")
|
||||
async def send_email(
|
||||
to: Annotated[str, Field(description="Recipient email address")],
|
||||
subject: Annotated[str, Field(description="Email subject line")],
|
||||
body: Annotated[str, Field(description="Email body content")],
|
||||
) -> str:
|
||||
"""Send an email using authenticated API (simulated).
|
||||
|
||||
This function accesses runtime context (API token, user ID) via closure
|
||||
from the runtime_context container.
|
||||
"""
|
||||
# Access runtime context via closure
|
||||
token = runtime_context.api_token
|
||||
user_id = runtime_context.user_id
|
||||
tenant = runtime_context.session_metadata.get("tenant", "unknown")
|
||||
|
||||
print("\n[send_email] Executing with runtime context:")
|
||||
print(f" - Token: {'[PRESENT]' if token else '[NOT PROVIDED]'}")
|
||||
print(f" - User ID: {'[PRESENT]' if user_id else '[NOT PROVIDED]'}")
|
||||
print(f" - Tenant: {'[PRESENT]' if tenant and tenant != 'unknown' else '[NOT PROVIDED]'}")
|
||||
print(" - Recipient count: 1")
|
||||
print(f" - Subject length: {len(subject)} chars")
|
||||
|
||||
# Simulate API call with authentication
|
||||
if not token:
|
||||
return "ERROR: No API token provided - cannot send email"
|
||||
|
||||
# Simulate sending email
|
||||
return f"Email sent to {to} from user {user_id} (tenant: {tenant}). Subject: '{subject}'"
|
||||
|
||||
|
||||
@tool(approval_mode="never_require")
|
||||
async def send_notification(
|
||||
message: Annotated[str, Field(description="Notification message to send")],
|
||||
priority: Annotated[str, Field(description="Priority level: low, medium, high")] = "medium",
|
||||
) -> str:
|
||||
"""Send a push notification using authenticated API (simulated).
|
||||
|
||||
This function accesses runtime context via closure from runtime_context.
|
||||
"""
|
||||
token = runtime_context.api_token
|
||||
user_id = runtime_context.user_id
|
||||
|
||||
print("\n[send_notification] Executing with runtime context:")
|
||||
print(f" - Token: {'[PRESENT]' if token else '[NOT PROVIDED]'}")
|
||||
print(f" - User ID: {'[PRESENT]' if user_id else '[NOT PROVIDED]'}")
|
||||
print(f" - Message length: {len(message)} chars")
|
||||
print(f" - Priority: {priority}")
|
||||
|
||||
if not token:
|
||||
return "ERROR: No API token provided - cannot send notification"
|
||||
|
||||
return f"Notification sent to user {user_id} with priority {priority}: {message}"
|
||||
|
||||
|
||||
async def pattern_1_single_agent_with_closure() -> None:
|
||||
"""Pattern 1: Single agent with middleware and closure for runtime context."""
|
||||
print("\n" + "=" * 70)
|
||||
print("PATTERN 1: Single Agent with MiddlewareTypes & Closure")
|
||||
print("=" * 70)
|
||||
print("Use case: Single agent with multiple tools sharing runtime context")
|
||||
print()
|
||||
|
||||
client = OpenAIChatClient(model_id="gpt-4o-mini")
|
||||
|
||||
# Create agent with both tools and shared context via middleware
|
||||
communication_agent = client.as_agent(
|
||||
name="communication_agent",
|
||||
instructions=(
|
||||
"You are a communication assistant that can send emails and notifications. "
|
||||
"Use send_email for email tasks and send_notification for notification tasks."
|
||||
),
|
||||
tools=[send_email, send_notification],
|
||||
# Both tools share the same context container via middleware
|
||||
middleware=[runtime_context.inject_context_middleware],
|
||||
)
|
||||
|
||||
# Test 1: Send email with runtime context
|
||||
print("\n" + "=" * 70)
|
||||
print("TEST 1: Email with Runtime Context")
|
||||
print("=" * 70)
|
||||
|
||||
user_query = (
|
||||
"Send an email to john@example.com with subject 'Meeting Tomorrow' and body 'Don't forget our 2pm meeting.'"
|
||||
)
|
||||
print(f"\nUser: {user_query}")
|
||||
|
||||
result1 = await communication_agent.run(
|
||||
user_query,
|
||||
# Runtime context passed as kwargs
|
||||
api_token="sk-test-token-xyz-789",
|
||||
user_id="user-12345",
|
||||
session_metadata={"tenant": "acme-corp", "region": "us-west"},
|
||||
)
|
||||
|
||||
print(f"\nAgent: {result1.text}")
|
||||
|
||||
# Test 2: Send notification with different runtime context
|
||||
print("\n" + "=" * 70)
|
||||
print("TEST 2: Notification with Different Runtime Context")
|
||||
print("=" * 70)
|
||||
|
||||
user_query2 = "Send a high priority notification saying 'Your order has shipped!'"
|
||||
print(f"\nUser: {user_query2}")
|
||||
|
||||
result2 = await communication_agent.run(
|
||||
user_query2,
|
||||
# Different runtime context for this request
|
||||
api_token="sk-prod-token-abc-456",
|
||||
user_id="user-67890",
|
||||
session_metadata={"tenant": "store-inc", "region": "eu-central"},
|
||||
)
|
||||
|
||||
print(f"\nAgent: {result2.text}")
|
||||
|
||||
# Test 3: Both email and notification in one request
|
||||
print("\n" + "=" * 70)
|
||||
print("TEST 3: Multiple Tools in One Request")
|
||||
print("=" * 70)
|
||||
|
||||
user_query3 = (
|
||||
"Send an email to alice@example.com about the new feature launch "
|
||||
"and also send a notification to remind about the team meeting."
|
||||
)
|
||||
print(f"\nUser: {user_query3}")
|
||||
|
||||
result3 = await communication_agent.run(
|
||||
user_query3,
|
||||
api_token="sk-dev-token-def-123",
|
||||
user_id="user-11111",
|
||||
session_metadata={"tenant": "dev-team", "region": "us-east"},
|
||||
)
|
||||
|
||||
print(f"\nAgent: {result3.text}")
|
||||
|
||||
# Test 4: Missing context - show error handling
|
||||
print("\n" + "=" * 70)
|
||||
print("TEST 4: Missing Runtime Context (Error Case)")
|
||||
print("=" * 70)
|
||||
|
||||
user_query4 = "Send an email to test@example.com with subject 'Test'"
|
||||
print(f"\nUser: {user_query4}")
|
||||
print("Note: Running WITHOUT api_token to demonstrate error handling")
|
||||
|
||||
result4 = await communication_agent.run(
|
||||
user_query4,
|
||||
# Missing api_token - tools should handle gracefully
|
||||
user_id="user-22222",
|
||||
)
|
||||
|
||||
print(f"\nAgent: {result4.text}")
|
||||
|
||||
print("\n✓ Pattern 1 complete - MiddlewareTypes & closure pattern works for single agents")
|
||||
|
||||
|
||||
# Pattern 2: Hierarchical agents with automatic kwargs propagation
|
||||
# ================================================================
|
||||
|
||||
|
||||
# Create tools for sub-agents (these will use kwargs propagation)
|
||||
@tool(approval_mode="never_require")
|
||||
async def send_email_v2(
|
||||
to: Annotated[str, Field(description="Recipient email")],
|
||||
subject: Annotated[str, Field(description="Subject")],
|
||||
body: Annotated[str, Field(description="Body")],
|
||||
) -> str:
|
||||
"""Send email - demonstrates kwargs propagation pattern."""
|
||||
# In this pattern, we can create a middleware to access kwargs
|
||||
# But for simplicity, we'll just simulate the operation
|
||||
return f"Email sent to {to} with subject '{subject}'"
|
||||
|
||||
|
||||
@tool(approval_mode="never_require")
|
||||
async def send_sms(
|
||||
phone: Annotated[str, Field(description="Phone number")],
|
||||
message: Annotated[str, Field(description="SMS message")],
|
||||
) -> str:
|
||||
"""Send SMS message."""
|
||||
return f"SMS sent to {phone}: {message}"
|
||||
|
||||
|
||||
async def pattern_2_hierarchical_with_kwargs_propagation() -> None:
|
||||
"""Pattern 2: Hierarchical agents with automatic kwargs propagation through as_tool()."""
|
||||
print("\n" + "=" * 70)
|
||||
print("PATTERN 2: Hierarchical Agents with kwargs Propagation")
|
||||
print("=" * 70)
|
||||
print("Use case: Parent agent delegates to specialized sub-agents")
|
||||
print("Feature: Runtime kwargs automatically propagate through as_tool()")
|
||||
print()
|
||||
|
||||
# Track kwargs at each level
|
||||
email_agent_kwargs: dict[str, object] = {}
|
||||
sms_agent_kwargs: dict[str, object] = {}
|
||||
|
||||
@function_middleware
|
||||
async def email_kwargs_tracker(
|
||||
context: FunctionInvocationContext, call_next: Callable[[], Awaitable[None]]
|
||||
) -> None:
|
||||
email_agent_kwargs.update(context.kwargs)
|
||||
print(f"[EmailAgent] Received runtime context: {list(context.kwargs.keys())}")
|
||||
await call_next()
|
||||
|
||||
@function_middleware
|
||||
async def sms_kwargs_tracker(
|
||||
context: FunctionInvocationContext, call_next: Callable[[], Awaitable[None]]
|
||||
) -> None:
|
||||
sms_agent_kwargs.update(context.kwargs)
|
||||
print(f"[SMSAgent] Received runtime context: {list(context.kwargs.keys())}")
|
||||
await call_next()
|
||||
|
||||
client = OpenAIChatClient(model_id="gpt-4o-mini")
|
||||
|
||||
# Create specialized sub-agents
|
||||
email_agent = client.as_agent(
|
||||
name="email_agent",
|
||||
instructions="You send emails using the send_email_v2 tool.",
|
||||
tools=[send_email_v2],
|
||||
middleware=[email_kwargs_tracker],
|
||||
)
|
||||
|
||||
sms_agent = client.as_agent(
|
||||
name="sms_agent",
|
||||
instructions="You send SMS messages using the send_sms tool.",
|
||||
tools=[send_sms],
|
||||
middleware=[sms_kwargs_tracker],
|
||||
)
|
||||
|
||||
# Create coordinator that delegates to sub-agents
|
||||
coordinator = client.as_agent(
|
||||
name="coordinator",
|
||||
instructions=(
|
||||
"You coordinate communication tasks. "
|
||||
"Use email_sender for emails and sms_sender for SMS. "
|
||||
"Delegate to the appropriate specialized agent."
|
||||
),
|
||||
tools=[
|
||||
email_agent.as_tool(
|
||||
name="email_sender",
|
||||
description="Send emails to recipients",
|
||||
arg_name="task",
|
||||
),
|
||||
sms_agent.as_tool(
|
||||
name="sms_sender",
|
||||
description="Send SMS messages",
|
||||
arg_name="task",
|
||||
),
|
||||
],
|
||||
)
|
||||
|
||||
# Test: Runtime context propagates automatically
|
||||
print("Test: Send email with runtime context\n")
|
||||
await coordinator.run(
|
||||
"Send an email to john@example.com with subject 'Meeting' and body 'See you at 2pm'",
|
||||
api_token="secret-token-abc",
|
||||
user_id="user-999",
|
||||
tenant_id="tenant-acme",
|
||||
)
|
||||
|
||||
print(f"\n[Verification] EmailAgent received kwargs keys: {list(email_agent_kwargs.keys())}")
|
||||
print(f" - api_token: {'[PRESENT]' if email_agent_kwargs.get('api_token') else '[NOT PROVIDED]'}")
|
||||
print(f" - user_id: {'[PRESENT]' if email_agent_kwargs.get('user_id') else '[NOT PROVIDED]'}")
|
||||
print(f" - tenant_id: {'[PRESENT]' if email_agent_kwargs.get('tenant_id') else '[NOT PROVIDED]'}")
|
||||
|
||||
print("\n✓ Pattern 2 complete - kwargs automatically propagate through as_tool()")
|
||||
|
||||
|
||||
# Pattern 3: Mixed pattern - hierarchical with middleware processing
|
||||
# ===================================================================
|
||||
|
||||
|
||||
class AuthContextMiddleware:
|
||||
"""MiddlewareTypes that validates and transforms runtime context."""
|
||||
|
||||
def __init__(self) -> None:
|
||||
self.validated_tokens: list[str] = []
|
||||
|
||||
async def validate_and_track(
|
||||
self, context: FunctionInvocationContext, call_next: Callable[[], Awaitable[None]]
|
||||
) -> None:
|
||||
"""Validate API token and track usage."""
|
||||
api_token = context.kwargs.get("api_token")
|
||||
|
||||
if api_token:
|
||||
# Simulate token validation
|
||||
if api_token.startswith("valid-"):
|
||||
print("[AuthMiddleware] Token validated successfully")
|
||||
self.validated_tokens.append(api_token)
|
||||
else:
|
||||
print("[AuthMiddleware] Token validation failed")
|
||||
# Could set context.terminate = True to block execution
|
||||
else:
|
||||
print("[AuthMiddleware] No API token provided")
|
||||
|
||||
await call_next()
|
||||
|
||||
|
||||
@tool(approval_mode="never_require")
|
||||
async def protected_operation(operation: Annotated[str, Field(description="Operation to perform")]) -> str:
|
||||
"""Protected operation that requires authentication."""
|
||||
return f"Executed protected operation: {operation}"
|
||||
|
||||
|
||||
async def pattern_3_hierarchical_with_middleware() -> None:
|
||||
"""Pattern 3: Hierarchical agents with middleware processing at each level."""
|
||||
print("\n" + "=" * 70)
|
||||
print("PATTERN 3: Hierarchical with MiddlewareTypes Processing")
|
||||
print("=" * 70)
|
||||
print("Use case: Multi-level validation/transformation of runtime context")
|
||||
print()
|
||||
|
||||
auth_middleware = AuthContextMiddleware()
|
||||
|
||||
client = OpenAIChatClient(model_id="gpt-4o-mini")
|
||||
|
||||
# Sub-agent with validation middleware
|
||||
protected_agent = client.as_agent(
|
||||
name="protected_agent",
|
||||
instructions="You perform protected operations that require authentication.",
|
||||
tools=[protected_operation],
|
||||
middleware=[auth_middleware.validate_and_track],
|
||||
)
|
||||
|
||||
# Coordinator delegates to protected agent
|
||||
coordinator = client.as_agent(
|
||||
name="coordinator",
|
||||
instructions="You coordinate protected operations. Delegate to protected_executor.",
|
||||
tools=[
|
||||
protected_agent.as_tool(
|
||||
name="protected_executor",
|
||||
description="Execute protected operations",
|
||||
)
|
||||
],
|
||||
)
|
||||
|
||||
# Test with valid token
|
||||
print("Test 1: Valid token\n")
|
||||
await coordinator.run(
|
||||
"Execute operation: backup_database",
|
||||
api_token="valid-token-xyz-789",
|
||||
user_id="admin-123",
|
||||
)
|
||||
|
||||
# Test with invalid token
|
||||
print("\nTest 2: Invalid token\n")
|
||||
await coordinator.run(
|
||||
"Execute operation: delete_records",
|
||||
api_token="invalid-token-bad",
|
||||
user_id="user-456",
|
||||
)
|
||||
|
||||
print(f"\n[Validation Summary] Validated tokens: {len(auth_middleware.validated_tokens)}")
|
||||
print("✓ Pattern 3 complete - MiddlewareTypes can validate/transform context at each level")
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
"""Demonstrate all runtime context delegation patterns."""
|
||||
print("=" * 70)
|
||||
print("Runtime Context Delegation Patterns Demo")
|
||||
print("=" * 70)
|
||||
print()
|
||||
|
||||
# Run Pattern 1
|
||||
await pattern_1_single_agent_with_closure()
|
||||
|
||||
# Run Pattern 2
|
||||
await pattern_2_hierarchical_with_kwargs_propagation()
|
||||
|
||||
# Run Pattern 3
|
||||
await pattern_3_hierarchical_with_middleware()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
@@ -0,0 +1,132 @@
|
||||
# Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
import asyncio
|
||||
from collections.abc import Awaitable, Callable
|
||||
from random import randint
|
||||
from typing import Annotated
|
||||
|
||||
from agent_framework import (
|
||||
FunctionInvocationContext,
|
||||
tool,
|
||||
)
|
||||
from agent_framework.azure import AzureAIAgentClient
|
||||
from azure.identity.aio import AzureCliCredential
|
||||
from pydantic import Field
|
||||
|
||||
"""
|
||||
Shared State Function-based MiddlewareTypes Example
|
||||
|
||||
This sample demonstrates how to implement function-based middleware within a class to share state.
|
||||
The example includes:
|
||||
|
||||
- A MiddlewareContainer class with two simple function middleware methods
|
||||
- First middleware: Counts function calls and stores the count in shared state
|
||||
- Second middleware: Uses the shared count to add call numbers to function results
|
||||
|
||||
This approach shows how middleware can work together by sharing state within the same class instance.
|
||||
"""
|
||||
|
||||
|
||||
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
|
||||
@tool(approval_mode="never_require")
|
||||
def get_weather(
|
||||
location: Annotated[str, Field(description="The location to get the weather for.")],
|
||||
) -> str:
|
||||
"""Get the weather for a given location."""
|
||||
conditions = ["sunny", "cloudy", "rainy", "stormy"]
|
||||
return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
|
||||
|
||||
|
||||
@tool(approval_mode="never_require")
|
||||
def get_time(
|
||||
timezone: Annotated[str, Field(description="The timezone to get the time for.")] = "UTC",
|
||||
) -> str:
|
||||
"""Get the current time for a given timezone."""
|
||||
import datetime
|
||||
|
||||
return f"The current time in {timezone} is {datetime.datetime.now().strftime('%H:%M:%S')}"
|
||||
|
||||
|
||||
class MiddlewareContainer:
|
||||
"""Container class that holds middleware functions with shared state."""
|
||||
|
||||
def __init__(self) -> None:
|
||||
# Simple shared state: count function calls
|
||||
self.call_count: int = 0
|
||||
|
||||
async def call_counter_middleware(
|
||||
self,
|
||||
context: FunctionInvocationContext,
|
||||
call_next: Callable[[], Awaitable[None]],
|
||||
) -> None:
|
||||
"""First middleware: increments call count in shared state."""
|
||||
# Increment the shared call count
|
||||
self.call_count += 1
|
||||
|
||||
print(f"[CallCounter] This is function call #{self.call_count}")
|
||||
|
||||
# Call the next middleware/function
|
||||
await call_next()
|
||||
|
||||
async def result_enhancer_middleware(
|
||||
self,
|
||||
context: FunctionInvocationContext,
|
||||
call_next: Callable[[], Awaitable[None]],
|
||||
) -> None:
|
||||
"""Second middleware: uses shared call count to enhance function results."""
|
||||
print(f"[ResultEnhancer] Current total calls so far: {self.call_count}")
|
||||
|
||||
# Call the next middleware/function
|
||||
await call_next()
|
||||
|
||||
# After function execution, enhance the result using shared state
|
||||
if context.result:
|
||||
enhanced_result = f"[Call #{self.call_count}] {context.result}"
|
||||
context.result = enhanced_result
|
||||
print("[ResultEnhancer] Enhanced result with call number")
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
"""Example demonstrating shared state function-based middleware."""
|
||||
print("=== Shared State Function-based MiddlewareTypes Example ===")
|
||||
|
||||
# Create middleware container with shared state
|
||||
middleware_container = MiddlewareContainer()
|
||||
|
||||
# For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
|
||||
# authentication option.
|
||||
async with (
|
||||
AzureCliCredential() as credential,
|
||||
AzureAIAgentClient(credential=credential).as_agent(
|
||||
name="UtilityAgent",
|
||||
instructions="You are a helpful assistant that can provide weather information and current time.",
|
||||
tools=[get_weather, get_time],
|
||||
# Pass both middleware functions from the same container instance
|
||||
# Order matters: counter runs first to increment count,
|
||||
# then result enhancer uses the updated count
|
||||
middleware=[
|
||||
middleware_container.call_counter_middleware,
|
||||
middleware_container.result_enhancer_middleware,
|
||||
],
|
||||
) as agent,
|
||||
):
|
||||
# Test multiple requests to see shared state in action
|
||||
queries = [
|
||||
"What's the weather like in New York?",
|
||||
"What time is it in London?",
|
||||
"What's the weather in Tokyo?",
|
||||
]
|
||||
|
||||
for i, query in enumerate(queries, 1):
|
||||
print(f"\n--- Query {i} ---")
|
||||
print(f"User: {query}")
|
||||
result = await agent.run(query)
|
||||
print(f"Agent: {result.text if result.text else 'No response'}")
|
||||
|
||||
# Display final statistics
|
||||
print("\n=== Final Statistics ===")
|
||||
print(f"Total function calls made: {middleware_container.call_count}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
@@ -0,0 +1,102 @@
|
||||
# Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
import asyncio
|
||||
from collections.abc import Awaitable, Callable
|
||||
from typing import Annotated
|
||||
|
||||
from agent_framework import (
|
||||
AgentContext,
|
||||
ChatMessageStore,
|
||||
tool,
|
||||
)
|
||||
from agent_framework.azure import AzureOpenAIChatClient
|
||||
from azure.identity import AzureCliCredential
|
||||
from pydantic import Field
|
||||
|
||||
"""
|
||||
Thread Behavior MiddlewareTypes Example
|
||||
|
||||
This sample demonstrates how middleware can access and track thread state across multiple agent runs.
|
||||
The example shows:
|
||||
|
||||
- How AgentContext.thread property behaves across multiple runs
|
||||
- How middleware can access conversation history through the thread
|
||||
- The timing of when thread messages are populated (before vs after call_next() call)
|
||||
- How to track thread state changes across runs
|
||||
|
||||
Key behaviors demonstrated:
|
||||
1. First run: context.messages is populated, context.thread is initially empty (before call_next())
|
||||
2. After call_next(): thread contains input message + response from agent
|
||||
3. Second run: context.messages contains only current input, thread contains previous history
|
||||
4. After call_next(): thread contains full conversation history (all previous + current messages)
|
||||
"""
|
||||
|
||||
|
||||
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
|
||||
@tool(approval_mode="never_require")
|
||||
def get_weather(
|
||||
location: Annotated[str, Field(description="The location to get the weather for.")],
|
||||
) -> str:
|
||||
"""Get the weather for a given location."""
|
||||
from random import randint
|
||||
|
||||
conditions = ["sunny", "cloudy", "rainy", "stormy"]
|
||||
return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
|
||||
|
||||
|
||||
async def thread_tracking_middleware(
|
||||
context: AgentContext,
|
||||
call_next: Callable[[], Awaitable[None]],
|
||||
) -> None:
|
||||
"""MiddlewareTypes that tracks and logs thread behavior across runs."""
|
||||
thread_messages = []
|
||||
if context.thread and context.thread.message_store:
|
||||
thread_messages = await context.thread.message_store.list_messages()
|
||||
|
||||
print(f"[MiddlewareTypes pre-execution] Current input messages: {len(context.messages)}")
|
||||
print(f"[MiddlewareTypes pre-execution] Thread history messages: {len(thread_messages)}")
|
||||
|
||||
# Call call_next to execute the agent
|
||||
await call_next()
|
||||
|
||||
# Check thread state after agent execution
|
||||
updated_thread_messages = []
|
||||
if context.thread and context.thread.message_store:
|
||||
updated_thread_messages = await context.thread.message_store.list_messages()
|
||||
|
||||
print(f"[MiddlewareTypes post-execution] Updated thread messages: {len(updated_thread_messages)}")
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
"""Example demonstrating thread behavior in middleware across multiple runs."""
|
||||
print("=== Thread Behavior MiddlewareTypes Example ===")
|
||||
|
||||
# For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
|
||||
# authentication option.
|
||||
agent = AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
|
||||
name="WeatherAgent",
|
||||
instructions="You are a helpful weather assistant.",
|
||||
tools=get_weather,
|
||||
middleware=[thread_tracking_middleware],
|
||||
# Configure agent with message store factory to persist conversation history
|
||||
chat_message_store_factory=ChatMessageStore,
|
||||
)
|
||||
|
||||
# Create a thread that will persist messages between runs
|
||||
thread = agent.get_new_thread()
|
||||
|
||||
print("\nFirst Run:")
|
||||
query1 = "What's the weather like in Tokyo?"
|
||||
print(f"User: {query1}")
|
||||
result1 = await agent.run(query1, thread=thread)
|
||||
print(f"Agent: {result1.text}")
|
||||
|
||||
print("\nSecond Run:")
|
||||
query2 = "How about in London?"
|
||||
print(f"User: {query2}")
|
||||
result2 = await agent.run(query2, thread=thread)
|
||||
print(f"Agent: {result2.text}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
Reference in New Issue
Block a user