心中的海边城——SonettoHereAgent异步工具库设计全解

0. 前言

我已经忘记了我是什么时候开始学习Agent的了，似乎是在今年四月？我只记得工具(Tools)绝对是我接触的第一个Agent概念，真的没有之一。

与其它许多Agent一样，Sonetto的能力是靠一整套精心规划的工具集撑起的。不同Agent对于工具集这种基础设施的理解非常不同。PiAgent只有4个极简的工具作为工具集，而Hermes Agent有堂堂86个。

四个和八十六个工具的差异会是84/4=21倍吗？还是没有那么多？工具集会以什么样的形式影响Agent的能力边界？为什么庞大的工具集未必能带来更好的Agent表现？我会尝试告诉你。

本文以LangGraph@Python作为后端开发框架。在讨论脚本工具时，默认指Python脚本工具。

1. 关于工具

工具的本质是一个Python函数，拥有固定的输入和输出格式。LLM在ReAct环的Act阶段输出该函数的入参，函数的返回值回到LLM的上下文，以此获取工具的信息完成一次工具调用。

我们以Sonetto假期工具为例来看看吧。这个工具是对一个UAPI的薄封装，很适合用来研究一下工具的结构。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
@get_doc  
@background  
class HolidayCalendarTool(BaseTool):  
    name: str = "holiday_calendar"  
    description: str = (  
        "查询指定日期/月份/年份的万年历与节假日信息。"  
        "支持农历、节气、法定节假日。[调用积极性: 可自由看情况调用] [get_doc: 仅在发生错误时 get_doc]"    )  
    args_schema: type[BaseModel] = HolidayCalendarInput  
  
    def _run(  
        self,  
        date: str = "",  
        month: str = "",  
        year: str = "",  
        timezone: str = "Asia/Shanghai",  
        holiday_type: str = "all",  
        include_nearby: bool = False,  
        nearby_limit: int = 7,  
    ) -> str:  
        if not date and not month and not year:  
            return format_error("必须提供 date、month 或 year 参数之一")  
  
        try:  
            result = self.client.uapi.misc.get_misc_holiday_calendar(  
                date=date,  
                month=month,  
                year=year,  
                timezone=timezone,  
                holiday_type=holiday_type,  
                include_nearby=include_nearby,  
                nearby_limit=nearby_limit,  
                exclude_past=True,  
            )
            return format_success(result)  
        except Exception as e:  
            return format_error(f"节假日查询失败: {e}")

继承类原作ToolBase，是对BaseTool的功能添加，有修改

我们可以看到，一个工具由四个部分组成。

• 工具名。模型据此来选择工具进行调用。
• 工具描述。模型据此决定何时使用该工具。
• 入参格式。与业务函数的入参完全相同，使用pydantic进行描述
• 业务函数。负责生成返回值。

我们只要为继承了BaseTool的工具类实现上述四个部分，LangGraph就会自动帮我们完成入参格式与工具名提示词注入、FuncCall入参分析、返回值注入等等鸡毛蒜皮的小事。

2. 工具的涌现

对于几个工具，我们以A、B、C为例。如果A+B的组合可以让LLM获取到等价于C的信息，我们就说C这个工具被A和B涌现了，写作A+B=>C。比如说，Sonetto使用她的Tavily搜索工具Ts找到了一个天气网站，再用Tavily提取Te提取了天气内容，那么她便得到了与调用天气工具W相等价的信息，也就是Ts+Te => W。

Python脚本工具P是SonettoHere最重要的工具。它提供了极其强大的工具涌现能力。这是Skill体系的基础。假设天气获取技能S_W在SKILL.md上面记载着公开的天气API，甚至在Skill的脚本部提供了访问此API的方便函数，Agent就可以使用脚本工具访问此API来获得天气内容。此时P+S_W => W。

那么，我们为什么要为Agent提供被涌现掉的工具呢？

第一个原因是人在回路与信息传出的效率。为了提供人类协作方式，Sonetto通过ReAct中插入用户消息或打断输出的方式提供了人在回路的信息入口。那么与此相对地，我们也需要人在回路的信息出口，让信息从Agent流向人类，使得人类更有的放矢地调节Agent的推进行为。这个信息出口就是Sonetto v1时代森罗计划的内容。这个计划需要为工具提供一个精心设计的前端气泡，使得人类能够超高效地读取到工具调用的结果。

第二个原因是稳定性与ReAct推进效率。很难说Sonetto在Ts没有找到公开的天气API接口的时候后续会怎么做。封装出一个工具能极大地降低Agent出错的可能，同时降低token消耗。

3. Sonetto的工具集

Sonetto的工具集分为多个向外推进的环形。越往外环，工具越可被涌现。

零环 一切的一切

我们选用了Python作为Sonetto的脚本工具，因为Sonetto的后端就是Python，况且许多Skill的脚本是用Python写的。

如果Sonetto没有脚本工具，几乎不可能通过其它工具把它涌现出来。这就是一切的一切。

一环 由于特殊原因不可涌现的工具

子智能体。这个Sonetto进行复杂大上下文任务处理的工具涉及复杂的前端和后端编排，不能由Python进行涌现。

同理，依赖于复杂前后端异步通信的用户交互系列工具（单选、多选、输入）也不可涌现。

以及后台任务相关工具（list、await）这种涉及本工程内部后端编排的。

还有前端任务显示这种涉及前端通信的。

二环 难以涌现的工具

