工具是可编程的功能，AI 机器人可以使用它们来执行特定任务或检索信息，而不仅仅是基于文本的响应。这些工具是脚本或集成，允许机器人与外部 API 交互、操作数据或执行其他功能来扩展其功能。
本文档涵盖：
创建新的自定义 AI 工具
配置工具参数和脚本
可用于工具脚本的 API
将自定义工具与 AI 角色集成
测试和故障排除自定义工具
要创建新的 AI 工具：
导航到管理面板 > 插件 > Discourse AI > 工具
点击“新建工具”（您可以使用现有的预设来了解选项）
填写以下字段：
名称：工具在 LLM 中显示的名称
描述：工具在 LLM 中显示的描述
摘要：工具的作用以帮助用户的摘要（显示在详细信息中）
参数：定义工具作为 LLM 显示的输入
脚本：为工具提供动力的 JavaScript 代码
点击“保存”
您的工具脚本可以访问以下 API：
HTTP 请求：
http.get(url, options)
http.post(url, options)
使用这些与外部服务进行交互。您可以使用 options 来指定 HTTP 标头：
http.get(url, { headers: { Auth: "some value" } })
http.post(url, { headers: { Auth: "some value", body: "some body" } })
http.patch(url, { headers: { Auth: "some value", body: "some body" } })
http.delete(url, { headers: ...})
http.put(url, { headers: ... , body: ...})
LLM（语言模型）集成：
llm.truncate(text, length)
这允许您在 AI 模型令牌限制内操作文本。
自定义上传集成 (RAG)
index.search(query, { filenames: options, limit: max_fragments_optional })
上传创建支持
upload.create(filename, base_64_content)
执行链控制
chain.setCustomRaw(raw) - 设置链中 post 的正文。
您的脚本必须实现：
invoke(params)：调用工具时执行的主函数
它还可以选择实现：
details()：（可选）提供有关工具执行的附加信息
示例脚本：
function invoke(params) {
let result = http.get("https://api.example.com/data?query=" + params.query);
return JSON.parse(result.body);
}
function details() {
return "Fetched data from Example API";
}
执行超时：工具的默认超时时间为 2 秒
HTTP 请求：每个工具执行最多 20 个请求
沙盒环境：无法访问服务器文件系统或 Ruby 库
您应该测试您构建的任何工具，以确保提供给 LLM 的结果符合您的预期。
要将自定义工具添加到 AI 角色：
转到管理面板 > 插件 > Discourse AI > 角色
编辑现有角色或创建新角色
在“工具”部分，您将看到自定义工具与内置工具并列显示
选择您的自定义工具以将其添加到角色
一旦您将自定义工具提供给 LLM，它就可以使用它来增强对话。
如果您的工具无法按预期工作：
使用测试界面确保它对您的输入表现符合预期。
确保您的组在 ai_bot_debugging_allowed_groups 中。此组的成员可以完全访问机器人会话记录；您可以在此处查看 AI 日志。
如果发生任何意外情况，请访问 https://SITENAME/logs 检查错误。
Discourse AI plugin.
Discourse AI - AI bot .
in this guide .
14 个赞
maiki
2024 年10 月 18 日 21:13
4
我刚开始为 Discourse 中的 AI 角色构建工具，部分原因是为了能够真正专注于此；鉴于存在如此多有用且公开的 API，这似乎非常有益！
例如，我得到的结果包括：
通过扑克策略理解决策制定
AI
maiki:
创建一个《塞尔达传说：旷野之息》的信息卡。
gpt-4o:
这是《塞尔达传说：旷野之息》的信息卡：
标题： 《塞尔达传说：旷野之息》开发商： 任天堂发行商： 任天堂发布日期： 2017 年 3 月 3 日平台： Nintendo Switch、Wii U类型： 动作冒险模式： 单人
剧情简介：
奖项：
更多信息： Wikidata 条目
《旷野之息》以重新定义开放世界游戏并提供鼓励探索和发现的迷人体验而闻名。
maiki:
为《集合啦！动物森友会》也做同样的事情。
gpt-4o:
这是《集合啦！动物森友会》的信息卡：
标题： 《集合啦！动物森友会》开发商： 任天堂发行商： 任天堂发布日期： 2020 年 3 月 20 日平台： Nintendo Switch类型： 社交模拟模式： 单人、多人
剧情简介：
奖项：
更多信息： Wikidata 条目
《集合啦！动物森友会》成为一种文化现象，因其引人入胜的社交功能和在充满挑战的时期缓解压力的游戏玩法而受到赞誉。
maiki:
远离芝加哥
gpt-4o:
这是关于书籍《远离芝加哥》的信息卡：
标题： 《远离芝加哥》作者： Richard Peck出版年份： 1998类型： 历史小说、青少年文学ISBN： 978-0141303529
剧情简介：
奖项：
更多信息： Wikidata 条目
这本书因其怀旧而温馨的故事而受到赞赏，捕捉了家庭纽带和简单时光的精髓。
maiki:
思考的赌注
gpt-4o:
我之前找到了“思考的赌注”的 Wikidata 条目，但目前无法直接从 Wikidata 获取更多具体细节。不过，这是基于现有信息的一个简短卡片：
标题： 《思考的赌注：在信息不全时做出更明智的决定》作者： Annie Duke出版年份： 2018类型： 非虚构、决策、心理学ISBN： 978-0735216358
剧情简介：
更多信息： Wikidata 条目
如需详细见解，您可以考虑查阅有关书籍出版物的其他资源或数据库。
好的，这没问题，但我注意到这个描述……
……我想知道：我是否应该直接参考这些工具来构建我的提示，以便高效使用？
我编写提示的一般方法是随着时间的推移进行完善，然后锁定我希望 AI 工具采用的行为模式。但是，如果我能够添加具体的说明，例如何时查找 Wikidata 条目，以及何时列出特定条目的所有声明（两个不同的 API），那么我觉得我可以将整个工作流程精炼成我想要的样子……
4 个赞
在系统提示中清楚地解释工具并提供示例确实是有益的。
2 个赞
在自定义工具中是否可以从管理员设置中插入 API 密钥和 OpenAI 项目？
1 个赞
sam
2025 年1 月 20 日 22:21
7
您可以从自定义工具发出 REST 调用并指定所有标头
2 个赞
tpetrov
2025 年9 月 26 日 13:34
9
我已经将一些文档上传到一个 Persona，它生成了嵌入，现在可以对其进行语义搜索。但在某些情况下，语义搜索并非理想选择，因此我想对其进行增强，实现混合搜索，例如保留现有功能并添加关键字搜索。目前，如果我想这样做，我应该编写一个自定义工具，对吗？
jorge-gbs
2026 年1 月 25 日 15:10
10
当我添加一个带有数组参数的自定义工具时，我看到了一个工具架构错误。错误在对话开始时出现：
{
“error”: {
“code”: 400,
“message”: “* GenerateContentRequest.tools[0].function_declarations[3].parameters.properties[properties].items: 缺少字段。\\n”,
“status”: “INVALID_ARGUMENT”
}
}
我尝试了什么：
创建了一个名为 properties、类型为数组的自定义工具参数。
参数列表 UI 不允许指定 items。
导出了/导入了一个完整的工具 JSON，其中包含 items: { type: “string” } 用于 properties。
导入后，只要工具对某个角色启用，错误就会持续存在。如果我删除该工具，机器人就能正常工作。
预期：
参数列表 UI 应该允许定义数组项类型，或者导入应该遵守 items 使得架构验证通过。
有人遇到过这个问题吗？是否存在已知的限制或定义数组参数所需的 UI 路径？
1 个赞
本指南介绍了如何在 Discourse AI 插件中创建、配置和集成自定义 AI 工具，使管理员能够通过用户定义的 JavaScript 函数扩展机器人的功能。
所需用户级别：管理员
