AI エージェントビルダー

このページは DevUtilities の AI エージェントビルダーで LLM エージェントを構築するための正規ガイドです。読みながら上のガイド付きワークフローを使うか、下のトピックへジャンプしてください。Schemas、MCP JSON、プロンプト、トークン数はブラウザ内に留まり、推論のためにアップロードされません。

AI エージェントビルダーは、本番向けエージェント設定を組み立てるクライアント側ワークショップです。OpenAI function calling 用の JSON Schema ツール、Cursor と Claude Desktop 向けの mcpServers 検証、system prompts、合算トークン予算、チーム引き継ぎ用のエクスポート成果物を扱います。

得られるもの

• 4 つのワークフローモード: フルエージェント、function calling のみ、MCP セットアップ、構造化レスポンス
• スターターテンプレート: Filesystem MCP、OpenAI function calling、構造化分類器
• 例 JSON → JSON Schema 推論（任意で厳格な additionalProperties: false）
• JSON-pointer のエラーと警告付きのローカル MCP lint
• プロンプト、minify した tools、MCP JSON を合わせた合算トークン予算
• エクスポート: OpenAI tools JSON、response_format、MCP 設定、markdown 要約、フルバンドル

このビルダーを使う場面

• OpenAI tools JSON が必要で、JSON Schema を手書きしたくないとき
• Cursor や Claude Desktop の MCP サーバーを配線し、貼り付け前に lint したいとき
• エージェントの prompt + tools がコンテキストウィンドウに収まることを証明する必要があるとき
• schema → MCP → prompt → export をつなぐ永続セッションが欲しいとき

単体ツールを優先する場面

• 深いエンコーディング比較やコスト計算だけが必要 → LLM Token Counter
• プロンプトなしの単発 MCP lint だけが必要 → MCP Validator
• サンプルからのスキーマ推論だけが必要 → Structured Output Generator

ツールを定義する前にモードを選んでください。モードは無関係なステップを隠し、空のパネルと戦わないようにします。

フルエージェント向けの初回ウォークスルーです。テンプレートのショートカットはこれらのステップの一部を飛ばします。

1. フルエージェントを選ぶ（または OpenAI function calling テンプレートを読み込む）。
2. ツール定義で、明確な名前・説明・代表的な例 JSON 引数を付けて各ツールを追加する。
3. 推論された JSON Schema を確認し、OpenAI structured outputs / strict tool calling 向けに厳格モードを有効にする。
4. エージェントが Cursor または Claude Desktop 内で動く場合は mcpServers JSON を貼る／編集し、続行前にすべてのエラーを直す。
5. どのツールをいつ呼び、何を決して捏造しないかをモデルに伝える system instructions を書く。
6. トークン予算を開き、cl100k_base または o200k_base を選び、合算がモデルに収まることを確認する。
7. API 用に OpenAI tools JSON、デスクトップクライアント用に MCP 設定、チーム用に markdown 要約をエクスポートする。
8. 任意でフルバンドル JSON をエクスポートし、別のエンジニアが後で同じセッション状態を再読み込みできるようにする。

課題: OpenAI function calling で天気と注文を照会できるカスタマーサポートエージェントが必要だが、手書き JSON Schema が厳格検証に失敗し続ける。

このツールでの解決方法

1. Function calling モードを選ぶか、OpenAI function calling テンプレート（天気 + 注文照会）を読み込む。
2. 本番で必要なフィールドが少なくとも一度は出るよう例 JSON を編集する — 欠けたキーは required プロパティにならない。
3. 厳格モードを有効にし、すべてのオブジェクトが additionalProperties: false を出すようにする。
4. system prompt を締める: 注文 ID を確認し、ツール結果を捏造せず、返信を簡潔に保つ。
5. GPT-4o にデプロイする場合は o200k_base でトークン予算を確認する。
6. OpenAI tools JSON をエクスポートし、Chat Completions または Responses API クライアントに貼る。

