create-client-tool

クライアントツールを作成する

$ARGUMENTS という名前の AtlasTool をスキャフォールドします。アプリに承認済みのアプリ内 useAtlasChat がない場合は、代わりに integrate-fusion-agent を使って Fusion アクションを実装します。

前提条件： integrate-atlas-chat によって、src/atlas-agent/ と @sinclair/typebox がベンダー化されていること。

背景

クライアントツールを使うと、Atlas Agent はチャート、ローカル状態、UI パネル、ナビゲーションなどのブラウザー側のロジックを呼び出せます。呼び出すタイミングはエージェントが判断し、アプリが実行して結果を返します。

1. エージェントが clientTool アクションで応答します
2. TypeBox が引数を検証します
3. execute() がブラウザー内で実行され、{ output, details } を返します
4. output（文字列）がエージェントに返されます
5. details は UI のレンダリング用に message.toolCalls から利用できます

---

ステップ 1 — コードベースを把握する

何かを記述する前に、次を読みます。

• useAtlasChat の呼び出し箇所（多くの場合、src/App.tsx またはチャットフック）を確認して、tools が渡される場所を特定します。integrate-atlas-chat の実行後は、通常 ./atlas-agent/react からインポートされます
• 既存のツール定義を確認し、ファイルや命名の規約に合わせます

---

ステップ 2 — ツールを定義する

パラメータースキーマには、コンパイル時の型付けと実行時の検証に対応する @sinclair/typebox の Type を使います。

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 クイックリファレンス

スキーマ	用途
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 を追加します。エージェントはこれらの文字列を使用します。

---

ステップ 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[] で、呼び出し順に、クライアント側とサーバー側の各ツール呼び出しに対して 1 つずつエントリーがあります。

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