Custom Tools

Let your AI call your own endpoints to fetch live, customer-specific data

Standard & Pro 套餐

概述

自定义工具让您的 AI 助手在对话过程中调用您自己的 API 端点，以获取实时的、针对具体请求的数据——订单状态、物流跟踪、特定 SKU 的库存、账户详情等等。

Asyntai 提供三种方式向 AI 输送实时或针对客户的数据。当 AI 所需的值仅在对话过程中才出现时，自定义工具是正确的选择：

实时数据源——将一份固定的数据集（例如您的整个产品目录）加载到每一次对话中。最适合对所有访客都相同的共享数据。
用户上下文——您的网站在对话开始时推送其已知的关于当前访客的数据（例如已登录客户的姓名、套餐或最近的订单）。最适合访客身份在一开始就已确定的情况。
自定义工具——AI 按需调用您的端点，并传入它从聊天中提取的值。最适合在客户输入之前无法得知该值的情况——例如来自匿名访客的订单号。

例如，当客户询问“我的订单 #10294 在哪里？”时，AI 会提取订单号，用它调用您的端点，并根据经过验证的响应作答。用户上下文本身无法涵盖这种情况，因为订单号在对话中途之前都是未知的——这正是自定义工具发挥作用的地方。（许多商店为已登录访客使用用户上下文，同时为临时查询使用自定义工具。）

AI 会根据您编写的描述决定何时调用工具。您通过将工具指向您的端点来决定工具做什么。Asyntai 在服务器端发起调用——您无需编写代码，也无需托管任何中间件。

工作原理

您定义一个工具——包括名称、描述、端点 URL 以及 AI 应发送的参数。
AI 在相关时调用它——当对话与您的描述相符时，AI 会用它从客户消息中提取的值来调用该工具。
Asyntai 调用您的端点——我们的服务器向您的 URL 发起 HTTP 请求，并将响应回传给 AI。
AI 作答——使用您的端点返回的经过验证的数据。

无需编写代码：您只需要一个已经能返回您数据的端点。其余一切都在仪表板的表单中配置——无需构建任何回调、Webhook 或浏览器脚本。

使用场景

订单状态 通过单号查询订单并返回其当前状态

物流跟踪 返回某个跟踪单号的最新物流状态

库存查询 返回特定产品或 SKU 的实时可用情况

账户查询 根据标识符返回账户或订阅详情

设置

打开自定义工具 前往 /custom-tools/ 并点击添加工具

描述该工具 为其设置名称、清晰的描述以及您的端点 URL

定义参数 添加 AI 应提取并发送的输入项（例如 order_number）

保存 & 测试 保存后，向您的机器人提出一个匹配的问题，即可看到它的实际运行效果

字段

名称——函数的标识符（字母、数字、下划线），例如 get_order_status。AI 会看到这个名称。
描述——最重要的字段。它告诉 AI 何时调用该工具。要明确具体：“每当客户提到订单号时就调用此工具。不要要求验证。”
端点 URL——Asyntai 将调用的公开 HTTPS URL。
HTTP 方法——GET（只读，推荐）或 POST（可更改数据——请参阅下方的“安全”部分）。
参数——AI 从对话中提取并发送的输入项。每个参数都有名称、类型、描述以及是否必填的标志。对于 GET，它们作为查询字符串参数发送；对于 POST，则作为 JSON 主体发送。
认证头 （可选）——在每次调用时发送的头名称 + 值，例如 X-API-Key。如果您的端点需要密钥，请使用此项。

AI 必须有参数才能传递任何值。如果您的端点需要某个输入（例如订单号），您必须为其添加一个参数——没有参数，AI 就没有放置该值的位置，会以空值调用端点。有两点很重要：

参数名称必须与您的端点所期望的完全一致。名为 order_number 的参数会作为 ?order_number=...（GET）或 {"order_number": "..."}（POST）发送。如果您的端点读取的是 id，请将该参数命名为 id。
您从不自己输入该值——您只需声明参数。AI 会在调用时根据客户所写的内容来填充它。

实例演示：订单状态查询

假设您的商店开放了以下端点：

GET https://yourstore.com/api/order-status?order_number=10294

……它返回如下所示的 JSON：

{
  "found": true,
  "status": "Accepted, preparing for shipment",
  "carrier": "DHL",
  "customer_message": "Your order has been accepted and is being prepared for shipment."
}