成果: 厳格で API 対応の tools 配列と、スキーマに一致するプロンプト — 別のスキーマエディタは不要。

課題: Cursor または Claude Desktop が mcp.json を拒否する、あるいは filesystem サーバーが誤ったディレクトリで起動しディスクを見すぎる。

このツールでの解決方法

1. MCP セットアップモードを選ぶか、Filesystem MCP テンプレートを読み込む。
2. /path/to/allowed/dir を、エージェントが触ってよい唯一のディレクトリへの絶対パスに置き換える。
3. 検証を実行し、欠けた command/args、無効な URL、文字列でない env 値を直す。
4. ブラウザで lint する間はプレースホルダー env 値（本番シークレットではない）を使う。
5. 検証済み mcpServers JSON を Cursor または Claude Desktop の設定にエクスポートする。
6. 破壊的なファイル操作の前に確認を求める system instructions を追加する。

成果: lint 済み MCP クライアント設定と、デスクトップアプリ再起動前にサーバー能力と一致するプロンプト。

課題: モデルに感情・信頼度・トピック・短い要約を JSON で返してほしい — 自由形式の回答は下流パーサーを壊す。

このツールでの解決方法

1. 構造化レスポンスモードを選ぶか、構造化分類器テンプレートを読み込む。
2. パイプラインが期待する正確な形に合わせて例 JSON を編集する。
3. 厳格モードを有効にし、未宣言キーを検証時に拒否する。
4. JSON オブジェクト外の散文を禁じる system prompt を書く。
5. OpenAI structured outputs 向けに response_format json_schema をエクスポートする。
6. 分類する入力ドキュメント用の余裕がトークン予算に残っているか確認する。

成果: 対応する指示付きで structured-output API にそのまま入れられる単一の出力スキーマ。

課題: ツールを 3 つと長い MCP 設定を追加したあと、チャット履歴を含めるとエージェントの合算プロンプトが GPT-4o の実用予算に収まらない。

このツールでの解決方法

1. トークン予算ステップを開き、prompt + minify した tools + MCP JSON の合算を確認する。
2. ツール説明を短くし、required スキーマを膨らませる未使用の例フィールドを削除する。
3. 常時オンの system prompt から冗長なポリシー文をオンデマンド取得へ移す。
4. より深いエンコーディング計算だけが必要なら、組み立てたペイロードを LLM Token Counter にコピーする。
5. 履歴と completions 用の余裕が予算に出てから再エクスポートする。

成果: 本番の最初の 400 エラーの後ではなく、ビルダー内で超過を捕捉できる。

例 JSON は厳格な JSON である必要があります。例に存在するキーだけが required プロパティになります。ネストしたオブジェクトと配列はサンプル値から型を推論します。

実務の目安

• モデルが送ってよいすべてのフィールドを含める — 省略は「required ではない」であり、「default 付きの任意」ではない。
• 現実的な enum を文字列サンプルとして使い、明示的な enum 配列が必要ならスキーマを手編集する。
• 厳格モードを有効にし、すべてのオブジェクトに additionalProperties: false を出す — OpenAI structured outputs と strict tool calling に推奨。
• 空配列は弱い item 型を推論する — 代表要素を少なくとも 1 つ追加する。

Stdio サーバーには command と通常は args が必要です。リモートサーバーには有効な http または https の url が必要です。env 値は文字列でなければなりません。エラーはエクスポートの信頼を阻み、警告は手動確認が必要です。

よくあるクライアントエンベロープ

• トップレベルキーは Cursor と Claude Desktop の慣例どおり "mcpServers" である必要がある
• Filesystem サーバーは絶対パスの allow-list を使うべき
• ブラウザ編集中は env プレースホルダーを優先し、本番シークレットはローカルマシンでのみ注入する

トークン数は system prompt、minify したツールスキーマ、MCP JSON を合算します。GPT-4 / Claude 近似には cl100k_base、GPT-4o には o200k_base を選びます。カウントはローカル tiktoken テーブルを使い、API 呼び出しはありません。

