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.
| File | Demonstrates |
|---|---|
function_tool_with_explicit_schema.py |
Choosing between Pydantic validation and a trusted, non-sensitive JSON schema declaration. |
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. |
Warning
Caller-supplied JSON schema mappings receive only lightweight top-level runtime checks. Nested constraints and other JSON Schema keywords are not comprehensively enforced, so mappings must not be used as an authorization or security boundary. Use a Pydantic model for sensitive tools or whenever runtime validation matters.
| 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. |
tool_approval_middleware.py |
Session-backed approval coordination, mixed-batch approvals, and "always approve" rules. |
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. |
| 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 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/
(code_act.py for Hyperlight,
monty_code_act.py for
Monty).
| Path | Demonstrates |
|---|---|
local_shell_with_allowlist.py |
Command-text filtering without human approval; not safe for production as shown. |
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). |
Warning
The allow-list shell sample is educational, not a safe production configuration. Its filters can allow embedded shell commands and do not enforce read-only access. Commands run with the application's permissions, without human approval. Use only an isolated, disposable environment without secrets or valuable data. Production use needs separately enforced isolation and restricted permissions; human review can add a check, but does not isolate the shell.
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/, which adds
dynamic tool / capability management.