工具¶

大多数项目通过 runtime.tools.tool 注册普通 Python 函数。

@runtime.tools.tool(
    name="add",
    description="计算两个整数的和。",
)
def add(a: int, b: int) -> int:
    return a + b

接口	用途
`ToolManager`	注册、查询和执行工具
`ToolRegistry`	保存工具定义
`Tool`	自定义工具基类
`CallableTool`	把 Python 函数包装成工具
`PathAllowlist`	为内置路径工具增加读写根目录
`MCPServerStatus`	查看 MCP 连接和工具状态

PathAllowlist 不是操作系统沙箱。自定义 Python 工具和 MCP 工具需要自行检查访问权限。

公开接口¶

Tool registration primitives.

CallableTool `dataclass` ¶

Bases: Tool

A callable object exposed as an LLM-callable tool.

execute `async` ¶

execute(**kwargs: Any) -> Any

Execute the wrapped function, supporting sync and async functions.

MCPServerStatus `dataclass` ¶

Runtime status for one configured MCP server.

PathAllowlist `dataclass` ¶

Extra filesystem roots available to path-aware built-in tools.

This is not an OS sandbox. It does not automatically restrict arbitrary Python tools, MCP servers, or filesystem access performed by subprocesses.

from_roots `classmethod` ¶

from_roots(*, extra_read_roots: Sequence[str | Path] = (), extra_write_roots: Sequence[str | Path] = ()) -> PathAllowlist

Build an allowlist from normalized, deduplicated filesystem roots.

Tool `dataclass` ¶

Bases: ABC

Base class for LLM-callable tools.

Tools execute independently by default. Set parallel_safe=True only when the handler can safely overlap with other parallel-safe tool calls.

cast_arguments ¶

cast_arguments(arguments: dict[str, Any]) -> dict[str, Any]

Apply safe schema-driven casts before validation.

validate_arguments ¶

validate_arguments(arguments: dict[str, Any]) -> None

Validate arguments against the tool JSON Schema.

prepare_arguments ¶

prepare_arguments(arguments: dict[str, Any]) -> dict[str, Any]

Cast and validate arguments before tool execution.

to_openai_tool_schema ¶

to_openai_tool_schema() -> dict[str, Any]

Return the OpenAI-compatible tool schema.

execute `abstractmethod` `async` ¶

execute(**kwargs: Any) -> Any

Execute the tool.

ToolManager ¶

Facade that coordinates tool registration, discovery, MCP, and execution.

tool `property` ¶

tool: Callable[..., Any]

Return the registry decorator for local Python function tools.

register ¶

register(tool: Tool) -> Tool

Register an already constructed Tool object.

register_builtin_tools ¶

register_builtin_tools() -> list[str]

Register built-in local tools using manager-owned config and state.

connect_mcp `async` ¶

connect_mcp() -> list[str]

Connect configured MCP servers and register their enabled tools.

set_mcp_server ¶

set_mcp_server(server: MCPServerConfig) -> None

Add or replace one MCP server configuration without connecting it.

remove_mcp_server `async` ¶

remove_mcp_server(server_name: str) -> None

Close and forget one MCP server configuration.

get_mcp_server_config ¶

get_mcp_server_config(server_name: str) -> MCPServerConfig | None

Return one configured MCP server by name.

list_mcp_server_configs ¶

list_mcp_server_configs() -> list[MCPServerConfig]

Return all configured MCP servers.

get_mcp_server_status ¶

get_mcp_server_status(server_name: str) -> MCPServerStatus | None

Return one MCP server status by name.

list_mcp_server_statuses ¶

list_mcp_server_statuses() -> list[MCPServerStatus]

Return runtime status for all configured MCP servers.

connect_mcp_server `async` ¶

connect_mcp_server(server: MCPServerConfig | str) -> list[str]

Connect one MCP server and register its enabled tools.

reload_mcp `async` ¶

reload_mcp() -> list[str]

Reconnect configured MCP servers and rebuild their registered tools.

reload_mcp_server `async` ¶

reload_mcp_server(server_name: str) -> list[str]

Reconnect one MCP server and rebuild its registered tools.

sync_mcp_servers `async` ¶

sync_mcp_servers(servers: Sequence[MCPServerConfig]) -> list[str]

Make configured MCP servers match servers.

If the configuration is unchanged, connected servers are left alone. If the configuration changed, existing MCP connections are closed, removed server configs are forgotten, new configs are stored, and the current server set is connected.

get_tool ¶

get_tool(name: str) -> Tool | None

Return one registered Tool object by name.

