Python: Rebase durable task feature branch with main (#2806)

python/samples/getting_started/tools/README.md

@@ -11,6 +11,8 @@ This folder contains examples demonstrating how to use AI functions (tools) with
 | [`ai_function_recover_from_failures.py`](ai_function_recover_from_failures.py) | Demonstrates graceful error handling when tools raise exceptions. Shows how agents receive error information and can recover from failures, deciding whether to retry or respond differently based on the exception. |
 | [`ai_function_with_approval.py`](ai_function_with_approval.py) | Shows how to implement user approval workflows for function calls without using threads. Demonstrates both streaming and non-streaming approval patterns where users can approve or reject function executions before they run. |
 | [`ai_function_with_approval_and_threads.py`](ai_function_with_approval_and_threads.py) | Demonstrates tool approval workflows using threads for automatic conversation history management. Shows how threads simplify approval workflows by automatically storing and retrieving conversation context. Includes both approval and rejection examples. |
+| [`ai_function_with_kwargs.py`](ai_function_with_kwargs.py) | Demonstrates how to inject custom arguments (context) into an AI function from the agent's run method. Useful for passing runtime information like access tokens or user IDs that the tool needs but the model shouldn't see. |
+| [`ai_function_with_thread_injection.py`](ai_function_with_thread_injection.py) | Shows how to access the current `thread` object inside an AI function via `**kwargs`. |
 | [`ai_function_with_max_exceptions.py`](ai_function_with_max_exceptions.py) | Shows how to limit the number of times a tool can fail with exceptions using `max_invocation_exceptions`. Useful for preventing expensive tools from being called repeatedly when they keep failing. |
 | [`ai_function_with_max_invocations.py`](ai_function_with_max_invocations.py) | Demonstrates limiting the total number of times a tool can be invoked using `max_invocations`. Useful for rate-limiting expensive operations or ensuring tools are only called a specific number of times per conversation. |
 | [`ai_functions_in_class.py`](ai_functions_in_class.py) | Shows how to use `ai_function` decorator with class methods to create stateful tools. Demonstrates how class state can control tool behavior dynamically, allowing you to adjust tool functionality at runtime by modifying class properties. |

python/samples/getting_started/tools/ai_function_with_kwargs.py

@@ -0,0 +1,53 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import Annotated, Any
+
+from agent_framework import ai_function
+from agent_framework.openai import OpenAIResponsesClient
+from pydantic import Field
+
+"""
+AI Function with kwargs Example
+
+This example demonstrates how to inject custom keyword arguments (kwargs) into an AI function
+from the agent's run method, without exposing them to the AI model.
+
+This is useful for passing runtime information like access tokens, user IDs, or
+request-specific context that the tool needs but the model shouldn't know about
+or provide.
+"""
+
+
+# Define the function tool with **kwargs to accept injected arguments
+@ai_function
+def get_weather(
+    location: Annotated[str, Field(description="The location to get the weather for.")],
+    **kwargs: Any,
+) -> str:
+    """Get the weather for a given location."""
+    # Extract the injected argument from kwargs
+    user_id = kwargs.get("user_id", "unknown")
+
+    # Simulate using the user_id for logging or personalization
+    print(f"Getting weather for user: {user_id}")
+
+    return f"The weather in {location} is cloudy with a high of 15°C."
+
+
+async def main() -> None:
+    agent = OpenAIResponsesClient().create_agent(
+        name="WeatherAgent",
+        instructions="You are a helpful weather assistant.",
+        tools=[get_weather],
+    )
+
+    # Pass the injected argument when running the agent
+    # The 'user_id' kwarg will be passed down to the tool execution via **kwargs
+    response = await agent.run("What is the weather like in Amsterdam?", user_id="user_123")
+
+    print(f"Agent: {response.text}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/tools/ai_function_with_thread_injection.py

@@ -0,0 +1,52 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import Annotated, Any
+
+from agent_framework import AgentThread, ai_function
+from agent_framework.openai import OpenAIChatClient
+from pydantic import Field
+
+"""
+AI Function with Thread Injection Example
+
+This example demonstrates the behavior when passing 'thread' to agent.run()
+and accessing that thread in AI function.
+"""
+
+
+# Define the function tool with **kwargs
+@ai_function
+async def get_weather(
+    location: Annotated[str, Field(description="The location to get the weather for.")],
+    **kwargs: Any,
+) -> str:
+    """Get the weather for a given location."""
+    # Get thread object from kwargs
+    thread = kwargs.get("thread")
+    if thread and isinstance(thread, AgentThread):
+        if thread.message_store:
+            messages = await thread.message_store.list_messages()
+            print(f"Thread contains {len(messages)} messages.")
+        elif thread.service_thread_id:
+            print(f"Thread ID: {thread.service_thread_id}.")
+
+    return f"The weather in {location} is cloudy."
+
+
+async def main() -> None:
+    agent = OpenAIChatClient().create_agent(
+        name="WeatherAgent", instructions="You are a helpful weather assistant.", tools=[get_weather]
+    )
+
+    # Create a thread
+    thread = agent.get_new_thread()
+
+    # Run the agent with the thread
+    print(f"Agent: {await agent.run('What is the weather in London?', thread=thread)}")
+    print(f"Agent: {await agent.run('What is the weather in Amsterdam?', thread=thread)}")
+    print(f"Agent: {await agent.run('What cities did I ask about?', thread=thread)}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())