• 数値は下限として扱う: チャット履歴とツール結果は実行時にさらに増える
• スキーマやプロンプトを編集するたびに再確認する
• 境界マップやカスタムペイロードの月次コストカードが必要なら LLM Token Counter を使う

症状: OpenAI が tools ペイロードを拒否する、またはアプリが実際に必要とする引数をモデルが渡せない。

なぜ起きるか

厳格スキーマは未宣言キーを拒否します。例 JSON でフィールドを省略するとプロパティになりません。厳格モードがオフでも、OpenAI structured-output の制限で開いたオブジェクトが拒否されることがあります。

診断

推論スキーマの properties とアプリが送る引数を比較します。OpenAI structured outputs を狙うときは厳格モードが有効か確認します。

修正

1. 欠けたキーを例 JSON に追加してスキーマを再生成する。
2. ネストしたオブジェクト全体で additionalProperties: false が一貫するよう厳格モードを有効にする。
3. OpenAI の structured output 制限に従い、深い oneOf や特殊な型など未サポート構成を短くする。
4. tools JSON を再エクスポートし、既知の正しい引数ペイロードで再テストする。

症状: command/url の検証エラー、クライアントがサーバーを起動できない、リモートトランスポートが接続しない。

なぜ起きるか

command のない stdio、http(s) URL のないリモート、数値の env、誤ったトップレベルキーはクライアントパーサーを壊します。

診断

各 lint エラーの JSON pointer を読みます。エンベロープが mcpServers を使い、各サーバーが stdio（command）かリモート（url）のどちらかで、壊れたハイブリッドでないことを確認します。

修正

1. stdio サーバーに command と args を追加し、すべての env 値を文字列として引用する。
2. リモート MCP トランスポートには http:// または https:// URL を使う。
3. トップレベルキー名を mcpServers に直す。
4. エラーがなくなるまで再検証し、出荷前に警告を整理する。

症状: エクスポート JSON、git diff、ビルダーのスクリーンショットに API キーが現れる。

なぜ起きるか

MCP の env ブロックはプレーン JSON です。本番シークレットをブラウザツール（ローカルでも）に貼ると、クリップボード・画面共有・誤コミット経由の漏洩リスクが上がります。

診断

エクスポートと MCP パネルで sk-、Bearer、ベンダーキーパターンを検索します。コミットされた設定にプレースホルダーだけがあることを確認します。

修正

1. ビルダー内でシークレットを ${ENV_VAR} 形式のプレースホルダーに置き換える。
2. 実値はローカルデスクトップクライアントまたはデプロイのシークレットストアでのみ注入する。
3. チャット、チケット、共有画面に貼ったキーはローテーションする。
4. mcp.json とエージェントバンドル向けの pre-commit シークレットスキャンを追加する。

このワークスペースは設定をアップロードしません — ただしクリップボードと git は漏洩し得ます。

• MCP env ブロックに API キーをコミットしない — 環境変数プレースホルダーを使う
• Filesystem MCP サーバーには最小権限の絶対パスを使う
• 本番プロンプトに大きな few-shot 例を足す前にトークン予算を見直す
• 予期しないキーを tools が受け付けないよう厳格スキーマを優先する
• 内部ツール名やインフラホストを含むエクスポートバンドルは機密として扱う

• テンプレートから始め、不要なツールを削除する — 小さいスキーマは安く安全
• system prompt の指示と一致する明確な動詞でツールを命名する（lookup_order、get_weather）
• 単一の正本を保つ: 分岐したスキーマコピーを維持せず、このビルダーからエクスポートする
• パスや command を変えるたびに MCP を再検証する
• markdown エクスポートにトークン予算を書き、PR でコスト影響をレビューできるようにする
• 深いエンコーディング差分には LLM Token Counter、組み立て済みエージェントにはこのビルダーを使う