Skip to Content
JavaScript SdkExamplesClient tools

Client tools

角色的客户端工具在你的页面里执行：模型决定调用某个工具，由你的代码去做——打开商品页、加入购物车、弹出表单。 你在控制台或用 POST /v1/tools 创建工具（type: "client"，一个 name，一段告诉模型什么时候用它的 description， 以及 JSON Schema 格式的 parameters），并把它挂到角色上。然后在加入会话之前注册它要做的事：

const stop = client.registerToolCallHandler("open_product", {
  onStart: async ({ toolName, arguments: args }) => {
    showProduct(args.productId);
    return { shown: true };            // 结果：字符串原样返回，其他值转成 JSON
  },
  onComplete: ({ result, executionTime }) => {},
  onFail: ({ errorMessage }) => {},    // onStart 里抛出的错误
});
stop(); // 不再处理
  • arguments 按工具的 parameters schema，由模型填写。
  • 工具设了 awaitResult 时，模型会拿到 onStart 的结果，要在 toolTimeoutSeconds（默认 10）秒内返回，否则模型会得知应用没有及时回应。 不设 awaitResult（默认）时，模型立刻继续说下去；你的处理函数照样执行。
  • onStart 里抛出的错误会作为错误信息交给模型，让它告诉用户——所以抛出人能看懂的话：throw new Error("That product is out of stock")。
  • 没有注册处理函数的工具，会立刻告诉模型这一点。
  • 超过 15 KB 的结果会被截断；模型最多读前 4,000 个字符。
  • 每个工具名只有一个处理函数；再次注册会替换掉原来的。
ErrorsTyping to the character