システムプロンプトの組み立て

エージェントの harness は、役割、ツールの使い方、実行環境、スキル一覧などからシステム指示を組み立てます。ツール定義と会話の文脈も別に準備します。ディスクにファイルがあっても、その本文が要求に入るとは限りません。

MEMORY.md にある情報をエージェントが見落としたなら、まず実際に送ったかを確認してください。本例のファイルには非公開プレビューの URL がありますが、初期設定はメモリ読み込みが Off なので送りません。

資料の目次に題名を書いても、本文を添付したことにはなりません。受け手が得るのは組み立てた資料だけです。スキル一覧と未読のメモリにも同じ違いがあります。

組み立ての仕組み

harness はモデルを囲むアプリケーションです。要求前に資料を選び、モデル API のフィールドへ配置します。この小さな決定的 harness は 3 つのフィールドを使います。

system は Identity、Tool guidance、Runtime、User preferences の 4 節を常に持ちます。各見出しと本文をこの順に空行でつなぎます。スキルを有効にすると Available skills が 5 節目になります。

役割は助手の仕事、ツール指示は編集提案前のファイル読み取り、環境は Workspace: /demo/docs、設定は Use concise English. を提供します。1 文書へまとめても、各出所の境界は残します。

ツールの使い方は通常の文章ですが、ツール定義は別構造です。Read は path、Edit は path、old_text、new_text を受け取ります。定義を付けるだけではファイル操作を行いません。実行はツール呼び出しループの役割です。

配置はランタイムによって異なります。Agent SDK のカスタマイズガイド はシステム指示への追加と会話経由のプロジェクト文脈を区別します。本例はスキル本文とメモリをラベル付きメッセージブロックへ置きます。すべての製品の規則ではありません。

システムプロンプト組み立てのステップ

初期タスクは「このプロジェクトの非公開プレビューはどこか」です。スキルは Loaded、メモリは Off。両方の元ファイルは存在します。

1. 基本 4 節を作る。 役割、ツール指示、作業場所、ユーザー設定を 1 ステップずつ system へ写します。URL は含まれません。
2. スキル一覧を追加。 docs-check: Review documentation changes. が 5 節目に入ります。用途の説明で、スキル指示ではありません。
3. 有効化を確認して本文を読む。 Loaded は、明示的な選択で読み込みが求められた状態です。skills/docs-check/SKILL.md の Check every relative link in the changed page. を文脈ブロックへ写します。元ファイルも残ります。
4. メモリ読み込みを確認し、省く。 MEMORY.md の本文は Private preview: https://preview-cedar.example ですが、Off なので要求へ入りません。ファイルを削除したわけではありません。
5. 要求を完成。 5 節の system と 2 ツール定義を確定し、ユーザーメッセージへスキル指示とタスクの 2 ブロックを入れます。
6. ペイロードを調べる。 スキル部分には relative link が見つかりますが、要求全体に https://preview-cedar.example はありません。モデル応答前で再生が終わります。

構造は完成しても、問われた非公開の事実が欠けています。Load memory を On にすると、その事実がメッセージへ加わります。対応する Off の実行と比べ、system と tools はバイト単位で同じです。

一覧の説明と読み込んだ指示

Disabled は一覧項目も本文も省きます。Listed は system に説明だけを入れます。Loaded は同じ説明に加え、本文をメッセージ文脈へ写します。Listed から Loaded へ変えると作業方法の指示が増えますが、system は 5 節のままです。

これは段階的開示です。発見用メタデータを先に提供し、選択後に詳細を読みます。Agent Skills の統合ガイド もこの分離とユーザーの明示的な有効化を扱います。本例は選択済みから始め、モデルのスキル選択は模擬しません。

メモリは独立しています。Listed + On では URL はあるがスキル指示はなく、Loaded + Off では指示はあるが URL がありません。「ファイルを持っている」だけでは、要求内容を説明できません。

各行はさらに 2 ツール定義と 1 タスクブロックを持ちます。構造の個数であり、トークン数ではありません。

デバッグでは元ファイルと完成要求の両方を調べ、欠けた指示や事実がどのフィールドにあるか検索します。両本文を読むと URL は messages[0].content[1]、つまり最初のメッセージの 2 番目のブロックです。メモリだけなら messages[0].content[0]、Off ならどこにもありません。正しいファイルでも、内容を含めなければ今回の要求の根拠にはなりません。文脈とメモリでは、その後の要約や次セッションへの持ち越しを扱います。

境界条件

• 任意本文を読み込まない。 基本指示、ツール定義、タスクは残ります。欠けた文脈を捏造しません。
• スキル無効。 Available skills 節全体を省き、空本文で利用不能なスキルを宣伝しません。
• 一覧だけ存在。 Listed の正常な状態です。名前が見つかっても本文を読んだ証拠にはなりません。
• メモリファイルはあるが Off。 ファイルは残り、URL は要求にありません。モデルが推測、質問、ファイル読み取りのどれを選ぶかは予測しません。
• 両本文を読み込む。 ユーザーメッセージはスキル、メモリ、タスクの 3 ブロックです。情報の提供は正しい利用を保証しません。

よくある間違い

• 入力全体をシステムプロンプトと呼ぶ。 system、tools、messages はアプリケーションから見える別フィールドです。提供者内部でまとめても、この区別は残ります。ツール利用文書も参照してください。
• 一覧を完全な指示と読む。 短い説明には本文の相対リンク検査の指示がなく、役割が違います。
• 追加順を権限順位と読む。 番号は追加位置で、競合解決規則ではありません。後の文字列が自動的に勝つわけではありません。
• ファイルの存在をモデルの知識と読む。 ディスク、一覧、要求への存在は別です。欠落を調べるなら最後を確認します。
• 読み込んだ文を信頼済み、遵守済みとする。 読み込みは利用可能性だけを示します。信頼、優先順位、モデルの動作は別問題です。

モデルの簡略化

固定のメモリ内ソースと小さな組み立て器を使い、モデル応答はありません。エージェントシステムの正式な訓練の代わりではありません。節順、明示的な有効化、文脈の配置は例の選択です。実ランタイムは権限、指示優先順位、信頼できない内容、トークン化、キャッシュ、文脈上限、提供者別形式も扱います。非公開システムプロンプトの再現や、モデル挙動・トークン費用の測定はしていません。