agent-harness

エージェントハーネス — エージェントに何を伝えるか、そして他者がエージェントに伝えた内容を監査する方法

agent-orchestrator はループをつなぎます。agent-evals はその動作を検証します。agent-interop は他のプロセスとの通信を可能にします。このスキルは、これらとモデルの間にある層、つまりプロンプト、ツール、手法の選択を扱います。 ハーネスエンジニアリングには、指示だけでなくコンテキスト管理も含まれます。その効果はタスク、モデル、評価によって異なり、ベンチマークでの向上だけでは普遍的な改善が立証されたことにはなりません。

これは両方向で機能します。構築と監査は、同じチェックリストを順方向と逆方向に読むだけなので、ここでは一緒に扱っています。

---

トリガー

「ツールの説明」、「エージェントが無限ループする」、「プロンプトエンジニアリング」、「ハーネスエンジニアリング」、「ReAct ループ」、「react パターン」、「静的か動的か」、「エージェントを組み込む」、「エージェント SDK」、「Pi ハーネス」、「встроить агента」。

0.31.3 の説明から移動した項目：「エージェントが間違ったツールを選ぶ」、「агент не вызывает тул」、「このエージェントを監査して」。

ルール 0 — まずプロンプトを確認する（例外を伴う診断上のヒューリスティック）

ツール選択や使用に関する失敗では、アーキテクチャを追加する前に指示と説明を確認します。Anthropic のツールに関するガイダンス （2026-10-09 に確認）は、説明の変更を評価することを支持していますが、欠陥のうちどれだけが説明に起因するかを測定した割合ではありません。これは診断の順序を示すものであり、結論を決めるものではありません。例外となるのは、プロンプトでは対処できない問題です。 決定論的な競合状態、ハードコードされたシークレット、誤った操作に設定されたタイムアウトなど、ソースレベルの不変条件違反はコードのバグであり、表現を変えても解決しません。

リトライ、ルーター、サブエージェントを追加する前に、次の順番で確認してください。

1. ツールの説明には、機能だけでなく、いつ使うかも書かれていますか？
2. システムプロンプトには、用語が明記されていますか？ ステータスを追跡するよう指示されたエージェントは、許可された値が列挙されていないと、同じ実行中に pending、to-do、done、completed を独自に使い分けます。
3. エージェントは今日の日付を把握していますか？ 学習のカットオフがあるモデルは、現在の日付が与えられないと検索せず、記憶から回答します。
4. 指示は、厳格にすべきでないところで柔軟になっていますか？ 「最も適切だと思う順序でツールを使ってください」 は、タスクを学習している段階では適切ですが、本番環境では不適切です。そこで 「各タスクについて必ずウェブ検索を実行してください」 と明記すれば、手順の抜けを防げます。

その後で初めて、アーキテクチャを検討してください。最初からアーキテクチャに頼ると、プロンプトの欠陥が恒久的な構造コストになります。

---

ワークフローかエージェントか — 何よりも先に決める

エージェントは、自らの処理を動的に制御します。ワークフローは、あらかじめ定義されたコードパスに従います。選択の基準は高度さではなく、手順の数を事前に把握できるかどうかです。

ワークフローを構築する場合	エージェントを構築する場合
要件が明確で安定している	タスクが自由度の高い探索的なものである
予測可能性と明示的な制御が重要である	予測可能性より柔軟性が重要である
デバッグとコスト管理を優先する	変数をまたいだ適応的な推論が必要である
すべての手順を今すぐ列挙できる	手順数が予測できず、ハードコードできない

機能する最もシンプルな方法から始め、そこで止めてください。 エージェントを使うと、遅延とコストが増えるだけでなく、ワークフローにはない種類の失敗も加わります。つまり、エージェント自身の判断を信頼することが必要になります。固定された手順では本当に記述できない場合にのみ、そのコストを負担してください。

自律性に頼る前に検討する、5つのワークフローパターン

パターン	形	選ぶ場面
プロンプトチェーン	逐次的に呼び出し、直前の出力を次に使い、その間にプログラムによるチェックを挟みます	タスクを固定の手順に分解できる場合 — 概要を作成してから下書きを作り、下書きを作成してから翻訳する
ルーティング	入力を分類し、専門の処理先に送ります	カテゴリーが明確に分かれており、それぞれに専用のプロンプトが必要な場合
並列化	分割（独立したサブタスクを同時に実行）または投票（同じタスクをN回実行）	サブタスクが独立している場合、または信頼度の判断に複数のサンプルが必要な場合
オーケストレーター・ワーカー	中央のモデルがタスクを分解して委任し、その後に統合します	サブタスクを事前に定義できない場合 — ここがルーティングとの正直な境界です
評価・最適化	あるモデルが生成し、別のモデルが批評するループです	明確な評価基準があり、反復による改善を測定できる場合