你总不能指望Sonetto仅凭LLM训练语料就复诵出一个能用的公开搜索API来，所以网络搜索工具是必要的。借助Tavily网络搜索工具，大量外源信息流入上下文，工具的涌现性将达到极大增强。一并封装了个提取工具。

三环 出于特殊原因而封装的可涌现工具

从三环开始，工具都可以被涌现出来了。这些工具是出于人在回路和安全原因才封装的。

所有文件操作工具都能被Python涌现覆盖，但我们还是封装了它们。原因是侵彻性的文件操作必须经由人在回路进行确认，这依赖于这些操作有一个可监视的入口。使用Python操作文件就很难从静态代码分析出来这是在对文件进行什么操作了。所以Sonetto封装了一整套文件处理工具集。

委托/自理解两个图像理解工具。需要做一点网安性质的路径校验，所以没让Sonetto用Python来搞。

四环 Sonetto高级业务工具

本环的工具全部可以由Python结合Skill涌现覆盖。它们是出于稳定性与ReAct推进效率才封装的。

包括全部高德地图工具和Todoist系列工具。你可以从这两个系列工具看出来Sonetto规划生活的Agent特色。

以及天气和假日工具。

五环 彩蛋性质工具

塔罗牌。这个工具从里到外都应该使用Skill实现。它实在是太Skill了，有Reference，有Script，最好还要有SKILL.md教Sonetto解牌。但是我觉得封装成工具看前端气泡可以增强沉浸感，就这么干了。

4. 工具装饰器框架的代码设计

对于所有Sonetto的工具，我们发现以下三个功能具备跨工具的特点，每个工具都可能取得三个功能中的一个或多个：

• 人在回路确认气泡。在前端弹出气泡展示该工具的入参，等待用户的审批。用户有自由输入信道，在拒绝时可以将任意文本发送给Agent。
• 读取工具辅助文档。添加get_doc: bool入参，读取与该工具相同目录下的TOOL.md获取使用方式指导。
• 背景执行。为工具添加background: bool入参，允许工具进入后台执行并返回取得结果的令牌。使用await提交令牌并进行可能的阻塞等待以取得实际返回值。

这三个功能站在架构师的视角上有不同的实现方案。我是这么想的，如果使用继承，我需要为BaseTool建立三个一级子类，然后三个一级子类可以交织出来8个不同的二级子类，如何保证这些逻辑全部正确地进入_arun从而被LangGraph框架调用是很困难的。

所以最后我选择了基于传统装饰器组合设计模式的面向切面编程（AOP）。使用Python程序员喜闻乐见的装饰器对Tool类进行修改，在不显式持有业务类的情况下劫持_arun函数和入参args_schema来注入相关的逻辑。

1
2
3
4
5
6
7
8
9
10
@get_doc  
@background  
class HolidayCalendarTool(ToolBase):  
    name: str = "holiday_calendar"  
    description: str = (  
        "查询指定日期/月份/年份的万年历与节假日信息。"  
        "支持农历、节气、法定节假日。[调用积极性: 可自由看情况调用] [get_doc: 仅在发生错误时 get_doc]"    )  
    args_schema: type[BaseModel] = HolidayCalendarInput  
  
    async def _arun(

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
def get_doc(cls: ToolClass) -> ToolClass:  
    """应用「按需返回领域文档」类装饰器。  
  
    Args:        cls: 目标工具类。  
    Returns:        增强后的 pydantic 子类。    """  
    def make_wrapper(orig: Callable[..., Any]) -> Callable[..., Any]:  
        @functools.wraps(orig)  
        async def async_wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:  
            if kwargs.pop("get_doc", False):  
                # TOOL.md 磁盘读取离环，避免卡事件循环  
                return await off_thread(self._load_doc)  
            return await orig(self, *args, **kwargs)  
  
        return async_wrapper  
  
    return enrich_tool_class(  
        cls,  
        schema_fields={  
            "get_doc": (bool, Field(default=False, description=DEFAULT_DESCRIPTION)),  
        },
        wrap_method=make_wrapper,  
    )

此框架未来可以扩展更多的功能。

5. 结尾

结尾部分草稿使用Agent写作 LLM z-ai/glm-5.3-flash HARNESS SonettoHere v3.6.0-preview 由人类逐段修改。

这就是SonettoHere工具集的全貌。这篇文章讲了三件事，工具是什么，工具如何相互涌现，以及我们如何用五个环和三个装饰器把如此多的工具交付给LLM。

从四月到现在，Sonetto 的工具集经历过好几次推倒重来。最早的时候我们还不知道何为涌现和Skill，犯过许多堆砌工具的毛病，把能想到的能力全部封装成工具交给Sonetto，结果LLM在长长的工具列表里陷入无法逃离的迷茫。后来才我们慢慢想明白，工具集的内在结构比规模更重要。不可涌现的工具留在核心，可以涌现的工具推离出去，直至环状的边缘而消失（点名编程系列工具）。五层环状的工具集就是这个想法落地的现状。

心中的海边城不在任何现实的地图上，它只存在于 Sonetto 的上下文窗口里。这座城市还在施工。装饰器框架预留了扩展点，五环之外或许还有新的环，旧工具也会被涌现、被拆掉、被重建。但只要现实的需要还在，这座海边城就会一直生长下去。

事实证明z-ai/glm-5.3-flash并不太适合文本写作。

• Previous
  湾流离岸——SonettoHere长期记忆系统"湾流"技术报告
• Next
  TSCTF-J 2026 Web 五题 WriteUp