Harness Agent

Harness Agent は、Microsoft Agent Framework の harness (create_harness_agent())上に構築された、ソフトウェアエンジニアリング向けの自律 エージェントです: 永続 Todo リスト、Plan/Execute モード管理、ファイル ベースのセッションメモリ、jail されたファイルアクセス、Agent Skills、 シェル実行、ホステッド Web 検索、コンテキスト圧縮、そして 「Todo が終わるまで続ける」ループ -- これらが 1 つのファクトリ呼び出しの背後に 組み立てられます。

Harness Agent は Declarative Agent(kind: Prompt)と Declarative Workflow(kind: Workflow)に続く 第 3 の宣言型 kind です: 同じ DECLARATIVE_AGENTS_DIR フォルダに置く kind: Harness YAML。原則も同じです: YAML は仕様であり、すべての入力は ChatWalaʻau が所有します -- モデルクライアント、資格情報、ツール、ワークスペース ディレクトリ、スキルは常に ChatWalaʻau が解決し、ファイルからは決して取りません。

できること

• タスクリストで働くエージェント。 harness は計画を立て、Todo を管理し、 plan と execute モードを切り替え、execute モードの間は Todo が完了するまで自身を 再起動します(上限 10 イテレーション)。進み具合は回答内のタスク表示で確認できます (v0.162.0)。

• 本物のワークスペース。 CODING_WORKSPACE_DIR を設定すると、jail 付きのファイル ツールとシェルが使えます。どちらも会話のプロジェクトフォルダ （選ばなければワークスペースのルート）から動きます。ターンをまたいで持続する ファイルメモリ(agent-file-memory/)も使えます。未設定なら、これらの機能は そもそも存在しません。

• プロジェクト規約。 projectRules: {enabled: true} にすると、コーディング エージェントと同じように、プロジェクトフォルダの AGENTS.md と CLAUDE.md に 従います（v0.208.0）。

• 承認の手順はありません。 ファイル書き込み、シェルコマンド、スキルスクリプトは、 エージェントが呼び出した時点で実行されます(v0.160.0)。エージェントが触れられる範囲は 持っているツールで決まります。CODING_WORKSPACE_DIR を設定しなければシェルとファイル ツールはなく、File write tools をオフにすれば読み取り専用になります。

• GUI で構成可能。 他のエージェントと同じ管理モーダル(HARNESS タグ付き)で 作成・編集できます。フルスクリーンエディタは、指示文と構成ブロックスイッチの フォームパネル、モデル・ツール・有効ブロックを表示するキャンバス、正準 YAML の ライブプレビューで構成されます。

• チャットの run-target として実行。 モーダルで有効化すると次のメッセージが harness agent で実行されます -- コンポーザーには Harness: <name> が表示されます (YAML がモデルと推論努力度を固定します)。Harness と Workflow の選択は排他で、 通常エージェントを有効化すると両方クリアされます。

• 推論努力度は詳細画面、または YAML で設定します。

  model:
    id: gpt-6-astra
    options:
      effort: medium   # low | medium | high | xhigh | max（既定 xhigh）

  v0.165.0 より前は、Harness はプロバイダの素の既定で動作し、推論設定を一切 送っていませんでした。

最小の Harness Agent

kind: Harness
name: repo-fixer
displayName: Repo Fixer
model:
  id: gpt-5.3            # カタログ offering を 1 つだけ
instructions:
  agent: |
    このリポジトリに集中してください。小さく検証可能な変更を優先します。
tools:
  - function:weather_get_current   # 任意: 組み込みツール / MCP サーバー全体
  - skill:pptx                     # 任意: 特定スキルに絞る (v0.166.0)
mode:
  initial: execute       # plan | execute
  planApproval: skip     # skip(既定) | ask
loop:
  maxIterations: 10      # 上限 10

DECLARATIVE_AGENTS_DIR に置く(または GUI で作成する)と管理モーダルに表示され ます。ファイルの誤り -- 未知のモデル、未知のツール、範囲外のバジェット -- は ブロッキング警告になります: エージェントは一覧に表示されますが、修正するまで 選択できません。