オーケストレーター・ワーカーとルーティングの違いは、よく誤解されています。 ルーティングは既知の選択肢から選びます。オーケストレーションは、リクエストごとに選択肢を作り出します。分岐を列挙できるなら、必要なのはルーティングであり、その方が低コストです。

静的か動的か — 2つ目の問いであり、先ほどの問いとは別です

ワークフローを選んでも、まだ決まっていないことがあります。実行前に、その形は分かっていますか？ 静的なグラフでは、すべてのノードとエッジが事前に決まっています。動的なグラフでは、ノードが自身の出力を読み取り、次の処理を決めながら拡張されます。

常にまずは静的に — 動的にするのは、静的な方式が具体的に説明できる壁にぶつかってからにしてください。動的な方式はより強力ですが、制御がはるかに難しいためです。ただし、監査可能性と静的な構造は同じ軸ではありません — これは、事前に描いた計画と、実行後に保存された実行グラフを混同しています。実行記録が完全であれば、実行は監査可能です。つまり、実際に実行されたすべてのノード、エッジ、イベント、有効だったポリシーのバージョン、そして出所情報を伴う決定論的な上限（予算／深さ／ノード数の上限）が記録されています。静的グラフが優先されるのは、通常、実行時の形が描かれた形と一致するからです。動的グラフも、こうした上限の範囲内で記録を保持すれば監査可能です。どちらの方式でも、設計図だけでは証拠になりません — *「こう計画した」は、「実際にこうなった」*ことを意味しません。

6行の表、その他のモデル — 偽のエッジのテスト、ダイヤモンド、合流前のチェッカーノード —、そしてホストが分岐時に実際に実行する処理については、次のドキュメントにまとめています。agent-orchestrator/references/graph-engineering.md。判断表が2か所にあると互いに食い違うため、ここでは繰り返しません。

リファレンス

各ファイルの冒頭には、それぞれ独自の 読み込むタイミング と改訂日時が記載されています。この資料は更新されるため、このパックのリポジトリバリデーターは、参照ファイルにいつ読んだかが記載されていないとビルドを失敗させます。

ファイル	読むタイミング
references/context-lifecycle.md	古いコンテキスト、取得したメモの矛盾、またはリサーチをスキルの指針に昇格させる場合 — 最新の参照先、アーカイブの境界、情報源の採用基準
references/instruction-budget.md	指示ファイルが上限を超えた場合、内容が重複する場合、または要件を失わずに分割する必要がある場合。明示的な入力を測定するスクリプトを含みます
references/system-prompt.md	プロンプトを作成または修正する場合 — 抽象度、構成、語彙、動的コンテキスト、推論モデルで変わる点
references/tools.md	モデルが誤ったツールを選ぶ、またはツールを選ばない場合 — エージェントとコンピューターのインターフェース：ツールの数、命名方法、説明方法、返す内容
references/techniques.md	ReAct、reflection、voting、planningなどから選ぶ場合 — 各項目には、ベンチマークスコアではなく、本番環境向けの評価が記載されています
references/workbench-contracts.md	既存のエージェントを囲むハーネスを組み立てる場合 — インストールの所有権、範囲を限定したフック、引き継ぎ、成果物に紐づく証拠と観察の限界、選択的なECC手法
references/layers.md	ハーネスが担う範囲を決める場合 — カーネル、ワークベンチ、プロダクトの各レイヤー、および権限境界が通常は他者の責任となる理由
references/audit.md	自分が構築していないエージェントシステムをレビューする場合 — 7つのトラック、証拠の階層、優先順位付きの計画
references/pi.md	上記の原則を実装例で確認したい場合 — Piのセッション、圧縮、設定、スキル、信頼、コンテナ化。それぞれが実装するルールと、意図的に異なる点を対応付けています
references/pi-sdk.md	ハーネスを組み込みまたは拡張する場合 — SDK、RPCプロトコル、JSONモード、および権限ゲート、コンテキストの書き換え、コストフックを実際に配置できる8つの拡張ポイント

scripts/audit_agent.py — 監査の機械的な部分です。意図を理解せずに検出できるもの（無制限のループ、説明のないツール、握りつぶされたツールエラー、ハードコードされたモデル、タイムアウトの欠如）を見つけ、検出できない項目の一覧を出力します。そのため、何も出力されなかったことを合格と解釈してはいけません。

指示の整理に関する注意点： @file を性急にインポートしても、テキストの配置が変わるだけで、実行時のコンテキストコストは削減されません。重要なルールは読み込んだままにし、任意の詳細は明示的なタスク条件のもとに配置し、ファイルサイズの測定とは別に、ホストで新たに読み込んだ状態を検証してください（references/instruction-budget.md）。

エージェントシステムの監査 — 簡易版

詳しい説明は references/audit.md にあります。概要は次のとおりです。

