内置工具参考

ToolBox().with_defaults() 注册 8 组工具（不传参数 = 全部组），with_subagent_provider() 再追加两个子智能体工具。下表列出全部内置工具的注册名、作用与参数（含默认值）。

浏览器工具需要内核

browser 组依赖 Playwright，安装后执行 playwright install（镜像里为 playwright install chromium --with-deps）。运行时惰性启动：首次调用才拉起 worker 线程与 Chromium，按智能体 identifier 隔离浏览器上下文，默认视口 1280×720。

system

工具	作用	参数
system_info	操作系统与内核、主机名、架构、处理器、时区与 UTC 偏移、locale，外加取自 LC_ALL/LANG 的 locale_env；不含其它环境变量	无
datetime	当前系统时间与时区（ISO 格式）	无

framework

工具	作用	参数
ask_preference	向用户征询选项（跳过自动确认，一定问人）	question: str、choices: list[str]、allow_extra: bool = False、default_choice: str \| None = None、title: str = "User Preference Query"
extract_compacted_tool_result	取回被压缩掉的工具结果原文	toolcall_id: str

fs

工具	作用	参数
temp_dir	取智能体专属临时目录（优先于系统临时目录）	无
list_dir	列目录	path: str、details: bool = False
file_info	元信息（大小、行数、是否文本、修改时间）；为统计行数会通读文件	path: str
read_file	按行范围读文本	path: str、line_offset: int = 0、line_limit: int \| None = None、include_line_numbers: bool = False
write_file	创建/覆盖写入（覆盖需确认）	path: str、content: str = ""
mkdir	建目录	path: str
move	移动/重命名（shutil.move 语义）	src: str、dst: str
copy	复制（copy2 / copytree 语义，覆盖需确认）	src: str、dst: str
delete	删除文件或目录	path: str
request_image	请求一张图片进入上下文（需要 vision 能力）；可先按相对区域裁剪，长边超过 1000px 自动缩放，URL 图片先下载再处理	src: str、crop: tuple[float, float, float, float] \| None = None（(x, y, w, h)，均为 [0, 1] 相对比例）
glob	按名称模式递归查找，识别 .gitignore	path: str = "."、name_pattern: str = "*"、file_type: "file"\|"directory"\|"any" = "any"、skip_ignored: bool = True
grep	按内容搜索，跳过二进制，识别 .gitignore，最多 100 条命中	path: str、pattern: str、file_pattern: str = "*"、include_content: bool = True、regex: bool = True、skip_ignored: bool = True

patch

工具	作用	参数
apply_patch	应用统一差异；先 dry-run，失败时允许有限 fuzz 重试，并给出定位建议（-p 层级错、已应用、危险文件名等）	patch: str、reverse: bool = False、strip: int = 1、directory: str = "."

不支持纯 git 元数据差异（重命名、模式位、二进制补丁）。

cmd

工具	作用	参数
bash	通过 bash（缺失时回落 /bin/sh）执行命令，阻塞、可取消、stdout 与 stderr 各自按 max_output_size 截断（保留首尾）	command: str、timeout: float = 300、cd: str \| None = None、envs: dict[str, str] \| None = None、max_output_size: int \| None = 16000

超时以 RuntimeError 报出并终止整个进程组（先 SIGTERM，5 秒后 SIGKILL）；cd 目标必须在工作区内。Windows 上不注册。

search

工具	作用	参数
web_search	由子智能体驱动浏览器完成检索，返回结构化结果；未能真正读取页面时结果会带 WARNING	query: str、max_results: int = 5（上限 20）

browser

工具	作用	参数
browser_page	管理常驻页面	action: "list"\|"new"\|"navigate"\|"reload"\|"select"\|"close" = "list"、page_id: str \| None = None、url: str \| None = None、wait_until = "domcontentloaded"（仅 navigate / reload 生效）、timeout_ms: int = 15000
browser_resize	设置视口（CSS 像素）	width: int、height: int、page_id: str \| None = None
browser_snapshot	以 accessibility / html / markdown 读取页面，支持分段	page_id: str \| None = None、format: "accessibility"\|"html"\|"markdown" = "accessibility"、selector: str \| None = None、start_char: int = 0、max_chars: int = 50000
browser_interact	用 Playwright 选择器交互	action: "click"\|"fill"\|"press"\|"select"\|"wait"、selector: str \| None = None、value: str \| list[str] \| None = None、state = "visible"、page_id: str \| None = None、timeout_ms: int = 15000
browser_evaluate	在页面里执行 JS 并返回 JSON 兼容数据	expression: str、argument: JsonType = None、selector: str \| None = None、page_id: str \| None = None
browser_logs	读取捕获到的 console / 报错 / 请求事件（环形缓冲 500 条）	page_id: str \| None = None、kind = "all"、clear: bool = False
browser_screenshot	截图（需要 vision 能力），图片延后到工具结果之后的一条用户消息里	page_id: str \| None = None、selector: str \| None = None、clip: {x, y, width, height} \| None = None（四键必填）、full_page: bool = False、save_to: str \| None = None、timeout_ms: int = 15000

selector、clip、full_page 三者互斥。

diagnostic

工具	作用	参数
check_syntax	语法解析校验（不执行）	path: str、language: "python"\|"json"\|"bash"
diff_files	两文件差异，相同则返回空串	path_a: str、path_b: str
check_lint	mypy 检查；未安装时先征求同意执行 pip install mypy，装好即返回、本次不跑检查，需再调一次	path: str、language: "python" = "python"

子智能体

由 ToolBox.with_subagent_provider() 提供，细节见 子智能体与取消。

工具	作用	参数
agent_run	生成一个空白上下文的子智能体执行自包含任务	task: str、name: str \| None = None
agent_run_parallel	并发执行多个任务，结果顺序与输入一致	tasks: list[str]、names: list[str] \| None = None