ChatWalaʻau が決めること

項目	ポリシー
チャット履歴	会話ごと。ターンのたびに保存され、再起動後に復元される（v0.207.0、下記参照）
Todo / ループ	常に有効; execute モードで Todo が残る限りループ、最大 10 イテレーション(v0.162.0)
ファイル / シェル	CODING_WORKSPACE_DIR 配下のみ; どちらも会話のプロジェクトフォルダから動く（v0.208.0）; 承認なし(v0.160.0)
プロジェクト規約	YAML の projectRules: {enabled: true} か、エディタの Project rules (AGENTS.md / CLAUDE.md) スイッチを ON にしない限り無効（v0.208.0、後述）
スキル	SKILLS_DIR から、チャットと同じローダー経由でロード -- Skills モーダルの選択・スクリプト実行・対応拡張子がすべて適用されます（v0.141.0）。v0.166.0 以降は、エディタ キャンバスの Add tools → Skills から選択するか tools: に skill:<name> を書いて、このエージェントを特定のスキルに絞り込めます。1 つも選ばない場合は従来どおり有効なスキルをすべて継承します
Web 検索	既定で有効、ただしモデルごとの capability gate に従う
Computer Use	エージェントに Computer Use のツールを追加すると使えます（Windows・ローカルのバックエンドのみ）。モデルごとの制御やスクリーンショットの扱いはチャットと同じ（v0.170.0）
CodeAct	App Settings > CodeAct が ON の間、計算用サンドボックス execute_code が使えます。モデルごとの機能の制御に従います。エージェント単位で外すには codeAct: {disabled: true} か、エディタの CodeAct (compute sandbox) スイッチを使います（v0.172.0）
コンテキスト圧縮	既定で有効。offering の context_window を基準に自動調整(YAML で狭められる)
トークンバジェット	offering の context_window から(YAML で狭められる)
資格情報 / プロバイダ	常に ChatWalaʻau のもの -- YAML からは読まない

Harness Agent は現時点で SPA 限定です: OpenAI 互換 API と Teams は引き続き アクティブな通常エージェントに従います。デモモードでは表示のみ(読み取り専用) です。

Plan 承認

Plan / Execute mode が有効な Harness Agent は、まず計画を立てます。依頼を分析し、Todo リストを書き、必要な不明点があれば質問します。その後の動作は選択できます(v0.162.0)。

Plan approval	計画の後、エージェントは
Skip(既定)	計画を簡潔に示し、自分で execute モードに切り替えて進める
Ask	承認を求めて待つ。「はい」と返す(または修正を依頼する)と続行する

エディタの「Plan / Execute mode」の下にある Plan approval で設定するか、YAML に書きます。

mode:
  planApproval: ask      # skip にする場合は省略

不明点の質問はどちらの設定でも行われます。skip で省かれるのは、最後の「始めてよいですか？」 という質問だけです。エディタは Ask を選んだときだけ planApproval を書き込むため、既定の まま保存したエージェントは以前のバージョンでも読み込めます。

注記

v0.162.0 より前は、エージェントは必ず承認を求め、Todo が残っているため自動ループが 「Continue working on the task」とユーザーの代わりに答えていました。現在ループは execute モードでのみ動くため、計画中にエージェントが尋ねた質問は必ずユーザーの回答を待ちます。

実行を追う: タスク表示

Harness のターンが Todo リストに沿って作業すると、回答内の本文の上に小さな表示が出ます (v0.162.0)。

[list] Tasks 3/7 done   [loop] auto-continue 2/10   execute          [Tasks]

部分	意味
Tasks n/m done	全 Todo のうち完了した数
auto-continue i/N	自動継続の何回目か(上限は loop.maxIterations)
plan / execute	エージェントの現在の mode
最後の行(ターン終了後)	終わった理由: すべて完了、回答待ち、未完了のまま上限で停止、停止

Tasks で一覧全体を開きます。作業中は随時更新され、終わったターンではそのターン終了時点の タスクを表示します。表示はメッセージとともに保存されるため、チャットを開き直しても残ります。

