ツールアーキテクチャ概要
ツールアーキテクチャ概要
BluePeriodのAIエージェント(内製・MCP)で使用されるツールの定義場所と構造を説明します。
1. ツールの二層構造
BluePeriodのツールは、役割に応じて2つの場所に定義されています:
next-app/src/
├── ai/agents/tools/ # エージェント汎用ツール(インフラ)
└── lib/features/*/tools.ts # Feature層ツール(ビジネスロジック)2. エージェント汎用ツール (ai/agents/tools/)
役割: エージェントのインフラストラクチャに関わる機能。Feature層には属さない汎用的な機能。
| ツールファイル | ツール名 | 説明 |
|---|---|---|
currentTimeTool.ts | current_time | 現在時刻の取得 |
finishTaskTool.ts | finish_task | タスクの完了通知 |
memoryTools.ts | list_memory_dates, read_memories_by_date | 長期メモリへのアクセス |
openUrlTool.ts | open_url | URLを開いてコンテンツ取得 |
recordThoughtTool.ts | record_thought | 短い思考・内省の記録(スキーマは thought のみ) |
reportProgressTool.ts | report_progress | 進捗報告 |
webSearchTool.ts | web_search | Web検索 |
responseTool.ts | response | ユーザーへのメイン回答送信 |
planTool.ts | plan_task | 実行計画(ロードマップ)の提示 |
計9ツール
これらはFeature(プロジェクト・執筆等)とは無関係な、エージェント自体の動作に必要な機能です。
注: 2026-03-28に
responseTool.tsとplanTool.tsを新設し、recordThoughtTool.tsのスキーマを簡略化した。詳細は 2026-03-29_1600_report_agent-graph-refactoring を参照。
3. Feature層ツール (lib/features/*/tools.ts)
役割: BluePeriodの機能(プロジェクト、執筆、キャラクター等)に関わるツール。
3.1. Projects (lib/features/projects/tools.ts)
| ツール名 | 説明 |
|---|---|
blueperiod_list_projects | 全プロジェクトの一覧 |
blueperiod_get_project | プロジェクトデータ取得(軽量版) |
blueperiod_get_metadata | メタデータのみ取得 |
blueperiod_get_outline | プロット構造のツリー表示 |
blueperiod_create_project | 新規プロジェクト作成 |
blueperiod_update_project_metadata | メタデータ更新 |
blueperiod_delete_project | プロジェクト削除 |
blueperiod_get_plot_translations | プロット翻訳データ取得 |
blueperiod_list_writing_prompts | 執筆プロンプト一覧 |
計9ツール
3.2. Editorial - Plot (lib/features/editorial/tools/plot-tools.ts)
| ツール名 | 説明 |
|---|---|
blueperiod_get_raw_plot | プロット構造のJSON取得 |
blueperiod_get_plot_context | 特定項目のコンテキスト取得 |
parse_plot_to_structure | テキスト→プロログ構造変換 |
refine_plot_item | プロット項目のAIブラッシュアップ |
blueperiod_add_plot_structure | プロット項目の追加 |
blueperiod_edit_plot_item | プロット項目の編集 |
blueperiod_delete_plot_item | プロット項目の削除 |
計7ツール
3.3. Editorial - Manuscript (lib/features/editorial/tools/manuscript-tools.ts)
| ツール名 | 説明 |
|---|---|
blueperiod_get_raw_manuscript | 原稿テキスト取得 |
generate_manuscript | 原稿生成(AI) |
rewrite_manuscript | 原稿リライト(AI) |
blueperiod_apply_manuscript_adit | Adit形式(JSONパッチ)の編集適用 |
blueperiod_apply_manuscript_delimiter | SEARCH/REPLACEブロック形式の編集適用 |
blueperiod_overwrite_manuscript | 原稿の完全上書き |
計6ツール
3.4. Characters (lib/features/characters/tools.ts)
| ツール名 | 説明 |
|---|---|
blueperiod_list_characters | 全キャラクター一覧 |
blueperiod_get_character | キャラクター取得 |
blueperiod_create_character | キャラクター作成 |
blueperiod_update_character | キャラクター更新 |
blueperiod_delete_character | キャラクター削除 |
計5ツール
3.5. System (lib/features/system/tools.ts)
| ツール名 | 説明 |
|---|---|
blueperiod_get_global_store | グローバルストア取得 |
blueperiod_set_global_store | グローバルストア設定 |
計2ツール
3.6. Prompts (lib/features/prompts/asset-tools.ts)
| ツール名 | 説明 |
|---|---|
blueperiod_list_prompt_assets | プロンプト資産一覧 |
blueperiod_get_prompt_asset | プロンプト資産取得 |
blueperiod_create_prompt_asset | プロンプト資産作成 |
blueperiod_update_prompt_asset | プロンプト資産更新 |
blueperiod_delete_prompt_asset | プロンプト資産削除 |
計5ツール
3.7. Chat - Artifacts (lib/features/chat/artifact-tools.ts)
| ツール名 | 説明 |
|---|---|
blueperiod_list_artifacts | アーティファクト一覧 |
blueperiod_create_artifact | アーティファクト作成 |
blueperiod_get_artifact | アーティファクトの全文取得 |
blueperiod_update_artifact | アーティファクトのメタデータ更新 |
blueperiod_delete_artifact | アーティファクト削除 |
blueperiod_apply_artifact_adit | Adit形式(JSONパッチ)の編集適用 |
blueperiod_apply_artifact_delimiter | SEARCH/REPLACEブロック形式の編集適用 |
blueperiod_toggle_artifact | アーティファクトの有効/無効切替 |
計8ツール
4. 統合方法
4.1. Feature層ツールの統合
lib/features/editorial/tools/index.ts で全てのFeature層ツールが統合されます:
export const createEditorialTools = (get: Getter, set: Setter, t: TFunction, toastFn: typeof toast) => {
return [
...createPlotTools(get, set, t, toastFn),
...createManuscriptTools(get, set, t, toastFn),
...createCharacterTools(get, set),
...createProjectTools(get, set),
...createPromptAssetTools(get, set),
...createArtifactTools(),
...createSystemTools()
];
};4.2. 内製エージェントでの使用
ai/agents/assistantGraph.ts でエージェント汎用ツールとFeature層ツールが結合されます:
const responseTool = createResponseTool();
const planTool = createPlanTool();
// General Agent用ツールセット(軽量 + artifact_tools)
const generalTools = [
webSearch,
currentTime,
reportProgress,
openUrl,
recordThought,
planTool,
responseTool,
createFinishTaskTool(),
...memoryTools,
...wrappedArtifactTools // artifact操作のみ(執筆ツールは含まない)
];
// Writing Agent用ツールセット(フル + editorial tools)
const writingToolsFull = [
webSearch,
currentTime,
reportProgress,
openUrl,
recordThought,
planTool,
responseTool,
createFinishTaskTool(),
...memoryTools,
...writingTools // editorial/writing tools(執筆ツールを含む)
];注: ツールセットは用途別に分割されています。
generalToolsは artifact 操作を含むが執筆ツールは含まず、writingToolsFullはartifact操作や執筆ツールを含むフルセットです。
4.3. MCPブリッジでの使用
server/api/mcp/index.ts でFeature層ツールがMCPサーバーとして公開されます。
5. ツール数の合計
| カテゴリ | ツール数 |
|---|---|
| エージェント汎用 | 9 |
| Feature層(Projects) | 9 |
| Feature層(Plot) | 7 |
| Feature層(Manuscript) | 6 |
| Feature層(Characters) | 5 |
| Feature層(System) | 2 |
| Feature層(Prompts) | 5 |
| Feature層(Artifacts) | 8 |
| 合計 | 51ツール |
6. 命名規則
6.1. blueperiod_ プレフィックス
Feature層ツールはMCPとの互換性のため、全て blueperiod_ プレフィックスを持ちます。
6.2. エージェント汎用ツール
プレフィックスなし(web_search, finish_task 等)
7. 新しいツールの追加方法
7.1. Feature層ツールを追加する場合
- 対応するFeatureディレクトリの
tools.tsにツール定義を追加 - 必要に応じてService層に関数を追加
lib/features/editorial/tools/index.tsに統合(必要な場合)
7.2. エージェント汎用ツールを追加する場合
ai/agents/tools/に新しいツールファイルを作成ai/agents/assistantGraph.tsでインポートして使用
関連ドキュメント:
- 12_ai_agent_architecture - 内製エージェントのアーキテクチャ
- 18_agent_tool_integration_guide - ツール統合ガイド
- 19_mcp_architecture - MCPアーキテクチャ