Class FunctionTool

src/agents/tool.py:381–523

A tool that wraps a function. In most cases, you should use the `function_tool` helpers to create a FunctionTool, as they let you easily wrap a Python function.

@dataclass
class FunctionTool:
    """A tool that wraps a function. In most cases, you should use  the `function_tool` helpers to
    create a FunctionTool, as they let you easily wrap a Python function.
    """

    name: str
    """The name of the tool, as shown to the LLM. Generally the name of the function."""

    description: str
    """A description of the tool, as shown to the LLM."""

    params_json_schema: dict[str, Any]
    """The JSON schema for the tool's parameters."""

    on_invoke_tool: Callable[[ToolContext[Any], str], Awaitable[Any]]
    """A function that invokes the tool with the given context and parameters. The params passed
    are:
    1. The tool run context.
    2. The arguments from the LLM, as a JSON string.

    You must return one of the structured tool output types (e.g. ToolOutputText, ToolOutputImage,
    ToolOutputFileContent) or a string representation of the tool output, or a list of them,
    or something we can call `str()` on.
    In case of errors, you can either raise an Exception (which will cause the run to fail) or
    return a string error message (which will be sent back to the LLM).
    """

    strict_json_schema: bool = True
    """Whether the JSON schema is in strict mode. We **strongly** recommend setting this to True,
    as it increases the likelihood of correct JSON input."""

    is_enabled: bool | Callable[[RunContextWrapper[Any], AgentBase], MaybeAwaitable[bool]] = True
    """Whether the tool is enabled. Either a bool or a Callable that takes the run context and agent
    and returns whether the tool is enabled. You can use this to dynamically enable/disable a tool
    based on your context/state."""

    # Keep guardrail fields before needs_approval to preserve v0.7.0 positional
    # constructor compatibility for public FunctionTool callers.
    # Tool-specific guardrails.
    tool_input_guardrails: list[ToolInputGuardrail[Any]] | None = None
    """Optional list of input guardrails to run before invoking this tool."""

    tool_output_guardrails: list[ToolOutputGuardrail[Any]] | None = None
    """Optional list of output guardrails to run after invoking this tool."""

    needs_approval: (
        bool | Callable[[RunContextWrapper[Any], dict[str, Any], str], Awaitable[bool]]
    ) = False
    """Whether the tool needs approval before execution. If True, the run will be interrupted
    and the tool call will need to be approved using RunState.approve() or rejected using
    RunState.reject() before continuing. Can be a bool (always/never needs approval) or a
    function that takes (run_context, tool_parameters, call_id) and returns whether this
    specific call needs approval."""

    # Keep timeout fields after needs_approval to preserve positional constructor compatibility.
    timeout_seconds: float | None = None
    """Optional timeout (seconds) for each tool invocation."""