Python: progressive tool exposure via FunctionInvocationContext (#6233)

* Python: progressive tool exposure via FunctionInvocationContext

Add first-class progressive tool exposure to the Python core function-calling
loop. Tools can now add or remove real FunctionTool schemas at runtime via the
injected FunctionInvocationContext, taking effect on the next iteration of the
loop.

- FunctionInvocationContext gains a live `tools` list plus experimental
  `add_tools()` / `remove_tools()` helpers (feature: PROGRESSIVE_TOOLS).
- The function-calling loop establishes a run-local, normalized tools list and
  threads it into the context at both invocation paths so mutations propagate.
- Add a sample (dynamic_tool_exposure.py) and a tools samples README, including
  a note that CodeAct providers (Monty/Hyperlight) use their own provider-level
  tool management instead.

Supersedes #3877.

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

* Validate non-negative input in dynamic_tool_exposure sample tools

Address review feedback: factorial and fibonacci now return an error
message for negative n instead of producing incorrect results.

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

* Make add_tools atomic and surface swallowed function errors

Address review feedback on progressive tool exposure:

- add_tools now validates the full batch against a throwaway copy before
  committing, so a duplicate-name clash partway through a sequence leaves
  the live tool list unchanged (all-or-nothing).
- _auto_invoke_function now logs a warning (with traceback) when a tool
  raises, so contract errors such as a duplicate-name ValueError from
  add_tools are debuggable without enabling include_detailed_errors.

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

* Avoid retaining tracebacks when logging swallowed function errors

Logging with exc_info=exc fed the exception traceback to the logging
machinery, whose frame references created reference cycles collected
lazily by the cyclic GC. On Windows that could drop a hyperlight
WasmSandbox on a non-owning thread ("unsendable, dropped on another
thread"), crashing the xdist worker. Log a pre-formatted message with
the exception repr instead, so no traceback object is retained.

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

* added missing decorator

---------

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

python/samples/02-agents/tools/README.md

@@ -0,0 +1,75 @@
+# Tools
+
+Samples that show how to define, configure, and control function tools for an
+agent — from basic declarations to approvals, invocation limits, session
+injection, and dynamic (progressive) tool exposure.
+
+## Function tools
+
+| File | Demonstrates |
+|------|--------------|
+| [`function_tool_with_explicit_schema.py`](function_tool_with_explicit_schema.py) | Defining a tool with an explicit JSON schema. |
+| [`function_tool_declaration_only.py`](function_tool_declaration_only.py) | A declaration-only tool (schema without a local implementation). |
+| [`function_tool_with_kwargs.py`](function_tool_with_kwargs.py) | Passing extra keyword arguments into a tool. |
+| [`function_tool_from_dict_with_dependency_injection.py`](function_tool_from_dict_with_dependency_injection.py) | Dependency injection into a tool defined from a dict. |
+| [`function_tool_with_session_injection.py`](function_tool_with_session_injection.py) | Injecting the session into a tool. |
+| [`tool_in_class.py`](tool_in_class.py) | Using a method on a class as a tool. |
+| [`agent_as_tool_with_session_propagation.py`](agent_as_tool_with_session_propagation.py) | Exposing an agent as a tool with session propagation. |
+
+## Approvals & invocation control
+
+| File | Demonstrates |
+|------|--------------|
+| [`function_tool_with_approval.py`](function_tool_with_approval.py) | Requiring human approval before a tool runs. |
+| [`function_tool_with_approval_and_sessions.py`](function_tool_with_approval_and_sessions.py) | Tool approvals combined with sessions. |
+| [`function_invocation_configuration.py`](function_invocation_configuration.py) | Configuring function-invocation settings (e.g. max iterations). |
+| [`control_total_tool_executions.py`](control_total_tool_executions.py) | All the ways to cap how many times tools run. |
+| [`function_tool_with_max_invocations.py`](function_tool_with_max_invocations.py) | Limiting the number of invocations per tool. |
+| [`function_tool_with_max_exceptions.py`](function_tool_with_max_exceptions.py) | Limiting the number of exceptions a tool may raise. |
+| [`function_tool_recover_from_failures.py`](function_tool_recover_from_failures.py) | Returning errors so the agent can recover from tool failures. |
+
+## Progressive tool exposure (dynamic loading)
+
+| File | Demonstrates |
+|------|--------------|
+| [`dynamic_tool_exposure.py`](dynamic_tool_exposure.py) | A "loader" tool that adds more tools at runtime via `FunctionInvocationContext`. |
+
+Frontloading a model with hundreds of tools hurts tool-selection accuracy,
+bloats context, and raises cost. Instead, start with a small set of loader
+tools and let the model pull in more on demand. Inside a tool, the injected
+`ctx: FunctionInvocationContext` exposes a live `ctx.tools` list plus
+`ctx.add_tools(...)` / `ctx.remove_tools(...)` helpers. Tools added or removed
+take effect on the **next iteration** of the function-calling loop.
+
+> [!NOTE]
+> Progressive tool exposure applies to the standard function-calling loop. It
+> does **not** apply to CodeAct providers (`agent-framework-monty`,
+> `agent-framework-hyperlight`). In CodeAct the model only sees a single
+> `execute_code` tool, and host tools are exposed *inside the sandbox* as typed
+> Python functions rather than as model tool-schemas. Host tools there are
+> invoked without a `FunctionInvocationContext`, so `ctx.add_tools()` is not
+> available; the helpers fail fast with a clear `RuntimeError` instead of
+> silently doing nothing. To change a CodeAct agent's tool set, use the
+> provider's own `add_tools` / `remove_tool` / `clear_tools` methods (applied
+> between runs). The recommended provider-driven path for Monty and Hyperlight
+> is shown in [`../context_providers/code_act/`](../context_providers/code_act/)
+> ([`code_act.py`](../context_providers/code_act/code_act.py) for Hyperlight,
+> [`monty_code_act.py`](../context_providers/code_act/monty_code_act.py) for
+> Monty).
+
+## Local shell & code interpreters
+
+| Path | Demonstrates |
+|------|--------------|
+| [`local_shell_with_allowlist.py`](local_shell_with_allowlist.py) | `LocalShellTool` restricted by a strict command allow-list. |
+| [`local_shell_with_environment_provider.py`](local_shell_with_environment_provider.py) | `LocalShellTool` wired with a `ShellEnvironmentProvider`. |
+| [`local_code_interpreter/`](local_code_interpreter/) | Hyperlight-backed sandboxed code interpreter (standalone tool — *extra* pattern). |
+| [`monty_code_interpreter/`](monty_code_interpreter/) | Monty-backed sandboxed code interpreter (standalone tool — *extra* pattern). |
+
+> [!TIP]
+> The `local_code_interpreter/` and `monty_code_interpreter/` samples show the
+> standalone-tool wiring and are provided as *extra* reference. For most
+> Monty/Hyperlight use cases the **recommended** path is the provider-driven
+> CodeAct setup in
+> [`../context_providers/code_act/`](../context_providers/code_act/), which adds
+> dynamic tool / capability management.

python/samples/02-agents/tools/dynamic_tool_exposure.py

@@ -0,0 +1,79 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import Annotated
+
+from agent_framework import Agent, FunctionInvocationContext, tool
+from agent_framework.openai import OpenAIChatClient
+from dotenv import load_dotenv
+from pydantic import Field
+
+# Load environment variables from .env file
+load_dotenv()
+
+"""
+Dynamic Tool Exposure (Progressive Tool Loading) Example
+
+This example demonstrates "progressive tool exposure": a tool that adds more tools to
+the agent at runtime, in the same run, via ``FunctionInvocationContext``.
+
+Frontloading a model with hundreds of tools hurts tool-selection accuracy, bloats
+context, and raises cost. Instead, you can start with a small set of "loader" tools and
+let the model pull in additional tools on demand. Tools added with ``ctx.add_tools(...)``
+(or removed with ``ctx.remove_tools(...)``) become available to the model on the next
+iteration of the function-calling loop.
+"""
+
+
+# These math tools are not registered on the agent up front. They are added on demand by
+# the ``load_math_tools`` tool below, and only then become callable by the model.
+@tool(approval_mode="never_require")
+def factorial(n: Annotated[int, Field(description="A non-negative integer.")]) -> str:
+    """Compute the factorial of n."""
+    if n < 0:
+        return "Error: n must be a non-negative integer."
+    result = 1
+    for value in range(2, n + 1):
+        result *= value
+    return f"{n}! = {result}"
+
+
+@tool(approval_mode="never_require")
+def fibonacci(n: Annotated[int, Field(description="The 0-based index in the Fibonacci sequence.")]) -> str:
+    """Compute the n-th Fibonacci number."""
+    if n < 0:
+        return "Error: n must be a non-negative integer."
+    a, b = 0, 1
+    for _ in range(n):
+        a, b = b, a + b
+    return f"fib({n}) = {a}"
+
+
+# The only tool the agent starts with. When called, it exposes the math tools above so the
+# model can use them on the next turn. Note the ``ctx`` parameter is injected by the
+# framework and is not visible to the model.
+@tool(approval_mode="never_require")
+def load_math_tools(ctx: FunctionInvocationContext) -> str:
+    """Load additional math tools (factorial, fibonacci) so they can be used."""
+    ctx.add_tools([factorial, fibonacci])
+    return "Loaded math tools: factorial, fibonacci. You can now call them."
+
+
+async def main() -> None:
+    agent = Agent(
+        client=OpenAIChatClient(),
+        name="MathAgent",
+        instructions=(
+            "You are a math assistant. If you need math capabilities that are not yet "
+            "available, call load_math_tools first, then use the newly available tools."
+        ),
+        tools=[load_math_tools],
+    )
+
+    # The agent starts with only ``load_math_tools``. To answer the question it must first
+    # load the math tools, then call ``factorial`` on the next iteration.
+    print(f"Agent: {await agent.run('What is 5 factorial?')}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())