CMO AI Pro Developers
リサーチツール
参考資料とリサーチ本文を扱う7つのツールの仕様です。
最終更新日：2026年10月16日
参考資料の保存、リサーチ本文の読み書き、参考資料の範囲指定読み取り、分類別の事実追加、事実リサーチの実行に使う7つのツールです。
エージェントが集めた情報をCMO AI Proへ蓄積し、その後の戦略仮説生成やバナー制作の材料にできます。 保存した内容は、画面から手動で作成したものと同じ扱いになります。
save_material
参考資料を案件へ保存します。入力の種類によって挙動が変わります。
input_type: "text": 本文をそのまま保存します。即座に利用可能な状態になり、クレジットを消費しませんinput_type: "url": URLを登録し、文字起こし処理を開始します。30クレジットを消費します
パラメータ
| パラメータ | 型 | 必須 | 既定値 | 制約 |
|---|---|---|---|---|
project_id | 文字列 | 必須 | — | UUID |
input_type | 文字列 | 必須 | — | text または url |
title | 文字列 | 任意 | — | 200文字以内。text では必須、url では省略時にホスト名を使用 |
content | 文字列 | 任意 | — | 120,000文字以内。text では必須 |
source_url | 文字列 | 任意 | — | URL形式。url では必須 |
idempotency_key | 文字列 | 必須 | — | 1〜128文字 |
応答
text の場合:
| フィールド | 内容 |
|---|---|
materialId | 保存された参考資料のID |
url の場合:
| フィールド | 内容 |
|---|---|
materialId | 保存された参考資料のID |
jobId | 文字起こしジョブのID |
status | queued |
エラー
| code | 発生条件 |
|---|---|
validation_error | text でタイトルまたは本文が空、url でURLが空 |
payment_required | クレジット不足、または日次上限（url のみ） |
conflict | 同じ処理が実行中 |
not_found | 案件が存在しない、または組織外 |
list_materials
案件の参考資料を、作成日時の新しい順で取得します。本文は既定では含みません。
パラメータ
| パラメータ | 型 | 必須 | 既定値 | 制約 |
|---|---|---|---|---|
project_id | 文字列 | 必須 | — | UUID |
include_content | 真偽値 | 任意 | false | true で本文を含める |
応答
| フィールド | 内容 |
|---|---|
materials[].id | 参考資料ID |
materials[].title | タイトル |
materials[].input_type | text または url |
materials[].source_url | 元のURL（url の場合） |
materials[].origin | 保存元。user（手動追加）または research（リサーチ収集） |
materials[].source_role | 出典の役割。リサーチ収集の場合の分類（例: review、media） |
materials[].status | 状態。ready が利用可能 |
materials[].error_message | 失敗時のメッセージ |
materials[].created_at | 作成日時 |
materials[].updated_at | 更新日時 |
materials[].content | 本文（include_content が true のときのみ） |
URLの参考資料は、登録直後は draft で、文字起こしが終わると ready になります。
materials[].title と、include_content: true のときの materials[].content は外部由来として untrusted.fields に申告されます。
get_material
案件の参考資料を1件ずつ、指定した範囲だけ読みます。大きな資料を一度に返さず、next_offset を次の offset に指定して続きへ進みます。クレジットは消費しません。
パラメータ
| パラメータ | 型 | 必須 | 既定値 | 制約 |
|---|---|---|---|---|
project_id | 文字列 | 必須 | — | UUID |
material_id | 文字列 | 必須 | — | UUID |
offset | 整数 | 任意 | 0 | 0以上 |
max_chars | 整数 | 任意 | 20000 | 1〜20,000文字 |
応答
| フィールド | 内容 |
|---|---|
title | 参考資料の題名 |
content | 指定範囲の本文 |
totalChars | 本文全体の字数 |
next_offset | 続きがある場合の次のoffset。無ければ null |
題名と本文は外部由来として untrusted.fields に申告されます。案件と資料が別組織の場合は not_found になります。
get_research_document
案件のリサーチ本文と更新日時を取得します。追記の前に必ず実行してください。 updatedAt を append_research_document の expected_updated_at に渡します。
パラメータ
| パラメータ | 型 | 必須 | 既定値 | 制約 |
|---|---|---|---|---|
project_id | 文字列 | 必須 | — | UUID |
応答
| フィールド | 内容 |
|---|---|
id | リサーチ本文のID（未作成の場合は含まれません） |
contentMd | 本文（Markdown）。未作成の場合は空文字 |
lastGeneratedAt | 最後にAI生成した日時 |
updatedAt | 更新日時。未作成の場合は null |
contentMd は外部由来として untrusted.fields に申告されます。
append_research_document
現在のリサーチ本文を残したまま、末尾へ追記します。上書きはしません。 競合を防ぐため、直前に取得した更新日時の指定が必須です。
パラメータ
| パラメータ | 型 | 必須 | 既定値 | 制約 |
|---|---|---|---|---|
project_id | 文字列 | 必須 | — | UUID |
content_md | 文字列 | 必須 | — | 1〜50,000文字 |
expected_updated_at | 文字列またはnull | 必須 | — | ISO 8601。本文が未作成なら null |
idempotency_key | 文字列 | 必須 | — | 1〜128文字 |
応答
| フィールド | 内容 |
|---|---|
researchDocument | 追記後のリサーチ本文（本文・直前の本文・更新日時を含む） |
エラー
| code | 発生条件 |
|---|---|
conflict | 指定した更新日時が現在の値と一致しない（他の更新が入った） |
validation_error | 本文が空、または文字数超過 |
not_found | 案件が存在しない、または組織外 |
conflict が返った場合は、get_research_document で最新を読み直し、内容を確認してから やり直してください。
add_research_facts
分類を指定した事実を、既存の事実リサーチ本文の分類見出しへ追加します。同じ事実は重ねず、標準形でない本文では追加節へ入れます。0クレジットです。本文全体は返しません。
パラメータ
| パラメータ | 型 | 必須 | 既定値 | 制約 |
|---|---|---|---|---|
project_id | 文字列 | 必須 | — | UUID |
facts | オブジェクト配列 | 必須 | — | 1〜30件。category は特徴／メリット／実績／権威性／オファー、claim は1〜200文字、detail は1〜500文字 |
source_label | 文字列 | 必須 | — | 1〜100文字。案件内資料の出典名 |
expected_updated_at | 文字列またはnull | 必須 | — | ISO 8601。本文が未作成なら null |
idempotency_key | 文字列 | 必須 | — | 1〜128文字 |
応答
mode（分類の中へ差し込んだら merged、本文が標準形でなく末尾の追加節に入れたら appended、事実リサーチがまだ無く新しく作ったら created）、addedCount、addedByCategory、updatedAt を返します。入力した事実の本文や出典ラベルは返しません。
start_fact_research
事実リサーチまたは追加リサーチを開始します。完了は待ちません。
mode: "generate"（事実リサーチ）: リサーチ本文をゼロから作ります。既にリサーチ本文がある場合は実行できませんmode: "append"（追加リサーチ）: 既存の本文に追記します。先に事実リサーチが必要です
パラメータ
| パラメータ | 型 | 必須 | 既定値 | 制約 |
|---|---|---|---|---|
project_id | 文字列 | 必須 | — | UUID |
mode | 文字列 | 任意 | generate | generate または append |
additional_instruction | 文字列 | 任意 | 空文字 | 4,000文字以内 |
expected_updated_at | 文字列またはnull | 任意 | — | ISO 8601 |
idempotency_key | 文字列 | 必須 | — | 1〜128文字 |
応答
| フィールド | 内容 |
|---|---|
jobId | ジョブID |
reused | true なら既存ジョブを再利用（新規消費なし） |
status | queued |
エラー
| code | 発生条件 |
|---|---|
conflict | 既存本文があるのに generate、本文がないのに append、更新日時の不一致 |
payment_required | クレジット不足、または日次上限 |
validation_error | 入力が要件を満たしていない |
not_found | 案件が存在しない、または組織外 |
消費
事実リサーチ・追加リサーチともに400クレジットです。詳しくは クレジット消費を参照してください。