create-client-tool

创建客户端工具

为名为 $ARGUMENTS 的新 AtlasTool 搭建脚手架，并将其接入应用。

背景

客户端工具让 Atlas Agent 可以调用在浏览器中运行的逻辑，例如渲染图表、查询本地状态、显示 UI 面板、触发导航等。由 Agent 决定何时调用工具；应用执行工具并返回结果。

流程如下：

1. Agent 返回一个 clientTool 操作
2. 库根据 TypeBox 架构验证参数
3. execute() 在浏览器中运行，并返回 { output, details }
4. output（字符串）作为工具结果发送回 Agent
5. details（任意结构）可通过 message.toolCalls 提供给 UI 渲染

---

步骤 1 — 了解代码库

开始编写前，请先阅读：

• 调用 useAtlasChat 的文件（很可能是 src/App.tsx），以找到传入 tools 的位置
• 任何已有的工具定义，以遵循文件和命名约定

---

步骤 2 — 定义工具

将工具定义为带类型的常量。使用来自 @cognite/dune-industrial-components/atlas-agent 的 Type 定义参数架构，这样既能获得编译时类型，也能进行运行时验证。

import { Type } from "@cognite/dune-industrial-components/atlas-agent";
import type { AtlasTool } from "@cognite/dune-industrial-components/atlas-agent";

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) => {
    // args is fully typed from the schema above
    // Do the work here — call APIs, update state, render UI, etc.
    return {
      output: "Plain text summary sent back to the agent",
      details: {
        // Any structured data you want available in the UI via message.toolCalls
      },
    };
  },
};

TypeBox 快速参考

架构	用法
Type.String()	字符串
Type.Number()	数字
Type.Boolean()	布尔值
Type.Literal("foo")	精确值
Type.Union([Type.Literal("a"), Type.Literal("b")])	枚举
Type.Array(Type.String())	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} />
))}

---

完成

Agent 现在可以调用 $ARGUMENTS。请在 description 字段中清楚说明工具的功能——Agent 会依靠这段描述来判断何时以及如何调用该工具。