Claude API で
AIエージェントをつくる仕組み
まず前提：Claude Messages API の基本機能はこれだけ
messages[]（会話）と tools（使える道具）を送ると、返事が返るステートレスなAPI。
(ステートフルなClaude Managed Agents APIもあるが今回は省略)
なのでClaude Code のようなCLIエージェントが内部でやることを、ブラウザ側に実装する必要がある。
① ループ
+
② 文脈保持
+
③ ツール / スキル
+
④ 分析(JS)実行
仕組み 1 / 4
① ループをどう実装しているか
「返事の stop_reason を見て、ツールを実行してまた送る」を繰り返すだけ。
for (let i = 0; i < 30; i++) { // 上限つきループ
const res = await callClaude({ messages, tools });
if (res.stop_reason === "tool_use") { // ツールを使ってと言われた
const out = runTool(res); // ← フロントで実行
messages.push(assistantTurn(res), toolResult(out));
continue; // 結果を添えてもう一度
}
return res; // end_turn = 完成
}
Claudeに送る
→
tool_use?
→
ツール実行
→
結果を添えて再送
↺
end_turn で完了
ツールが失敗してもエラーを結果として返す＝モデルが直して再挑戦できる（止めない）。
仕組み 2 / 4
② コンテキストをどう保持しているか
前提：APIは会話を覚えていない（ステートレス）
毎回のリクエストは独立。
過去のやり取りは自分で送り直さないと消える。
対策：messages 配列を自前で持ち、毎ターン丸ごと送り直す
ConversationStore が messages を localStorage に保存
肥大対策：古い結果は compaction でプレースホルダ化し、大量データは履歴に載せず別ストアへ。
仕組み 3 / 4
③ ツール呼び出しの仕組み
ツール＝エージェントが実行できること。Claudeは実行せず、「この名前のツールを、この入力で使って」と返す。
定義（スキーマ）
名前・説明・入力形式を
Claude APIへ送る
↔
ToolRegistry
同じツール名で
定義と実装を管理
↔
実装（関数）
ブラウザが実際に
e-Stat操作などを実行
toolRegistry.execute(call.name, call.input)
Claudeが返したツール名から対応する関数を探し、入力を渡して実行。結果を tool_result としてClaudeへ返す。
仕組み 3 / 4
③ スキルの仕組み
スキル＝ツールの上手な使い方。分野ごとの手順知識・判断基準を、システムプロンプトと一緒に system フィールドへ入れる。
システムプロンプト
+
e-Stat API
スキル
→
system
毎回のAPIリクエスト
→
Claudeの
判断を誘導
何を教えるか
AIの役割(ロール)やこのアプリケーションの目的、やってはいけないことなど。
e-Stat APIの使い方／統計表の選び方／効率的な取得手順／単位・出典の示し方。
毎回送るが、キャッシュする
cache_control: ephemeral を指定。変わらない tools → system を初回に保存し、以後はキャッシュから読む。
既定TTLは5分。初回はキャッシュ書き込み、エージェントループ中の2回目以降は入力コストと処理時間を抑えられる。
仕組み 4 / 4
④ 分析のために、エージェントにJavaScriptを実行させる
用意されている集計関数で足りない分析は、エージェントが分析用のJavaScriptコードを生成して実行する。
ただし生成コードをそのまま動かすのは危険なので隔離して走らせる。
エージェントが
analyze() を生成
→
使い捨て
Web Worker
→
データを渡して
実行
→
結果(数値)だけ
会話へ返す
隔離のしかた
毎回新しい Web Worker を生成し、データだけ渡して実行。完了／失敗／タイムアウトで即破棄。
渡さない・させない
workerにAPIキー・DOM・localStorage アクセスさせない。生成されたコードにヤバそうな関数実行(fetchなど)が含まれてないか実行前にチェック