get_tools ¶

get_tools(tool_names: list[str]) -> list[Tool]

Return registered Tool objects filtered by name.

list_tools ¶

list_tools() -> list[Tool]

Return all registered Tool objects.

get_openai_tool_definitions ¶

get_openai_tool_definitions(tool_names: list[str] | None = None) -> list[dict[str, Any]]

Return OpenAI-compatible tool definitions for a model request.

tool_names=None returns all tools, [] returns none, and a non-empty list returns only the named tools in the given order.

execute_call `async` ¶

execute_call(call: ToolCall, *, tool_names: list[str] | None = None, workspace: Path | str | None = None, path_allowlist: PathAllowlist = PathAllowlist(), emitter: EventEmitter | None = None) -> ToolResult

Execute one tool call with a run-scoped built-in path allowlist.

Custom Python and MCP tools are responsible for enforcing their own filesystem access rules.

execute_many `async` ¶

execute_many(calls: list[ToolCall], *, tool_names: list[str] | None = None, workspace: Path | str | None = None, path_allowlist: PathAllowlist = PathAllowlist(), emitter: EventEmitter | None = None) -> list[ToolResult]

Execute tool calls with one run-scoped built-in path allowlist.

Custom Python and MCP tools are responsible for enforcing their own filesystem access rules.

close_mcp_server `async` ¶

close_mcp_server(server_name: str) -> None

Close one MCP server connection and unregister its tools.

close_mcp `async` ¶

close_mcp() -> None

Close all MCP server connections and unregister their tools.

close `async` ¶

close() -> None

Release all resources owned by this manager.

ToolRegistry ¶

Registry used by the agent loop to expose and execute tools.

unregister ¶

unregister(name: str) -> None

Remove a registered tool by name if it exists.

prepare_call ¶

prepare_call(name: str, arguments: dict[str, Any]) -> PreparedToolCall

Resolve a tool call and prepare its arguments for execution.

tool ¶

tool(fn_or_name: Callable[..., Any] | str | None = None, *, name: str | None = None, description: str | None = None, parameters: dict[str, Any] | None = None, parallel_safe: bool = False) -> Callable[[Callable[..., Any]], Callable[..., Any]] | Callable[..., Any]

Register a function as a tool.

get_tools ¶

get_tools(tool_names: list[str]) -> list[Tool]

Return registered tools filtered by name.

list_tools ¶

list_tools() -> list[Tool]

Return all registered tools.

get_openai_tool_definitions ¶

get_openai_tool_definitions(tool_names: list[str] | None = None) -> list[dict[str, Any]]

Return OpenAI-compatible tool definitions for the model request.

tool_names=None returns all tools, [] returns none, and a non-empty list returns only the named tools in the given order.

工具¶

公开接口¶

CallableTool dataclass ¶

execute async ¶

MCPServerStatus dataclass ¶

PathAllowlist dataclass ¶

from_roots classmethod ¶

Tool dataclass ¶

cast_arguments ¶

validate_arguments ¶

prepare_arguments ¶

to_openai_tool_schema ¶

execute abstractmethod async ¶

ToolManager ¶

tool property ¶

register ¶

register_builtin_tools ¶

connect_mcp async ¶

set_mcp_server ¶

remove_mcp_server async ¶

get_mcp_server_config ¶

list_mcp_server_configs ¶

get_mcp_server_status ¶

list_mcp_server_statuses ¶

connect_mcp_server async ¶

reload_mcp async ¶

reload_mcp_server async ¶

sync_mcp_servers async ¶

get_tool ¶

get_tools ¶

list_tools ¶

get_openai_tool_definitions ¶

execute_call async ¶

execute_many async ¶

close_mcp_server async ¶

close_mcp async ¶

close async ¶

ToolRegistry ¶

unregister ¶

prepare_call ¶

tool ¶

get_tools ¶

list_tools ¶

get_openai_tool_definitions ¶

CallableTool `dataclass` ¶

execute `async` ¶

MCPServerStatus `dataclass` ¶

PathAllowlist `dataclass` ¶

from_roots `classmethod` ¶

Tool `dataclass` ¶

execute `abstractmethod` `async` ¶

tool `property` ¶

connect_mcp `async` ¶

remove_mcp_server `async` ¶

connect_mcp_server `async` ¶

reload_mcp `async` ¶

reload_mcp_server `async` ¶

sync_mcp_servers `async` ¶

execute_call `async` ¶

execute_many `async` ¶

close_mcp_server `async` ¶

close_mcp `async` ¶

close `async` ¶