create-client-tool

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

$ARGUMENTS という名前の新しい AtlasTool をスキャフォールディングし、アプリに組み込みます。

背景

クライアントツールを使うと、Atlas Agent はブラウザー上で実行されるロジックを呼び出せます。たとえば、グラフの描画、ローカル状態の照会、UI パネルの表示、ナビゲーションの実行などです。ツールを呼び出すタイミングはエージェントが判断し、アプリが実行して結果を返します。

処理の流れは次のとおりです。

1. エージェントが clientTool アクションを含む応答を返します
2. ライブラリが TypeBox スキーマに対して引数を検証します
3. ブラウザーで execute() が実行され、{ output, details } を返します
4. output（文字列）がツールの結果としてエージェントに返されます
5. details（任意の形式）は、UI が描画できるよう message.toolCalls から利用できます

---

ステップ 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 を追加してください。エージェントはこれを使って、渡す値を判断します。

---

ステップ 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} />
))}

---

完了

これで、エージェントが $ARGUMENTS を呼び出せるようになりました。description フィールドには、ツールの機能を明確に記述してください。エージェントはその文字列を頼りに、ツールを呼び出すタイミングと方法を判断します。