[控场AI]
科技前沿· 4 分钟阅读· 2,470 字

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

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

给 Agent 装工具只需一个带装饰器的 Python 函数和一段 docstring。

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

AI Agent 听起来很神秘,但让它“动手做事”的第一步其实很朴素:给它一个工具。最近一集短视频教程(Ep 16)演示了如何让 Agent 读取你的日历,整个过程不到一分钟就能讲清楚,但背后的设计思路值得展开。

工具的本质:一个带装饰器的 Python 函数

A tool is just a Python function with the function tool decorator.

教程给出的定义非常直接:一个工具就是一个 Python 函数,加上函数工具装饰器(function tool decorator)即可。没有复杂的协议,也不需要额外的服务框架。

这个定义揭示了一个被很多教程忽略的事实:Agent 的能力边界,本质上取决于你愿意给它写多少个函数。装饰器负责把函数“注册”给模型,模型看到的是一个可调用的工具,而不是一段代码。

文中提到的“函数工具装饰器”是 function calling(函数调用)机制的一种实现方式。当前主流大模型 API(如 OpenAI、Anthropic)都支持让模型输出结构化的函数调用请求:你通过参数把可用工具的名称、描述和参数 schema 告诉模型,模型在需要时返回一个“我要调用某函数、参数是这些”的结构化结果,由你的代码实际执行函数并把结果回传给模型继续生成。装饰器的作用正是自动从 Python 函数的签名和 docstring 中提取这些元信息,生成模型所需的工具描述,省去手写 JSON schema 的麻烦。理解这一层就能明白:模型本身并不执行代码,它只负责“决定调用什么”,真正的执行发生在你的进程里。

Docstring 就是 Agent 的使用说明书

The docstring tells the agent what it does.

函数写好后,Agent 怎么知道它是干嘛的?答案是 docstring。教程强调,docstring 告诉 Agent 这个工具做什么。

这一点在实际开发中容易被低估。模型不会读你的实现逻辑,它只读你对工具的描述。描述写得含糊,模型就可能在不该调用的时候调用,或者该调用时不调用。写好 docstring,相当于给 Agent 写了一份它唯一会看的产品文档。

Docstring 之所以关键,是因为它会被序列化进发给模型的工具描述里,通常包含函数用途说明以及参数的类型和含义。模型在每一轮对话中都会看到这份描述,并据此判断当前问题是否需要调用工具、以及各参数该填什么值。实践中常见的失败模式包括:描述过于笼统导致模型在无关问题上误调用;参数说明缺失导致模型编造参数值;多个工具描述高度相似导致模型选错工具。因此 docstring 应当写清“什么时候用”“输入是什么格式”“返回什么内容”,必要时在描述中给出示例值,这比在函数名上做文章更有效。

演示数据先行,真实数据后换

This is demo data, and later you swap in your real calendar.

视频里的日历数据是演示用的,教程明确说明:先跑通流程,之后再换成你的真实日历。

这个顺序值得借鉴。先用假数据验证“提问—调用—回答”的链路是否通畅,再接真实数据源,可以避免把调试问题和数据权限问题搅在一起。真实日历的接入涉及认证、权限、时区等一堆琐事,放在链路验证之后处理更高效。

把工具传进列表,然后像聊天一样提问

Pass it in the tools list, then ask a question.

使用方式只有两步:把工具传进 tools 列表,然后问一个问题。

接下来发生的事是 Agent 自主完成的:它判断需要调用 get_events(示例中的函数名),读取返回结果,再用自然语言回答你。教程特别提到,同样的模式适用于邮件、表格,以及几乎任何你能写成函数的东西。

这意味着 Agent 的开发范式可以概括为一句话:你负责把能力封装成函数,模型负责决定何时调用。日历只是第一个例子,后面接什么取决于你的需求。

这里描述的“传进 tools 列表再提问”背后是一个多轮循环:用户提问后,模型可能先返回工具调用请求而非最终答案;你的程序执行对应函数,把返回值作为一条工具结果消息追加进对话历史,再次请求模型;模型基于结果决定是继续调用其他工具还是给出自然语言回答。这个“模型请求—程序执行—结果回传”的循环可能重复多次,直到模型输出最终答案。理解这个循环有助于排查问题:如果 Agent 没有调用工具,通常是工具描述或提问措辞的问题;如果调用后回答不对,则要检查函数返回的数据格式是否对模型友好。

系列课程的下一步

教程预告了第 17 集:一个能帮你起草邮件回复的 Agent。如果按顺序跟下来,从读日历到写邮件,是一条从“读取信息”到“生成内容”的渐进路径。对于想系统搭建 Agent 能力的人来说,按顺序学比跳着看更划算。

几点实践提醒

  • 工具命名要直白:get_events 这种名字模型一看就懂,比抽象命名更可靠。
  • docstring 写清楚输入输出:模型靠它判断参数怎么填。
  • 先用演示数据跑通链路:真实数据接入是后置步骤。
  • 从一个工具开始:模式跑通后,扩展到邮件、表格只是复制同一套结构。

给 Agent 装工具这件事,门槛比想象中低。一个函数、一行装饰器、一段 docstring,就能让模型从“聊天”变成“办事”。

#AI Agent#函数工具装饰器#Python 工具开发#Agent 工具调用#docstring#日历查询#AI 编程教程
分享:

相关推荐