tool#

Build typed tools from annotations and docstrings. See the guide.

zett_agent.tools.base.tool(function: Callable[[...], Any], *, name: str | None = None, snippet: str | None = None, guidelines: str | Sequence[str] | None = None, execution_mode: ToolExecutionMode = ToolExecutionMode.PARALLEL, deferred: bool = False, local_tool_search: bool = False) → AgentTool[源代码]#
zett_agent.tools.base.tool(function: None = None, *, name: str | None = None, snippet: str | None = None, guidelines: str | Sequence[str] | None = None, execution_mode: ToolExecutionMode = ToolExecutionMode.PARALLEL, deferred: bool = False, local_tool_search: bool = False) → _ToolDecorator

Turn a typed function and its structured docstring into an AgentTool.

参数:

  • function (Callable[[...], Any] | None) -- Typed function for bare @tool use; omitted for @tool(...).

  • name (str | None) -- Optional public name overriding the Python function name.

  • snippet (str | None) -- Optional usage snippet overriding the docstring section.

  • guidelines (str | Sequence[str] | None) -- Optional model guidance overriding docstring Guidelines.

  • execution_mode (ToolExecutionMode) -- Whether the local handler must run serially or may run concurrently with other parallel handlers. The default is parallel; use SERIAL for handlers that require exclusive ordered execution.

  • deferred (bool) -- Whether Responses API providers may load this tool's schema through tool search instead of injecting it up front. Other provider protocols ignore this flag. Tool search requires a compatible model such as gpt-5.4 or later.

  • local_tool_search (bool) -- Whether this tool answers client-side tool search. The Responses adapter declares tool_search with execution: "client" and hands every search query to this handler; it must return list[FunctionToolParam] (OpenAI's Responses function definition), which becomes the tool_search_output the model loads from. The model never calls this tool as a function, and other provider protocols reject the flag.

返回:

An AgentTool for direct decoration, or a decorator when configured first.

抛出:

ValueError -- If annotations, guidance, or documented parameter names are invalid.

返回类型:

AgentTool | _ToolDecorator

备注

A normal exception raised by the decorated handler is caught by the Agent instead of ending the run. The Agent creates an unsuccessful ToolMessage whose content is str(exception); that string is what the next model request sees. The original exception object remains available separately on the TOOL_FAILED event and after-tool hooks. Cancellation and other BaseException subclasses are not converted.

示例

Register a typed function:

@tool
def read_file(path: str) -> str:
    """Read a text file.

    Args:
        path: File path relative to the workspace.

    Snippet:
        read_file(path="README.md")

    Guidelines:
        - Read a file before changing it.
    """
    return path
当前页面