Eduard van Valkenburg
49a6e433a3
* 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>
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 |
Defining a tool with an explicit JSON schema. |
function_tool_declaration_only.py |
A declaration-only tool (schema without a local implementation). |
function_tool_with_kwargs.py |
Passing extra keyword arguments into a tool. |
function_tool_from_dict_with_dependency_injection.py |
Dependency injection into a tool defined from a dict. |
function_tool_with_session_injection.py |
Injecting the session into a tool. |
tool_in_class.py |
Using a method on a class as a tool. |
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 |
Requiring human approval before a tool runs. |
function_tool_with_approval_and_sessions.py |
Tool approvals combined with sessions. |
function_invocation_configuration.py |
Configuring function-invocation settings (e.g. max iterations). |
control_total_tool_executions.py |
All the ways to cap how many times tools run. |
function_tool_with_max_invocations.py |
Limiting the number of invocations per tool. |
function_tool_with_max_exceptions.py |
Limiting the number of exceptions a tool may raise. |
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 |
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 singleexecute_codetool, and host tools are exposed inside the sandbox as typed Python functions rather than as model tool-schemas. Host tools there are invoked without aFunctionInvocationContext, soctx.add_tools()is not available; the helpers fail fast with a clearRuntimeErrorinstead of silently doing nothing. To change a CodeAct agent's tool set, use the provider's ownadd_tools/remove_tool/clear_toolsmethods (applied between runs). The recommended provider-driven path for Monty and Hyperlight is shown in../context_providers/code_act/(code_act.pyfor Hyperlight,monty_code_act.pyfor Monty).
Local shell & code interpreters
| Path | Demonstrates |
|---|---|
local_shell_with_allowlist.py |
LocalShellTool restricted by a strict command allow-list. |
local_shell_with_environment_provider.py |
LocalShellTool wired with a ShellEnvironmentProvider. |
local_code_interpreter/ |
Hyperlight-backed sandboxed code interpreter (standalone tool โ extra pattern). |
monty_code_interpreter/ |
Monty-backed sandboxed code interpreter (standalone tool โ extra pattern). |
Tip
The
local_code_interpreter/andmonty_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/, which adds dynamic tool / capability management.