Create Client Tool

Create a Client Tool

Scaffold an AtlasTool named $ARGUMENTS. If the app has no approved in-app useAtlasChat, implement a Fusion action via integrate-fusion-agent instead.

Prerequisite: vendored src/atlas-agent/ and @sinclair/typebox from integrate-atlas-chat.

Background

Client tools let the Atlas Agent invoke browser-side logic — charts, local state, UI panels, navigation. The agent decides when to call; the app executes and returns a result.

1. Agent responds with a clientTool action
2. TypeBox validates the arguments
3. execute() runs in the browser and returns { output, details }
4. output (string) is sent back to the agent
5. details is available on message.toolCalls for the UI to render

Step 1 — Understand the codebase

Before writing anything, read:

• The file where useAtlasChat is called (often src/App.tsx or a chat hook) to find where tools is passed — imports are typically from ./atlas-agent/react after integrate-atlas-chat
• Any existing tool definitions to match the file/naming conventions

Step 2 — Define the tool

Use Type from @sinclair/typebox for the parameters schema (compile-time types + runtime validation).

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      },    };  },};

Adjust the ./atlas-agent/... path if the tool file is not directly under src/ next to the atlas-agent folder (for example ../atlas-agent/types from src/tools/).

TypeBox quick reference

Always add a description on the tool and on each parameter — the agent uses those strings.

Step 3 — Wire into useAtlasChat

Find the useAtlasChat call and add the tool to the tools array:

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

Step 4 — Render tool results (if needed)

If the tool returns structured details, render them in the message list. message.toolCalls is a ToolCall[] — one entry per tool call (client-side and server-side) in call order.

{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} />))}