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/)が使えます。未設定なら、これらの機能は そもそも存在しません。

• 承認の手順はありません。 ファイル書き込み、シェルコマンド、スキルスクリプトは、 エージェントが呼び出した時点で実行されます(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 が決めること

項目	ポリシー
チャット履歴	会話ごとの in-memory(再起動でリセット)
Todo / ループ	常に有効; execute モードで Todo が残る限りループ、最大 10 イテレーション(v0.162.0)
ファイル / シェル	CODING_WORKSPACE_DIR 配下のみ; 承認なし(v0.160.0)
スキル	SKILLS_DIR から、チャットと同じローダー経由でロード -- Skills モーダルの選択・スクリプト実行・対応拡張子がすべて適用されます（v0.141.0）。v0.166.0 以降は、エディタ キャンバスの Add tools → Skills から選択するか tools: に skill:<name> を書いて、このエージェントを特定のスキルに絞り込めます。1 つも選ばない場合は従来どおり有効なスキルをすべて継承します
Web 検索	既定で有効、ただしモデルごとの capability gate に従う
コンテキスト圧縮	既定で有効。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 サーバに実際に由来するツールにのみ表示されます。

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

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 回記録されます。