Merge branch 'main' into feature-python-foundry-agents

python/samples/getting_started/tools/README.md

@@ -0,0 +1,119 @@
+# Tools Examples
+
+This folder contains examples demonstrating how to use AI functions (tools) with the Agent Framework. AI functions allow agents to interact with external systems, perform computations, and execute custom logic.
+
+## Examples
+
+| File | Description |
+|------|-------------|
+| [`ai_function_declaration_only.py`](ai_function_declaration_only.py) | Demonstrates how to create function declarations without implementations. Useful for testing agent reasoning about tool usage or when tools are defined elsewhere. Shows how agents request tool calls even when the tool won't be executed. |
+| [`ai_function_from_dict_with_dependency_injection.py`](ai_function_from_dict_with_dependency_injection.py) | Shows how to create AI functions from dictionary definitions using dependency injection. The function implementation is injected at runtime during deserialization, enabling dynamic tool creation and configuration. Note: This serialization/deserialization feature is in active development. |
+| [`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_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. |
+
+## Key Concepts
+
+### AI Function Features
+
+- **Function Declarations**: Define tool schemas without implementations for testing or external tools
+- **Dependency Injection**: Create tools from configurations with runtime-injected implementations
+- **Error Handling**: Gracefully handle and recover from tool execution failures
+- **Approval Workflows**: Require user approval before executing sensitive or important operations
+- **Invocation Limits**: Control how many times tools can be called or fail
+- **Stateful Tools**: Use class methods as tools to maintain state and dynamically control behavior
+
+### Common Patterns
+
+#### Basic Tool Definition
+
+```python
+from agent_framework import ai_function
+from typing import Annotated
+
+@ai_function
+def my_tool(param: Annotated[str, "Description"]) -> str:
+    """Tool description for the AI."""
+    return f"Result: {param}"
+```
+
+#### Tool with Approval
+
+```python
+@ai_function(approval_mode="always_require")
+def sensitive_operation(data: Annotated[str, "Data to process"]) -> str:
+    """This requires user approval before execution."""
+    return f"Processed: {data}"
+```
+
+#### Tool with Invocation Limits
+
+```python
+@ai_function(max_invocations=3)
+def limited_tool() -> str:
+    """Can only be called 3 times total."""
+    return "Result"
+
+@ai_function(max_invocation_exceptions=2)
+def fragile_tool() -> str:
+    """Can only fail 2 times before being disabled."""
+    return "Result"
+```
+
+#### Stateful Tools with Classes
+
+```python
+class MyTools:
+    def __init__(self, mode: str = "normal"):
+        self.mode = mode
+
+    def process(self, data: Annotated[str, "Data to process"]) -> str:
+        """Process data based on current mode."""
+        if self.mode == "safe":
+            return f"Safely processed: {data}"
+        return f"Processed: {data}"
+
+# Create instance and use methods as tools
+tools = MyTools(mode="safe")
+agent = client.create_agent(tools=tools.process)
+
+# Change behavior dynamically
+tools.mode = "normal"
+```
+
+### Error Handling
+
+When tools raise exceptions:
+1. The exception is captured and sent to the agent as a function result
+2. The agent receives the error message and can reason about what went wrong
+3. The agent can retry with different parameters, use alternative tools, or explain the issue to the user
+4. With invocation limits, tools can be disabled after repeated failures
+
+### Approval Workflows
+
+Two approaches for handling approvals:
+
+1. **Without Threads**: Manually manage conversation context, including the query, approval request, and response in each iteration
+2. **With Threads**: Thread automatically manages conversation history, simplifying the approval workflow
+
+## Usage Tips
+
+- Use **declaration-only** functions when you want to test agent reasoning without execution
+- Use **dependency injection** for dynamic tool configuration and plugin architectures
+- Implement **approval workflows** for operations that modify data, spend money, or require human oversight
+- Set **invocation limits** to prevent runaway costs or infinite loops with expensive tools
+- Handle **exceptions gracefully** to create robust agents that can recover from failures
+- Use **class-based tools** when you need to maintain state or dynamically adjust tool behavior at runtime
+
+## Running the Examples
+
+Each example is a standalone Python script that can be run directly:
+
+```bash
+uv run python ai_function_with_approval.py
+```
+
+Make sure you have the necessary environment variables configured (like `OPENAI_API_KEY` or Azure credentials) before running the examples.

python/samples/getting_started/tools/ai_function_declaration_only.py

@@ -0,0 +1,75 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from agent_framework import AIFunction
+from agent_framework.openai import OpenAIResponsesClient
+
+"""
+Example of how to create a function that only consists of a declaration without an implementation.
+This is useful when you want the agent to use tools that are defined elsewhere or when you want
+to test the agent's ability to reason about tool usage without executing them.
+
+The only difference is that you provide an AIFunction without a function.
+If you need a input_model, you can still provide that as well.
+"""
+
+
+async def main():
+    function_declaration = AIFunction[None, None](
+        name="get_current_time",
+        description="Get the current time in ISO 8601 format.",
+    )
+
+    agent = OpenAIResponsesClient().create_agent(
+        name="DeclarationOnlyToolAgent",
+        instructions="You are a helpful agent that uses tools.",
+        tools=function_declaration,
+    )
+    query = "What is the current time?"
+    print(f"User: {query}")
+    result = await agent.run(query)
+    print(f"Result: {result.to_json(indent=2)}\n")
+
+
+"""
+Expected result:
+User: What is the current time?
+Result: {
+  "type": "agent_run_response",
+  "messages": [
+    {
+      "type": "chat_message",
+      "role": {
+        "type": "role",
+        "value": "assistant"
+      },
+      "contents": [
+        {
+          "type": "function_call",
+          "call_id": "call_0flN9rfGLK8LhORy4uMDiRSC",
+          "name": "get_current_time",
+          "arguments": "{}",
+          "fc_id": "fc_0fd5f269955c589f016904c46584348195b84a8736e61248de"
+        }
+      ],
+      "author_name": "DeclarationOnlyToolAgent",
+      "additional_properties": {}
+    }
+  ],
+  "response_id": "resp_0fd5f269955c589f016904c462d5cc819599d28384ba067edc",
+  "created_at": "2025-10-31T15:14:58.000000Z",
+  "usage_details": {
+    "type": "usage_details",
+    "input_token_count": 63,
+    "output_token_count": 145,
+    "total_token_count": 208,
+    "openai.reasoning_tokens": 128
+  },
+  "additional_properties": {}
+}
+"""
+
+
+if __name__ == "__main__":
+    import asyncio
+
+    asyncio.run(main())

python/samples/getting_started/tools/ai_function_with_max_exceptions.py

@@ -0,0 +1,188 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import Annotated
+
+from agent_framework import FunctionCallContent, FunctionResultContent, ai_function
+from agent_framework.openai import OpenAIResponsesClient
+
+"""
+Some tools are very expensive to run, so you may want to limit the number of times
+it tries to call them and fails. This sample shows a tool that can only raise exceptions a
+limited number of times.
+"""
+
+
+# we trick the AI into calling this function with 0 as denominator to trigger the exception
+@ai_function(max_invocation_exceptions=1)
+def safe_divide(
+    a: Annotated[int, "Numerator"],
+    b: Annotated[int, "Denominator"],
+) -> str:
+    """Divide two numbers can be used with 0 as denominator."""
+    try:
+        result = a / b  # Will raise ZeroDivisionError
+    except ZeroDivisionError as exc:
+        print(f"    Tool failed with error: {exc}")
+        raise
+
+    return f"{a} / {b} = {result}"
+
+
+async def main():
+    # tools = Tools()
+    agent = OpenAIResponsesClient().create_agent(
+        name="ToolAgent",
+        instructions="Use the provided tools.",
+        tools=[safe_divide],
+    )
+    thread = agent.get_new_thread()
+    print("=" * 60)
+    print("Step 1: Call divide(10, 0) - tool raises exception")
+    response = await agent.run("Divide 10 by 0", thread=thread)
+    print(f"Response: {response.text}")
+    print("=" * 60)
+    print("Step 2: Call divide(100, 0) - will refuse to execute due to max_invocation_exceptions")
+    response = await agent.run("Divide 100 by 0", thread=thread)
+    print(f"Response: {response.text}")
+    print("=" * 60)
+    print(f"Number of tool calls attempted: {safe_divide.invocation_count}")
+    print(f"Number of tool calls failed: {safe_divide.invocation_exception_count}")
+    print("Replay the conversation:")
+    assert thread.message_store
+    assert thread.message_store.list_messages
+    for idx, msg in enumerate(await thread.message_store.list_messages()):
+        if msg.text:
+            print(f"{idx + 1}  {msg.author_name or msg.role}: {msg.text} ")
+        for content in msg.contents:
+            if isinstance(content, FunctionCallContent):
+                print(
+                    f"{idx + 1}  {msg.author_name}: calling function: {content.name} with arguments: {content.arguments}"
+                )
+            if isinstance(content, FunctionResultContent):
+                print(f"{idx + 1}  {msg.role}: {content.result if content.result else content.exception}")
+
+
+"""
+Expected Output:
+============================================================
+Step 1: Call divide(10, 0) - tool raises exception
+    Tool failed with error: division by zero
+[2025-10-31 15:39:53 - /Users/edvan/Work/agent-framework/python/packages/core/agent_framework/_tools.py:718 - ERROR]
+Function failed. Error: division by zero
+Response: Division by zero is undefined in standard arithmetic. There is no finite value for 10 ÷ 0.
+
+If you want alternatives:
+- A valid example: 10 ÷ 2 = 5.
+- To handle safely in code, you can check the denominator first (e.g., in Python: if b == 0:
+    handle error else: compute a/b).
+- If you’re curious about limits: as x → 0+, 10/x → +∞; as x → 0−, 10/x → −∞; there is no finite limit.
+
+Would you like me to show a safe division snippet in a specific language, or compute something else?
+============================================================
+Step 2: Call divide(100, 0) - will refuse to execute due to max_invocations
+[2025-10-31 15:40:09 - /Users/edvan/Work/agent-framework/python/packages/core/agent_framework/_tools.py:718 - ERROR]
+Function failed. Error: Function 'safe_divide' has reached its maximum exception limit, you tried to use this
+tool too many times and it kept failing.
+Response: Division by zero is undefined in standard arithmetic, so 100 ÷ 0 has no finite value.
+
+If you’re coding and want safe handling, here are quick patterns in a few languages:
+
+- Python
+  def safe_divide(a, b):
+      if b == 0:
+          return None  # or raise an exception
+      return a / b
+
+  safe_divide(100, 0)  # -> None
+
+- JavaScript
+  function safeDivide(a, b) {
+      if (b === 0) return undefined; // or throw
+      return a / b;
+  }
+
+  safeDivide(100, 0)  // -> undefined
+
+- Java
+  public static Double safeDivide(double a, double b) {
+      if (b == 0.0) throw new ArithmeticException("Divide by zero");
+      return a / b;
+  }
+
+  safeDivide(100, 0)  // -> exception
+
+- C/C++
+  double safeDivide(double a, double b) {
+      if (b == 0.0) return std::numeric_limits<double>::infinity(); // or handle error
+      return a / b;
+  }
+
+Note: In many languages, dividing by zero with floating-point numbers yields Infinity (or -Infinity) or NaN,
+but integer division typically raises an error.
+
+Would you like a snippet in a specific language or to see a math explanation (limits) for what happens as the
+divisor approaches zero?
+============================================================
+Number of tool calls attempted: 1
+Number of tool calls failed: 1
+Replay the conversation:
+1  user: Divide 10 by 0
+2  ToolAgent: calling function: safe_divide with arguments: {"a":10,"b":0}
+3  tool: division by zero
+4  ToolAgent: Division by zero is undefined in standard arithmetic. There is no finite value for 10 ÷ 0.
+
+If you want alternatives:
+- A valid example: 10 ÷ 2 = 5.
+- To handle safely in code, you can check the denominator first (e.g., in Python: if b == 0:
+    handle error else: compute a/b).
+- If you’re curious about limits: as x → 0+, 10/x → +∞; as x → 0−, 10/x → −∞; there is no finite limit.
+
+Would you like me to show a safe division snippet in a specific language, or compute something else?
+5  user: Divide 100 by 0
+6  ToolAgent: calling function: safe_divide with arguments: {"a":100,"b":0}
+7  tool: Function 'safe_divide' has reached its maximum exception limit, you tried to use this tool too many times
+    and it kept failing.
+8  ToolAgent: Division by zero is undefined in standard arithmetic, so 100 ÷ 0 has no finite value.
+
+If you’re coding and want safe handling, here are quick patterns in a few languages:
+
+- Python
+  def safe_divide(a, b):
+      if b == 0:
+          return None  # or raise an exception
+      return a / b
+
+  safe_divide(100, 0)  # -> None
+
+- JavaScript
+  function safeDivide(a, b) {
+      if (b === 0) return undefined; // or throw
+      return a / b;
+  }
+
+  safeDivide(100, 0)  // -> undefined
+
+- Java
+  public static Double safeDivide(double a, double b) {
+      if (b == 0.0) throw new ArithmeticException("Divide by zero");
+      return a / b;
+  }
+
+  safeDivide(100, 0)  // -> exception
+
+- C/C++
+  double safeDivide(double a, double b) {
+      if (b == 0.0) return std::numeric_limits<double>::infinity(); // or handle error
+      return a / b;
+  }
+
+Note: In many languages, dividing by zero with floating-point numbers yields Infinity (or -Infinity) or NaN,
+but integer division typically raises an error.
+
+Would you like a snippet in a specific language or to see a math explanation (limits) for what happens as the
+divisor approaches zero?
+"""
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/tools/ai_function_with_max_invocations.py

@@ -0,0 +1,89 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import Annotated
+
+from agent_framework import FunctionCallContent, FunctionResultContent, ai_function
+from agent_framework.openai import OpenAIResponsesClient
+
+"""
+For tools you can specify if there is a maximum number of invocations allowed.
+This sample shows a tool that can only be invoked once.
+"""
+
+
+@ai_function(max_invocations=1)
+def unicorn_function(times: Annotated[int, "The number of unicorns to return."]) -> str:
+    """This function returns precious unicorns!"""
+    return f"{'🦄' * times}✨"
+
+
+async def main():
+    # tools = Tools()
+    agent = OpenAIResponsesClient().create_agent(
+        name="ToolAgent",
+        instructions="Use the provided tools.",
+        tools=[unicorn_function],
+    )
+    thread = agent.get_new_thread()
+    print("=" * 60)
+    print("Step 1: Call unicorn_function")
+    response = await agent.run("Call 5 unicorns!", thread=thread)
+    print(f"Response: {response.text}")
+    print("=" * 60)
+    print("Step 2: Call unicorn_function again - will refuse to execute due to max_invocations")
+    response = await agent.run("Call 10 unicorns and use the function to do it.", thread=thread)
+    print(f"Response: {response.text}")
+    print("=" * 60)
+    print(f"Number of tool calls attempted: {unicorn_function.invocation_count}")
+    print(f"Number of tool calls failed: {unicorn_function.invocation_exception_count}")
+    print("Replay the conversation:")
+    assert thread.message_store
+    assert thread.message_store.list_messages
+    for idx, msg in enumerate(await thread.message_store.list_messages()):
+        if msg.text:
+            print(f"{idx + 1}  {msg.author_name or msg.role}: {msg.text} ")
+        for content in msg.contents:
+            if isinstance(content, FunctionCallContent):
+                print(
+                    f"{idx + 1}  {msg.author_name}: calling function: {content.name} with arguments: {content.arguments}"
+                )
+            if isinstance(content, FunctionResultContent):
+                print(f"{idx + 1}  {msg.role}: {content.result if content.result else content.exception}")
+
+
+"""
+Expected Output:
+============================================================
+Step 1: Call unicorn_function
+Response: Five unicorns summoned: 🦄🦄🦄🦄🦄✨
+============================================================
+Step 2: Call unicorn_function again - will refuse to execute due to max_invocations
+[2025-10-31 15:54:40 - /Users/edvan/Work/agent-framework/python/packages/core/agent_framework/_tools.py:718 - ERROR]
+Function failed. Error: Function 'unicorn_function' has reached its maximum invocation limit,
+you can no longer use this tool.
+Response: The unicorn function has reached its maximum invocation limit. I can’t call it again right now.
+
+Here are 10 unicorns manually: 🦄 🦄 🦄 🦄 🦄 🦄 🦄 🦄 🦄 🦄
+
+Would you like me to try again later, or generate something else?
+============================================================
+Number of tool calls attempted: 1
+Number of tool calls failed: 0
+Replay the conversation:
+1  user: Call 5 unicorns!
+2  ToolAgent: calling function: unicorn_function with arguments: {"times":5}
+3  tool: 🦄🦄🦄🦄🦄✨
+4  ToolAgent: Five unicorns summoned: 🦄🦄🦄🦄🦄✨
+5  user: Call 10 unicorns and use the function to do it.
+6  ToolAgent: calling function: unicorn_function with arguments: {"times":10}
+7  tool: Function 'unicorn_function' has reached its maximum invocation limit, you can no longer use this tool.
+8  ToolAgent: The unicorn function has reached its maximum invocation limit. I can’t call it again right now.
+
+Here are 10 unicorns manually: 🦄 🦄 🦄 🦄 🦄 🦄 🦄 🦄 🦄 🦄
+
+Would you like me to try again later, or generate something else?
+"""
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/tools/ai_functions_in_class.py

@@ -0,0 +1,100 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import Annotated
+
+from agent_framework import ai_function
+from agent_framework.openai import OpenAIResponsesClient
+
+"""
+This sample demonstrates using ai_function within a class,
+showing how to manage state within the class that affects tool behavior.
+
+And how to use ai_function-decorated methods as tools in an agent in order to adjust the behavior of a tool.
+"""
+
+
+class MyFunctionClass:
+    def __init__(self, safe: bool = False) -> None:
+        """Simple class with two ai_functions: divide and add.
+
+        The safe parameter controls whether divide raises on division by zero or returns `infinity` for divide by zero.
+        """
+        self.safe = safe
+
+    def divide(
+        self,
+        a: Annotated[int, "Numerator"],
+        b: Annotated[int, "Denominator"],
+    ) -> str:
+        """Divide two numbers, safe to use also with 0 as denominator."""
+        result = "∞" if b == 0 and self.safe else a / b
+        return f"{a} / {b} = {result}"
+
+    def add(
+        self,
+        x: Annotated[int, "First number"],
+        y: Annotated[int, "Second number"],
+    ) -> str:
+        return f"{x} + {y} = {x + y}"
+
+
+async def main():
+    # Creating my function class with safe division enabled
+    tools = MyFunctionClass(safe=True)
+    # Applying the ai_function decorator to one of the methods of the class
+    add_function = ai_function(description="Add two numbers.")(tools.add)
+
+    agent = OpenAIResponsesClient().create_agent(
+        name="ToolAgent",
+        instructions="Use the provided tools.",
+    )
+    print("=" * 60)
+    print("Step 1: Call divide(10, 0) - tool returns infinity")
+    query = "Divide 10 by 0"
+    response = await agent.run(
+        query,
+        tools=[add_function, tools.divide],
+    )
+    print(f"Response: {response.text}")
+    print("=" * 60)
+    print("Step 2: Call set safe to False and call again")
+    # Disabling safe mode to allow exceptions
+    tools.safe = False
+    response = await agent.run(query, tools=[add_function, tools.divide])
+    print(f"Response: {response.text}")
+    print("=" * 60)
+
+
+"""
+Expected Output:
+============================================================
+Step 1: Call divide(10, 0) - tool returns infinity
+Response: Division by zero is undefined in standard arithmetic. There is no real number that equals 10 divided by 0.
+
+- If you look at limits: as x → 0+ (denominator approaches 0 from the positive side), 10/x → +∞; as x → 0−, 10/x → −∞.
+- Some calculators may display "infinity" or give an error, but that's not a real number.
+
+If you want a numeric surrogate, you can use a small nonzero denominator, e.g., 10/0.001 = 10000. Would you like to
+see more on limits or handle it with a tiny epsilon?
+============================================================
+Step 2: Call set safe to False and call again
+[2025-10-31 16:17:44 - /Users/edvan/Work/agent-framework/python/packages/core/agent_framework/_tools.py:718 - ERROR]
+Function failed. Error: division by zero
+Response: Division by zero is undefined in standard arithmetic. There is no number y such that 0 × y = 10.
+
+If you’re looking at limits:
+- as x → 0+, 10/x → +∞
+- as x → 0−, 10/x → −∞
+So the limit does not exist.
+
+In programming, dividing by zero usually raises an error or results in special values (e.g., NaN or ∞) depending
+on the language.
+
+If you want, tell me what you’d like to do instead (e.g., compute 10 divided by 2, or handle division by zero safely
+in code), and I can help with examples.
+============================================================
+"""
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/tools/function_invocation_configuration.py

@@ -0,0 +1,58 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import Annotated
+
+from agent_framework.openai import OpenAIResponsesClient
+
+"""
+This sample demonstrates how to configure function invocation settings
+for an client and use a simple ai_function as a tool in an agent.
+
+This behavior is the same for all chat client types.
+"""
+
+
+def add(
+    x: Annotated[int, "First number"],
+    y: Annotated[int, "Second number"],
+) -> str:
+    return f"{x} + {y} = {x + y}"
+
+
+async def main():
+    client = OpenAIResponsesClient()
+    if client.function_invocation_configuration is not None:
+        client.function_invocation_configuration.include_detailed_errors = True
+        client.function_invocation_configuration.max_iterations = 40
+        print(f"Function invocation configured as: \n{client.function_invocation_configuration.to_json(indent=2)}")
+
+    agent = client.create_agent(name="ToolAgent", instructions="Use the provided tools.", tools=add)
+
+    print("=" * 60)
+    print("Call add(239847293, 29834)")
+    query = "Add 239847293 and 29834"
+    response = await agent.run(query)
+    print(f"Response: {response.text}")
+
+
+"""
+Expected Output:
+============================================================
+Function invocation configured as:
+{
+  "type": "function_invocation_configuration",
+  "enabled": true,
+  "max_iterations": 40,
+  "max_consecutive_errors_per_request": 3,
+  "terminate_on_unknown_calls": false,
+  "additional_tools": [],
+  "include_detailed_errors": true
+}
+============================================================
+Call add(239847293, 29834)
+Response: 239,877,127
+"""
+
+if __name__ == "__main__":
+    asyncio.run(main())