1. まずスキャナーを実行します。 低コストで実行でき、見落としの一覧から、監査の残りを手作業でどこまで確認する必要があるかが分かります。
2. 7つの観点 — プロンプト、ツール、制御フロー、コンテキスト、障害、権限、証拠 — を順に確認し、観察結果を添えられる場合に限って所見を記録します。
3. すべての推奨事項に確度を付けます。 根拠が、この環境での測定、上流のドキュメント、判断のいずれなのかを示します。
4. スコアではなく、優先順位を付けた計画を出します。 数字だけでは、月曜日に何を変更すればよいか誰にも分かりません。これは、agent-evals が評価基準に、seo-aeo-audit がサイトに適用するのと同じルールです。

多くの監査で最初に明らかになる所見： システムに評価がありません。これは、信頼性が不明であるという所見です。つまり、これより下流にあるあらゆる動作の推定は反証不能であり、この監査の推定も例外ではありません。ただし、ソースで証明できることまで無効になるわけではありません。二重請求の実証、ハードコードされたシークレット、決定論的な競合状態には、それぞれ独自の所見と、具体的な被害に基づく優先順位があります。一般的な「評価がない」という問題で、具体的に立証された被害を覆い隠してはなりません。

---

対象範囲

agent-orchestrator との境界。 このスキルは、ループの配管処理（反復ガード、トリミング、サブエージェントのディスパッチ、プロバイダーのルーティング、メモリレイヤー、チェックポイント）を担当します。このスキルが担当するのは、モデルに伝える内容です。両者が接するのは4つの境界で、それぞれの内容は一方にのみ記載されています。

1. モデルが適切なツールを選べるようにツールを説明することは、このスキルの references/tools.md が担当します。能力フラグに基づいて、リクエストごとにツールのリストを組み立てることは、オーケストレーターの §3 が担当し、文言についてはこのスキルを参照します。
2. プロンプトに何を書くか — 抽象度、語彙、列挙されたステータス — は、このスキルの references/system-prompt.md が担当します。リクエストごとにツールと同じ処理でプロンプトを再構築することは、オーケストレーターの §10 が担当します。
3. 作業の構造 — 静的／動的の表、フェイクエッジテスト、収束前のチェッカー — は、必ず1か所だけに記載します。それはこのスキルではありません。 agent-orchestrator/references/graph-engineering.md が該当します。このスキルの静的／動的のセクションは判断までにとどめ、モデルの詳細についてはそこを参照します。
4. コンテキストウィンドウ： agent-orchestrator/references/context-engineering.md では、ウィンドウがいっぱいになったときに何を削除するかというコンパクションを扱います。一方、このスキルの system-prompt.md では、そもそも何を入れるかを扱います。満たす処理と空ける処理、それぞれ別のファイルです。

agent-evals との境界。 そのスキルは、実行記録からエージェントの動作を測定します。このスキルは、ソースとプロンプトから、エージェントがどのように構築されたかをレビューします。評価がないと分かった監査は、このスキルに引き継ぎます。同じ観点で評価スイートが失敗し続ける場合は、このスキルに差し戻します。

agent-interop との境界。 MCP、A2A、レジストリ、ゲートウェイなど、プロセス間の通信経路を扱います。ツールの説明はこちら、ツールのプロトコルはあちらです。

対象外： モデルの選定と価格（Anthropic のものについては claude-api スキルを参照）、再販時のウォレット（agent-orchestrator/references/llm-proxy-billing.md）、および RAG の検索品質です。RAG の検索品質は検索の問題であり、このスキルではプロンプトに入る部分のみを扱います。

チェックリスト — リリースに値するハーネス

• カーネルまたはワークベンチのハーネスを明示し、インストール済み・読み込み済み・強制適用される機能を区別している
• ワークフローとエージェントのどちらにするかを慎重に決め、よりシンプルな選択肢も実際に試している
• 静的か動的かも決めている — 予測可能性を優先して静的にし、監査可能である必要のある実行では、静的な形状だけでなく完全な実行記録を保持している
• システムプロンプトの抽象度が適切 — ヒューリスティックを使い、ハードコードされた分岐にも、漠然とした期待にも頼っていない
• エージェントが出力すべきすべてのステータス、カテゴリ、列挙値をプロンプト内で列挙している
• 今日の日付や、その他の変化しやすいコンテキストを、推測に頼らず注入している
• ツール：影響力の大きいものを少数に絞り、名前空間を付け、新しい同僚に説明するようにそれぞれを説明している
• ツールの応答には識別子ではなく意味を含め、デフォルトでページ分割または切り詰めている
• ツールのエラーはスタックトレースを繰り返すのではなく、次の試行に役立つ情報を伝える
• 論文に載っていたからという理由ではなく、問題ごとに理由を持って手法を一つ選んでいる
• サブエージェントはトランスクリプトではなく、要点をまとめたサマリーを返す
• エージェントを観測できる：どのツールを、どの引数で使い、何を観測し、トークンをいくつ消費したか
• 実装の前にオブザーバブルを、プロンプトの調整前に評価を用意する。そうしなければ調整は経験則にとどまり、本番環境まで待つのはコーパスだけ