新增内置工具的判据(开发者选读)¶
阅读提示:本文档面向参与 Agentica 框架开发的贡献者,说明向
DeepAgent/ CLI 新增默认内置工具的工程判据与同步清单。如果只是在自己的项目中编写自定义工具,请看 工具与自定义工具。
Tools 讲的是怎么写一个工具。这篇讲该不该把它做成内置——
即默认装进 DeepAgent / CLI、每个用户每一轮都带着它的那种工具。
这不是打分表。agentica 不按「这个能力有多基础」投票,因为那种判据不可证伪: 档位的边界、词条的取舍,组合起来没有穷尽,而每一次判错都是静默的。 下面每一条判据都能在装配期用一个具体事实回答是或否。
先回答:它是不是产品入口专属¶
Agent 会被嵌入 gateway,而 gateway 一个进程服务多个 session。
凡是「要改进程级状态」或「要有人在这个键盘前」的能力,都不能只假设一个
session;但也不等于各端可以各自拼工具表。现在产品层能力由
agentica.tools.product.build_product_tools() 一处装配,各端只传 surface 专属回调。
| 判据 | 回答 |
|---|---|
| 能力依赖进程 cwd 或当前用户? | 通过每次调用传 work_dir / path / owner,不把它写进工具本身 |
| 能力需要人类交互出口? | 由该 surface 的回调提供;没有出口时显式不挂 ask_user_question |
| 能力要改安装级配置或 cron? | 通过产品层工具暴露,不把 agentica.cli 当库反向 import 进 gateway |
tests/gateway/test_surface_parity.py 对 CLI 与 gateway 的稳定前缀和工具 schema 做字节级比对;新增产品工具时要让两端同时拿到同一份 schema。
有没有一个装配期就能查的前提¶
内置工具的前提必须是装配时可判定的事实,不是运行时的猜测。 没有前提就不挂——不是挂上去再在调用时报错。
# agentica/agent/base.py:737 —— 记忆工具要有 workspace 才有意义
if self.enable_long_term_memory and self.workspace is not None:
...注册 BuiltinMemoryTool
# agentica/tools/builtin/execute_tool.py:431 —— 没有 registry 就没有后台进程可等
if self._background_process_registry is not None:
...注册 wait
ask_user_question 是这条的极端形式:create_agent() 把
include_ask_user_question 做成 keyword-only 且没有默认值
(agentica/cli/runtime.py:918)。
给它一个默认值就等于替调用方猜「现在有没有人在终端前等着回答」,而这件事只有
调用方知道。--query 一次性运行显式传 False(agentica/cli/main.py:280):
没有 TUI,工具会掉到一个 input() 上去问一个不存在的终端。
必填让这个问题在读代码时就必须被回答,而不是在半夜的 cron 里挂住。
不要用「运行时把它藏起来」来抵消代价¶
一个常见的辩护是「工具很多也没关系,不相关的那轮从 schema 里摘掉就行」。 agentica 明确不走这条路:
# agentica/agent/permissions.py:78
def read_only_whitelist(mode: str) -> Optional[List[str]]:
"""Query-level tool whitelist for `mode`. Always None: every tier exposes all tools."""
原因是 prompt cache。工具定义在系统消息里,而 prompt cache 命中的条件是 前缀逐字节相同;系统消息在之后每一个 breakpoint 的前缀里。 按轮增删工具 = 每轮换一个前缀 = 把整段对话历史重新计价。 省下来的那点 schema token,换来的是全量重算。
所以内置工具的代价是长期且全局的,不能靠「需要时才出现」摊薄。 这也意味着:上面第二条的条件挂载是装配期一次性的,不是每轮过滤。 两者形状相似, 成本完全不同。
能不能由已有工具加一个参数完成¶
新工具名是给每个模型的每一轮都加一行 schema;新参数只对用到它的那次调用收费。
analyze_image 是这条的正面例子:底模能看图就把像素直接给它、配了
vision_model 就交给它、都没有才退到本地 OCR——三条路一个工具名。
OCR 没有单独暴露成 tool,因为「走哪条路」是这套安装的能力问题,
不该让模型替我们推理它。
反过来,execute 的 background=True 也不是独立的 run_in_background 工具。
但注意它连带的约束:没有 BackgroundProcessRegistry 时,
那个参数根本不在 schema 里——agentica/tools/builtin/execute_tool.py:445
把 background 从
parameters["properties"] 里主动 pop 掉,同时 wait 不注册。
实测两种模式的参数面确实不同:交互 CLI 是
["background", "command", "parallel_safe", "timeout"],
--query 是 ["command", "parallel_safe", "timeout"]。
参数所承诺的能力必须真的存在,否则模型会调一个注定拿不回结果的后台命令。 这也说明:盘点两种形态的差异时只比工具名是不够的,同一个工具的参数面也会变。
它的 docstring 是 prompt,不是开发文档¶
内置工具的 docstring 进每一轮 context,并且同一份文本发给所有档位的模型, 所以它的成本不只是 token:写得含糊,弱模型就照着含糊去调。
细则见 CLAUDE.md 的「Tool Docstring Hygiene」。一条实测出来的反例:
不要维护二进制黑名单("not cat"、"MUST avoid find")——那把强模型推向了更差的绕路。
落地清单¶
决定要内置之后,以下四处必须同步(漏一处都是静默失效):
- 元数据四处同步:
is_read_only/is_destructive/concurrency_safe要在Function字段、@tool装饰器参数、Tool.register()参数、Function.from_callable()提取处都在——细则见CLAUDE.md「Tool Metadata Sync」。 仅执行器用的旋钮(max_result_size_chars/manages_own_timeout/parallel_arg)是例外,只挂在Function上、注册后赋值。 - 展示清单:
BUILTIN_TOOLS(agentica/cli/runtime.py:77)。tests/cli/test_builtin_tools_listing.py会在工厂长出一个它没列的函数时失败—— 这张清单曾经漂移过(write_todos缺失,而注释还写着 single source of truth)。 - 图标(可选):
TOOL_ICONS(同文件),缺省回落🔧。 - 文档:Tools 的内置工具表。
为什么没有「总开关」¶
builtin_tools=False 作为一个总开关被提过,并且被否决了
(CLAUDE.md:284)。因为 DeepAgent 即使关掉它,仍会 auto_load_mcp
并注入 BuiltinMemoryTool——这个名字会承诺一个它保证不了的保证。
需要白名单的调用方要的不是这个预设,而是 plain Agent 加上真正需要的那几个
预设,外加一条构造期对最终工具表的断言。
只有后者才拦得住「新加了一个默认开启的内置工具」这种情况。
判据的实际后果:两端一致的工具面¶
交互式 CLI 与 gateway 通过 build_product_tools() 拿到同一套产品工具
(worktree / self_manage / cronjob 等),差异只在 surface 专属回调;
worktree 不再因为「CLI-only」而缺席 Web / Desktop / IM。
--query / cron 复用 create_agent(surface="cli", ...),显式传
include_ask_user_question=False;没有 BackgroundProcessRegistry 时不注册
wait,execute 的 schema 里也不会保留 background 参数。工具表是否一致
以 tests/gateway/test_surface_parity.py 的字节比对为准,不靠手写工具数量。
BUILTIN_TOOLS(agentica/cli/runtime.py)包含 task 与 get_task_result:
后者是 task 定位符的只读回读工具;tests/cli/test_builtin_tools_listing.py
会在展示清单漏掉工厂新增函数时失败。