简要总结
Plugin Agent Tools
这页说明书在讲一个叫“工具”的小帮手。就像你的玩具箱里有不同的玩具一样，这里的小帮手（工具）可以帮智能大脑（LLM）做更多事情。有的小帮手是必须带着的，有的小帮手是你可以自己选择要不要带的。这页会告诉大人们怎么把这些小帮手放进玩具箱里，以及怎么告诉智能大脑可以用哪些小帮手。
五岁小孩版解释
想象一下，智能大脑（LLM）就像一个很聪明但需要工具的小朋友。插件（Plugin）可以给它准备一些“工具”，就像小铲子、小画笔一样，让它能挖土或者画画。这些工具是用一种叫 JSON‑schema 的规则写好的“说明书”，告诉大脑这个工具怎么用。
工具分两种：
- 必须的工具：智能大脑每次玩的时候，都自动带着这些工具。
- 可选的工具：这些工具不会自动给大脑用。只有你（用户）特别允许了，大脑才能用它们。
怎么给大脑准备工具呢？ 大人们需要在一个叫“配置文件”的地方写下来。有两个地方可以写：
- 在主配置文件里，一个叫
tools的地方。 - 或者，在专门为某个大脑（agent）写的配置里，一个叫
agents.list[].tools的地方。
怎么控制大脑能用哪些工具？ 有一个“允许名单”和“拒绝名单”的规则。就像你可以规定“只允许玩积木和画笔”一样，这个名单决定了大脑可以叫哪个小帮手（工具）来帮忙。
怎么做一个简单的“必须工具”？ 大人们需要写一小段代码来“注册”一个工具。我们来看看这段代码在做什么：
- 给它起名字：
name: "my_tool"。这是工具的名字，比如叫“我的小铲子”。 - 告诉大脑它能干嘛：
description: "Do a thing"。这是说“这个小铲子可以用来挖东西”。 - 告诉大脑怎么用：
parameters: ...这部分是“使用说明书”，规定用这个工具时需要给它什么。比如这里需要一个叫input的“文字”。 - 告诉工具接到命令后做什么：
async execute(...)这部分是工具真正干活的步骤。比如这里它会把收到的input文字原样说出来。
怎么做一个“可选工具”？
和上面很像，但在最后要加一句 { optional: true }。这就像在玩具上贴了个标签，写着“需要爸爸妈妈同意才能玩”。这样，这个工具就不会自动给大脑用了。
怎么允许大脑使用“可选工具”？
你需要在配置文件里，把工具的名字加到“允许名单”里。名单写在 agents.list[].tools.allow 这个地方（或者全局的 tools.allow 里）。你可以这样写：
"workflow_tool"：允许名字叫workflow_tool的这一个工具。"workflow"：允许所有来自一个叫workflow的插件里的工具。"group:plugins"：允许所有来自插件的工具。
其他影响工具使用的“小开关” 配置文件里还有一些其他地方也能影响工具：
tools.profile：一个基础的“允许名单”模板。tools.byProvider：可以针对不同的大脑供应商（provider）设置不同的允许/拒绝规则。tools.sandbox.tools.*：当大脑在“沙箱”（一个安全的玩耍区域）里时，对工具的特别规定。
重要规则和小提醒
- 起名字要小心：你给工具起的名字，不能和系统自带的“核心工具”名字一样。如果名字冲突了，你的工具会被忽略掉。
- 插件名字也要小心：在“允许名单”里用的插件ID，也不能和核心工具的名字冲突。
- 安全第一：如果一个工具会做很重要的事情（比如发信息），或者需要特别的密码或软件才能用，最好把它做成“可选工具”（
optional: true），这样更安全。