BluePeriod Docs
開発

ツールアーキテクチャ概要

ツールアーキテクチャ概要

BluePeriodのAIエージェント(内製・MCP)で使用されるツールの定義場所と構造を説明します。


1. ツールの二層構造

BluePeriodのツールは、役割に応じて2つの場所に定義されています:

next-app/src/
├── ai/agents/tools/          # エージェント汎用ツール(インフラ)
└── lib/features/*/tools.ts   # Feature層ツール(ビジネスロジック)

2. エージェント汎用ツール (ai/agents/tools/)

役割: エージェントのインフラストラクチャに関わる機能。Feature層には属さない汎用的な機能。

ツールファイルツール名説明
currentTimeTool.tscurrent_time現在時刻の取得
finishTaskTool.tsfinish_taskタスクの完了通知
memoryTools.tslist_memory_dates, read_memories_by_date長期メモリへのアクセス
openUrlTool.tsopen_urlURLを開いてコンテンツ取得
recordThoughtTool.tsrecord_thought短い思考・内省の記録(スキーマは thought のみ)
reportProgressTool.tsreport_progress進捗報告
webSearchTool.tsweb_searchWeb検索
responseTool.tsresponseユーザーへのメイン回答送信
planTool.tsplan_task実行計画(ロードマップ)の提示

計9ツール

これらはFeature(プロジェクト・執筆等)とは無関係な、エージェント自体の動作に必要な機能です。

: 2026-03-28に responseTool.tsplanTool.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_aditAdit形式(JSONパッチ)の編集適用
blueperiod_apply_manuscript_delimiterSEARCH/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_aditAdit形式(JSONパッチ)の編集適用
blueperiod_apply_artifact_delimiterSEARCH/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層ツールを追加する場合

  1. 対応するFeatureディレクトリの tools.ts にツール定義を追加
  2. 必要に応じてService層に関数を追加
  3. lib/features/editorial/tools/index.ts に統合(必要な場合)

7.2. エージェント汎用ツールを追加する場合

  1. ai/agents/tools/ に新しいツールファイルを作成
  2. ai/agents/assistantGraph.ts でインポートして使用

関連ドキュメント:

On this page