您可以这样配置一个工具：

名称：get_order_status
描述：“查询客户订单的状态。每当客户提供订单号时立即调用此工具——不要要求额外验证。在你的回复中使用返回的 customer_message。”
端点 URL：https://yourstore.com/api/order-status
方法：GET
参数：order_number（字符串，必填）——“客户的订单号，通常为 8 位以上数字。”

当客户写下“我的订单 #10294 怎么样了？”时，AI 会调用 get_order_status(order_number=10294)，Asyntai 用 ?order_number=10294 请求您的 URL，然后 AI 根据响应作答。

提示：AI 会发送它自行决定的值——您从不预先填写。请保持参数名称和描述清晰，以便模型确切知道要提取什么。

您的端点会接收什么以及应返回什么

请求：一个在查询字符串中带有您参数的 GET，或一个带有 JSON 主体的 POST。您配置的任何认证头都会被包含在内。
响应：返回 JSON（推荐）或纯文本。Asyntai 会将主体回传给 AI。一个 AI 可以直接引用的字段——例如 customer_message——效果很好。
未找到 / 错误：返回清晰的负载（例如一个带有 found: false 和 customer_message 的 JSON 对象），以便 AI 能够如实回答，而不是凭空猜测。

测试您的工具

每个工具在配置页面上都有一个内置的测试此工具面板，因此您可以在任何客户使用之前验证它是否正常工作——而且无需通过机器人发送消息。

为工具的参数输入示例值（例如一个真实的订单号）。
点击运行测试。Asyntai 会完全像 AI 那样调用您的端点——相同的查询字符串或 JSON 主体、相同的认证头、相同的 5 秒超时和安全检查。
您将立即看到结果：成功/失败标记、HTTP 状态、响应时间、我们调用的确切 URL，以及您端点的原始响应（如果是 JSON，会以美观的格式显示）。

这对未保存的编辑同样有效，因此您可以调整 URL、参数或认证头并重新测试，直到它返回您所期望的结果。

注意：测试 POST 工具会真正调用您的端点，并可能更改数据——测试面板会在您运行前发出警告。对于只读的 GET 工具则无需担心。

安全——请阅读此部分

安全边界是您的端点，而不是 AI。聊天组件是公开的，访客可以操纵 AI 用任意值调用工具。这对每一个 AI 工具调用系统都成立。请据此设计您的端点：

优先使用 GET / 只读。查询类操作（订单状态、库存、物流跟踪）可以安全地对外开放。正因如此，GET 是默认设置。
POST 需要确认。由于 POST 可以更改数据，POST 工具只有在您勾选一个复选框、确认您独自负责在自己的端点上保护并授权请求之后才能保存。除非您的端点能独立验证请求，否则切勿连接退款、取消、密码更改或资金转移等操作。
防范枚举攻击。如果查询键是可猜测的（例如连续的订单号），请要求第二个验证要素——例如订单号以及订单上的电子邮箱，并验证二者是否匹配——这样访客就无法通过尝试编号来读取其他客户的数据。
切勿信任 AI 的参数。在服务器端验证并授权每一个请求，就当它来自匿名攻击者一样——因为实际上确实可能如此。

验证实时调用

您的工具上线后，对话中的每一次真实调用都会被记录下来。对于每次调用，我们都会记录工具名称、AI 发送的参数、我们请求的确切 URL、HTTP 状态、响应以及持续时间。这让您无需翻查自己的服务器日志，就能确认某个工具在真实聊天中被触发，并查看您的端点返回了什么。（上方的测试此工具面板用于您自己检查配置；而此日志记录的是实际客户对话期间发生的情况。）

限制 & 防护措施

每个网站最多 10 个工具。
每次调用 5 秒超时；响应上限为 10 KB。
端点必须是公开的 http(s) URL。私有地址、回环地址和内部网络地址将被阻止。
适用于 Standard 和 Pro 套餐。
计费：每次工具调用都会按套餐中的一条额外消息计算。普通回复使用 1 条消息；AI 调用一个工具的回复使用 2 条（回复加上工具调用），因为工具调用需要一次额外的 AI 请求。
如果工具调用失败（超时、错误、被阻止），AI 会得到通知并妥善作答——它不会让对话崩溃。

文档