create-client-tool

用途

create-client-tool 用于为 Atlas 智能体创建客户端工具（AtlasTool）。根据资料，只要需要为 Atlas agent 创建 AtlasTool，就必须使用该技能，不应手动编写 AtlasTool 定义，也不应手动将其接入 useAtlasChat。

背景与运行流程

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

整体流程为：

Agent 以 clientTool action 作出响应。
库根据 TypeBox schema 校验参数。
execute() 在浏览器中运行并返回 { output, details }。
output（字符串）作为工具结果发送回 agent。
details（任意结构）可在 message.toolCalls 上供 UI 渲染。

使用方式

第 1 步：理解代码库

在编写任何内容之前，先阅读：

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

第 2 步：定义工具

将工具创建为带类型的常量。使用来自 @cognite/dune-industrial-components/atlas-agent 的 Type 定义参数 schema，从而同时获得编译期类型与运行时校验。

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 快速参考：

Schema	用途
Type.String()	string
Type.Number()	number
Type.Boolean()	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 依赖该字符串决定何时以及如何调用该工具。

适用场景

适用于需要让 Atlas Agent 调用浏览器端逻辑的场景，例如渲染图表、查询本地状态、显示 UI 面板、触发导航等。

限制

资料未提供关于收费、价格、平台支持范围、效果保证等方面的信息。