create-client-tool

创建客户端工具

搭建一个名为 $ARGUMENTS 的 AtlasTool。如果应用没有经过批准的应用内 useAtlasChat，请改用 integrate-fusion-agent 实现 Fusion action。

**前提条件：**已从 integrate-atlas-chat 引入 src/atlas-agent/ 和 @sinclair/typebox。

背景

客户端工具让 Atlas Agent 能调用浏览器端逻辑——图表、本地状态、UI 面板、导航。由 Agent 决定何时调用；应用负责执行并返回结果。

1. Agent 使用 clientTool action 响应
2. TypeBox 验证参数
3. execute() 在浏览器中运行并返回 { output, details }
4. output（字符串）会发送回 Agent
5. details 可通过 message.toolCalls 获取，供 UI 渲染

---

第 1 步 — 了解代码库

开始编写前，请阅读：

• 调用 useAtlasChat 的文件（通常是 src/App.tsx 或聊天 hook），找到传入 tools 的位置——在执行 integrate-atlas-chat 后，导入通常来自 ./atlas-agent/react
• 现有工具定义，以遵循文件和命名约定

---

第 2 步 — 定义工具

使用 @sinclair/typebox 中的 Type 定义参数 schema（编译时类型 + 运行时验证）。

import { Type } from "@sinclair/typebox";
import type { AtlasTool } from "./atlas-agent/types";

export const myTool: AtlasTool = {
  name: "my_tool",            // snake_case — this is what the agent uses to invoke it
  description:
    "One sentence describing what this tool does and when the agent should call it.",
  parameters: Type.Object({
    exampleParam: Type.String({ description: "What this param is for" }),
    optionalNum: Type.Optional(Type.Number({ description: "..." })),
  }),
  execute: async (args) => {
    return {
      output: "Plain text summary sent back to the agent",
      details: {
        // Any structured data you want available in the UI via message.toolCalls
      },
    };
  },
};

如果工具文件不在 src/ 下、与 atlas-agent 文件夹同级，请调整 ./atlas-agent/... 路径（例如，从 src/tools/ 使用 ../atlas-agent/types）。

TypeBox 快速参考

Schema	用途
Type.String()	字符串
Type.Number()	数字
Type.Boolean()	布尔值
Type.Literal("foo")	精确值
Type.Union([Type.Literal("a"), Type.Literal("b")])	枚举
Type.Array(Type.String())	字符串数组
Type.Object({ ... })	对象
Type.Optional(...)	将任意字段标记为可选

始终为工具及其每个参数添加 description——Agent 会使用这些字符串。

---

第 3 步 — 接入 useAtlasChat

找到 useAtlasChat 调用，并将工具添加到 tools 数组中：

const { messages, send, ... } = useAtlasChat({
  client: isLoading ? null : sdk,
  agentExternalId: AGENT_EXTERNAL_ID,
  tools: [myTool],   // add here
});

---

第 4 步 — 渲染工具结果（如有需要）

如果工具返回结构化的 details，请在消息列表中渲染。 message.toolCalls 是一个 ToolCall[]——每次工具调用对应一个条目（包括客户端和服务端调用），并按调用顺序排列。

{msg.toolCalls?.map((tc, i) => (
  // tc.name    — tool name
  // tc.output  — the string sent back to the agent
  // tc.details — your structured data (cast to your known shape)
  <MyToolOutput key={i} data={tc.details as MyToolDetails} />
))}