ループがモデルに送る内部メッセージ -- Progress so far: ... と Continue working on the task. If it is complete, say so. -- は回答には含まれません。 その情報はこの表示で確認できます。単純な追加の質問には、以前の完了済みリストは表示されません。

実行はどこまで続くか

送信したメッセージ 1 つが、エージェントの 1 回の実行 です。その実行の中で harness は execute モードで Todo が残っている間、最大 10 ループ(loop.maxIterations、上限 10)続き、各ループでは ツール呼び出しを含めて最大 40 往復 のモデル呼び出しができます。これが予算のすべてで、 それ以外に実行を止めるものも、延ばすものもありません。

Todo が残ったまま上限に達した実行も、通常の回答と同じように終わります。もう一度メッセージを 送れば(「続けて」 で十分です)、会話は履歴を保持しているため、エージェントは Todo リストの続きから再開します。

注記

v0.160.0 より前は、書き込みやシェルコマンドのたびに承認で一時停止し、一時停止ごとに新しい 実行が始まっていたため、長いタスクは承認ラウンドの設定(AUTONOMOUS_LOOP_NO_PROGRESS_ROUNDS、 AUTONOMOUS_LOOP_MAX_ROUNDS)で区切られていました。承認の手順がなくなったため、これらの 設定はもう存在しません。.env に残っている場合、サーバーは起動時に警告を出し、値は 無視されます。

Tool Activity の読み方

Harness Agent は多数の小さなツールを呼び出して作業します。呼び出しはすべてアシスタント メッセージの下に表示され、実際の動作がそのまま読めます。

表示	エージェントが行ったこと
Listed workspace files / Read workspace file / Wrote workspace file	CODING_WORKSPACE_DIR 配下の jail 化されたファイルアクセス。"Read workspace file" には、ファイルの一部の行だけを読む操作も含まれます(v0.161.0)
Searched workspace content	ワークスペース内の grep
Saved to agent memory / Read agent memory	自身のファイルメモリストア(agent-file-memory)の操作
Added a task / Completed a task / Checked remaining tasks	Todo リストの更新(継続ループを駆動する)
Switched agent mode / Checked agent mode	plan と execute の切り替え
Ran command	ワークスペースでのシェルコマンド実行。出力はプレーンテキストで、色コードは取り除かれます(v0.162.0)
Ran skill script	Agent Skill に属するスクリプトの実行（CODING_ENABLED=true が必要）

存在しない名前での Ran skill script -- v0.162.0 で修正

以前のバージョンでは、作り出された名前（script_name: "noop" や skill_name: "none"）で Ran skill script が実行され、「not found」のエラーが 1 ターンに何度も繰り返されることが ありました。フレームワークが、どのスキルもスクリプトを持たない場合でもスクリプト実行ツールを 提供していたため、モデルが名前を作り出していました。v0.162.0 からは、表示対象のスキルに実際に スクリプトがあるときだけツールが提供されます。スクリプトを持つスキルは従来どおり動作します。

注記

v0.134.0 より前は、これらすべてが MCP: <name> と表示されていました。挙動の違いでは なく表示の誤りです。いずれも MCP 呼び出しではありません。現在 MCP: は、設定済みの MCP サーバに実際に由来するツールにのみ表示されます。

プロジェクトフォルダとプロジェクト規約

v0.208.0 から、Harness の会話はそれぞれ ワークスペース内の 1 つのフォルダ で作業します。 Harness エージェントが実行対象のとき、チャット画面の入力欄にフォルダのアイコンが表示され、 ツールチップに今のフォルダが出ます（Project folder: projects/shop）。クリックすると Project folder ダイアログが開きます:

• ワークスペースを 1 階層ずつ辿り、Use this folder を押す
• New folder で、今いる場所に新しいプロジェクト用のフォルダを作る
• Use workspace root を押すか、最近使った 5 つのフォルダから選ぶ
• AGENTS.md や CLAUDE.md があるフォルダにはバッジが付く

