给AI Agent装上第一个工具:日历查询实战

给 Agent 装工具只需一个带装饰器的 Python 函数和一段 docstring。
文章以短视频教程 Ep 16 为例,讲解如何让 AI Agent 读取日历。核心观点是:工具的本质就是一个加了函数工具装饰器的 Python 函数,不需要复杂协议或服务框架。模型通过 docstring 理解工具用途,因此描述质量直接决定调用准确性;模型本身不读实现代码,只读你对工具的描述。使用方式只有两步:把工具传入 tools 列表,然后像聊天一样提问,Agent 会自主判断是否调用 get_events 并基于返回结果作答。教程建议先用演示数据跑通“提问—调用—回答”链路,再接入真实日历,以避免调试问题与权限问题混杂。同一模式可复用于邮件、表格等任何可封装为函数的能力,系列下一集将演示起草邮件回复的 Agent。
AI Agent 听起来很神秘,但让它“动手做事”的第一步其实很朴素:给它一个工具。最近一集短视频教程(Ep 16)演示了如何让 Agent 读取你的日历,整个过程不到一分钟就能讲清楚,但背后的设计思路值得展开。
工具的本质:一个带装饰器的 Python 函数

教程给出的定义非常直接:一个工具就是一个 Python 函数,加上函数工具装饰器(function tool decorator)即可。没有复杂的协议,也不需要额外的服务框架。
这个定义揭示了一个被很多教程忽略的事实:Agent 的能力边界,本质上取决于你愿意给它写多少个函数。装饰器负责把函数“注册”给模型,模型看到的是一个可调用的工具,而不是一段代码。
文中提到的“函数工具装饰器”是 function calling(函数调用)机制的一种实现方式。当前主流大模型 API(如 OpenAI、Anthropic)都支持让模型输出结构化的函数调用请求:你通过参数把可用工具的名称、描述和参数 schema 告诉模型,模型在需要时返回一个“我要调用某函数、参数是这些”的结构化结果,由你的代码实际执行函数并把结果回传给模型继续生成。装饰器的作用正是自动从 Python 函数的签名和 docstring 中提取这些元信息,生成模型所需的工具描述,省去手写 JSON schema 的麻烦。理解这一层就能明白:模型本身并不执行代码,它只负责“决定调用什么”,真正的执行发生在你的进程里。
Docstring 就是 Agent 的使用说明书

函数写好后,Agent 怎么知道它是干嘛的?答案是 docstring。教程强调,docstring 告诉 Agent 这个工具做什么。
这一点在实际开发中容易被低估。模型不会读你的实现逻辑,它只读你对工具的描述。描述写得含糊,模型就可能在不该调用的时候调用,或者该调用时不调用。写好 docstring,相当于给 Agent 写了一份它唯一会看的产品文档。
Docstring 之所以关键,是因为它会被序列化进发给模型的工具描述里,通常包含函数用途说明以及参数的类型和含义。模型在每一轮对话中都会看到这份描述,并据此判断当前问题是否需要调用工具、以及各参数该填什么值。实践中常见的失败模式包括:描述过于笼统导致模型在无关问题上误调用;参数说明缺失导致模型编造参数值;多个工具描述高度相似导致模型选错工具。因此 docstring 应当写清“什么时候用”“输入是什么格式”“返回什么内容”,必要时在描述中给出示例值,这比在函数名上做文章更有效。
演示数据先行,真实数据后换

视频里的日历数据是演示用的,教程明确说明:先跑通流程,之后再换成你的真实日历。
这个顺序值得借鉴。先用假数据验证“提问—调用—回答”的链路是否通畅,再接真实数据源,可以避免把调试问题和数据权限问题搅在一起。真实日历的接入涉及认证、权限、时区等一堆琐事,放在链路验证之后处理更高效。
把工具传进列表,然后像聊天一样提问

使用方式只有两步:把工具传进 tools 列表,然后问一个问题。
接下来发生的事是 Agent 自主完成的:它判断需要调用 get_events(示例中的函数名),读取返回结果,再用自然语言回答你。教程特别提到,同样的模式适用于邮件、表格,以及几乎任何你能写成函数的东西。
这意味着 Agent 的开发范式可以概括为一句话:你负责把能力封装成函数,模型负责决定何时调用。日历只是第一个例子,后面接什么取决于你的需求。
这里描述的“传进 tools 列表再提问”背后是一个多轮循环:用户提问后,模型可能先返回工具调用请求而非最终答案;你的程序执行对应函数,把返回值作为一条工具结果消息追加进对话历史,再次请求模型;模型基于结果决定是继续调用其他工具还是给出自然语言回答。这个“模型请求—程序执行—结果回传”的循环可能重复多次,直到模型输出最终答案。理解这个循环有助于排查问题:如果 Agent 没有调用工具,通常是工具描述或提问措辞的问题;如果调用后回答不对,则要检查函数返回的数据格式是否对模型友好。
系列课程的下一步
教程预告了第 17 集:一个能帮你起草邮件回复的 Agent。如果按顺序跟下来,从读日历到写邮件,是一条从“读取信息”到“生成内容”的渐进路径。对于想系统搭建 Agent 能力的人来说,按顺序学比跳着看更划算。
几点实践提醒
- 工具命名要直白:
get_events这种名字模型一看就懂,比抽象命名更可靠。 - docstring 写清楚输入输出:模型靠它判断参数怎么填。
- 先用演示数据跑通链路:真实数据接入是后置步骤。
- 从一个工具开始:模式跑通后,扩展到邮件、表格只是复制同一套结构。
给 Agent 装工具这件事,门槛比想象中低。一个函数、一行装饰器、一段 docstring,就能让模型从“聊天”变成“办事”。
相关推荐
科技前沿Textly:Mac上任意位置抓取文字和表格的效率神器
Textly是一款Mac菜单栏效率工具,支持从截图、PDF、视频和应用中框选捕获文字与表格,保持行列完整并导出CSV、Markdown、TSV,还内置即时翻译和剪贴板历史。
科技前沿Frameboy:World Labs Atlas 世界模型浏览器实时体验
World Labs 在 Product Hunt 发布 Frameboy,基于 Atlas 世界模型的浏览器实时演示,移动相机即可在云端 GPU 生成新视角,最高 15 fps 串流,探索 AI 生成的可漫游世界。
科技前沿Keypause:一键锁定Mac键盘,清洁时不再误触
Keypause是一款Mac菜单栏应用,一键锁定键盘所有按键,方便清洁时避免误触。本文介绍其功能、使用体验、潜在风险及适用场景,帮你判断是否值得尝试。