AgentTool

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

class zett_agent.tools.base.AgentTool(name, description, parameters, handler, guidelines, snippet='', execution_mode=ToolExecutionMode.PARALLEL, deferred=False, local_tool_search=False)

A tool is a name, an input schema, and an async callable.

参数:

• name (str)

• description (str)

• parameters (dict[str, Any])

• handler (Callable[[...], Awaitable[ToolResult]])

• guidelines (tuple[str, ...])

• snippet (str)

• execution_mode (ToolExecutionMode)

• deferred (bool)

• local_tool_search (bool)

name: str

Unique name exposed to the model and used for dispatch.

description: str

Natural-language purpose used by the model to select this tool.

parameters: dict[str, Any]

JSON Schema describing this tool's keyword arguments.

handler: Callable[[...], Awaitable[ToolResult]]

Async handler that validates arguments and performs the local operation.

guidelines: tuple[str, ...]

Model-facing rules rendered beside this tool in prompt guidance. Tools that share one rule through another channel, such as a server-level system message, may leave this empty so the rule is not repeated per tool.

snippet: str

Optional invocation examples rendered into prompt guidance.

execution_mode: ToolExecutionMode

Whether this local handler runs serially or may run in parallel.

deferred: bool

Whether Responses API providers may defer loading this tool's schema through tool search. Other provider protocols ignore this flag.

local_tool_search: bool

Whether this tool answers client-side tool search for one request.

A search tool is internal: the model never calls it directly. The Responses adapter declares tool_search with execution: "client" and routes every search request to this handler, whose result decides which tools the model may load. Other provider protocols reject it.

async __call__(arguments)

Execute with a mapping of model-provided keyword arguments.

参数:

arguments (Mapping[str, Any]) -- Input object validated by the decorated function's schema.

返回:

The function's typed result before JSON serialization.

返回类型:

ToolResult

示例

Invoke a decorated tool from Python:

result = await read_file({"path": "README.md"})

备注

Decorated synchronous functions run in a worker thread; async functions are awaited directly. A manually supplied handler owns its validation policy.

serialize_result(value)

Convert Pydantic models, dataclasses, and plain values into JSON.

Strings pass through unchanged so plain-text tool results reach the model without JSON quoting.

参数:

value (ToolResult)

返回类型:

str

sync(*, runtime=None)

Return a context-managed synchronous view; optionally share a runtime.

Omitting runtime creates a new background thread for this view. Passing an existing runtime reuses its loop and leaves its shutdown to the caller. This API is for service entry points, not Extension lifecycle hooks.

示例

Use a model or tool from a plain function:

with read_file.sync() as read:
    result = read({"path": "README.md"})

参数:

runtime (SyncRuntime | None)

返回类型:

SyncObject[Self]