エージェントのファイルツールとシェルは、どちらもこのフォルダから動きます。File Explorer に 表示される場所と同じです。フォルダは会話に属します。チャットと一緒に保存され、開き直すと 再表示されます。新しいチャットはワークスペースのルートから始まります。メッセージの合間なら フォルダを切り替えられ、エージェントは履歴・Todo・モードを保ったまま、新しいフォルダを 知らされます。フォルダはワークスペース内に存在している必要があります。リンクやジャンクションを 経由するパスと、エージェント自身の agent-file-memory フォルダはエラーで拒否されます。

AGENTS.md / CLAUDE.md に従わせる

プロジェクト規約はエージェントごとに、YAML かエディタのスイッチで有効にします:

projectRules:
  enabled: true      # 既定は false

有効にすると、エージェントは 毎ターンの開始時 にプロジェクトフォルダの AGENTS.md と CLAUDE.md を読み、プロジェクトの規約（ビルド・テスト・整形の方法、構成、触ってはいけない もの）として従います:

ルール	動き
両方のファイルがある	両方を適用し、AGENTS.md が先。同じ内容の CLAUDE.md や、@AGENTS.md とだけ書いた CLAUDE.md は 1 回だけ数える
@docs/style.md の行	フォルダ内のその .md ファイルの内容に置き換える。1 階層だけで、コードブロックの中は対象外
エージェントが書いた規約ファイル	次のメッセージから効く
サイズ	1 ファイル 64 KiB まで、合計 32,000 文字まで。切り詰めた箇所は本文に印が付く
読まないもの	サブフォルダや親フォルダのファイル、リンク経由のファイル、バイナリファイル

規約は ChatWalaʻau 自身の規則より 下 に置かれ、安全のための規則、ツールの制限、あなたの 指示を変えることはできません。そのターンで何が適用されたかはタスク表示に出ます （Project: projects/shop · Rules: AGENTS.md, CLAUDE.md）。ログにはファイル名とサイズだけが 記録され、本文は記録されません。

規約は信頼できるフォルダでだけ有効にしてください

clone したリポジトリの AGENTS.md は他人が書いた文章で、Harness のシェルは承認なしで 動きます。中身を確認していないコードを扱うエージェントでは projectRules を OFF のままに してください。

v0.207.0 以前からの更新

以前は、Harness のファイルツールは agent-file-access/ から、シェルはワークスペースの ルートから動いていました。今はどちらもプロジェクトフォルダから動きます。以前に書いた ファイルは agent-file-access/ に残っています。従来の配置が必要な会話では、そのフォルダを プロジェクトフォルダに選んでください。

再起動してもエージェントの状態は残る

v0.207.0 から、サーバーを再起動しても harness の会話は止まったところから続きます。 各ターンの終わり（完了・失敗・停止のいずれでも）に、エージェントの作業状態がチャットの 隣の .sessions/<チャット id>.harness/<harness id>.json に保存されます。中身は、履歴 （コンテキスト圧縮で畳んだ分も含む）、todo リスト、モード、ループの状態です。再起動後の 次のターンで読み戻されます。

以前のバージョンで保存された会話は、更新後もそのまま使えます。v0.210.0 より前に Claude の ホスト型 Web 検索を使っていた場合、その検索はソースのリンク付きの短いメモとしてモデルに渡されます。 保存された会話は変更されません。

再起動しなくてもエージェントが組み立て直される場面でも同じです。MCP サーバーの保存、 モデルカタログの再読み込み、Skills の変更、そしてしばらく使わないうちに他の多くの harness チャットにメモリから押し出された場合です。v0.207.0 より前は、これらのたびに 開いている harness の会話がすべて最初からになっていました。

この後に	エージェントが引き継ぐもの
サーバーの再起動、MCP / カタログ / Skills の変更	すべて（履歴、todo、モード）
harness の YAML の編集	履歴だけ。todo とモードは YAML の初期値から
モデルも切り替える編集	前のモデルの推論を除いた履歴

保存された状態はチャットに属します。チャットを削除すると消え、アーカイブするとチャットと 一緒に .archived/ へ移り、一時チャットではチャットと一緒に期限切れになります。 エクスポートには含まれません。 インポートしたチャットや分岐したチャットは、新しい エージェントのセッションで始まります。ファイルが読めない場合（ダウングレードの後など）は *.corrupt-<時刻>.json に改名して最初から始めます。チャット自体には影響しません。ファイルは 隣のチャットファイルと同じく、ツールの出力を平文で保持します。

メッセージを編集するとエージェントは最初からやり直す

harness エージェントは会話が続くあいだ作業状態を保持します -- 履歴、todo リスト、 そして現在のモードです。

メッセージを編集または削除すると、そのすべてがリセットされます。 会話の削除も 同じです。ここでの「戻ってやり直す」とはそういう意味で、エージェントは今あなたが 残した状態の会話から始め、何も引き継ぎません。

操作	エージェントの挙動
過去のメッセージを編集	やり直し。履歴・todo・モードがクリアされる
メッセージを削除	同上
会話を削除	同上。保存された状態も削除され、シェルプロセスも解放される
通常の追加送信	これまでどおり、すべてを保持する

注記

v0.137.0 より前は、表示されているメッセージだけが削除され、エージェントは過去の 実行すべての記憶を保持し続けていました。実行が途中で中断されていた場合、その残骸に よって後続のリクエストが不正になり、モデルプロバイダから No tool output found for function call ... として拒否されることがありました。 巻き戻しがそれを消すようになりました。

部分的なリセットはありません。エージェントの内部メッセージは、表示されている メッセージと一対一で対応していないため、巻き戻す先の地点が存在しないからです。

長く使う todo リストを残したい場合は、過去のメッセージを編集する前に完了させるか 書き直してください。メッセージの編集や削除では保存された状態も消えるため、その後に 再起動しても古い状態は戻りません。

コンテキスト圧縮

Harness Agent はチャットを開いている間、会話をメモリ上に保持し続けます。ツールを 多用するセッションでは、これはすぐに大きくなります。コンテキスト圧縮はこれを自動的に 抑えます。モデルの入力バジェットに対して2段階で動作します。

到達点	動作
50%	古いツール結果を要約にまとめる(直近のものはそのまま残る)
80%	最も古いやり取りを削除する

v0.161.0 から、要約にはエージェントの発言だけでなく、実行した手順(どのツールを、 どの引数で呼び、何が返ってきたか)も記録されます。そのため長い実行でも、済ませた作業を 見失いにくくなります。その分、要約は少し大きくなります。

設定は不要です。バジェットは Model Offering の context_window から取得され、出力 許容量は既定で 32,768 トークン(小さいモデルでは自動的に縮小)です。理由がある場合 のみ上書きしてください。

compaction:
  maxContextWindowTokens: 200000   # 既定: offering の context_window
  maxOutputTokens: 16384           # 既定: 32768(窓の 1/8 が上限)

値を省略することは「既定値を使う」という意味であり、圧縮を無効化するもので はありません。実際に無効化するには次のようにします。

compaction:
  disabled: true

管理モーダルのエージェント詳細パネルには、実行時に実際に使われるバジェットが表示 されるので、推測ではなく確認できます。

注記

v0.133.0 より前は、maxOutputTokens を省略すると圧縮が黙って無効化される一方で、 どの画面も「有効」と表示していました。以前のバージョンで作成した Harness Agent も 自動的に修正されます。YAML の変更は不要です。

注記

v0.138.0 より前は、長い会話がターンの途中で、ツールを数個実行したところで No tool call found for shell call output with call_id ... のようなプロバイダー エラーで失敗することがありました。エージェント内部の履歴に同じツール呼び出しの 複製が蓄積し、圧縮がツール呼び出しとその結果を一緒に保てなくなるためで、 片方だけが畳まれてリクエストが不正になっていました。現在は履歴からその重複が 取り除かれます。入力した内容には影響しません — 同じメッセージを 2 回送れば 2 回記録されます。