エージェント行動をコードにマッピングするハンドブック

Agent Harness · Tencent HY LLM Frontier · 2026 年 6 月

エージェント・ハンスの仕組みを可視化し、監査可能にし、編集できるようにする。

オープンソースのエージェント用コードベースを開くと、実際の動作を確認したい、ドキュメントにある通りの安全性が担保されているか検証したい、あるいは自分用のエージェントとして改造したいといったニーズが出てくるでしょう。これらの目的は一見異なりますが、コードの中に入ってみればすべて「振る舞い」に関する具体的な問いに帰着します。

例えば、「ファイル削除前に必ず確認を促すのか？」という問いに対する答えを見つけるには、確認ロジックを探し出し、迂回経路を追跡し、変更を加えた際に影響を受ける実装箇所をすべて特定する必要があります。数千ものファイルが存在するリポジトリで「delete」「permission」「confirm」といったキーワードを検索しても、結果は散発的な断片に過ぎません。それらを組み合わせて完全な振る舞いの連鎖として再構築するのは、非常に手間のかかる作業です。

真の問題はコードが不足していることではなく、振る舞いから実装への道筋が見えないことです。必要なのは新たなコード索引ではありません。両者を結びつける「地図」が必要です。

Harness Handbook は散在する実装を振る舞いレベルのマニュアルとして整理します。システムごとの振る舞いを軸に実行フローを構造化し、各ステップに対応する検証可能なコード根拠を紐付けます。ユーザーは理解したいこと、監査したいこと、変更したいことをそのまま問いかければ、Handbook が関連する振る舞い単位、実装箇所、そして次のアクションを特定して提示します。

ハンスが進化しても、この地図によってシステムの可読性とレビュー可能性は維持され、人間が常にプロセスに関与し続ける仕組みが保たれます。

Ruhan Wang1,2,* · Yucheng Shi1,† ·

Zongxia Li1,3 · Zhongzhi Li1,4 ·

Yue Yu2 · Junyao Yang1,5 ·

Kishan Panaganti1 · Haitao Mi1 ·

Dongruo Zhou2 · Leoweiliang1

1 Tencent HY LLM Frontier · 2 Indiana University ·

3 University of Maryland · 4 University of Georgia ·

5 National University of Singapore

• 連絡先著者：Ruhan Wang (ruhwang@iu.edu)

† プロジェクトの主要協力者

あなたが望む行動

「ファイルを削除する前にユーザーに確認してください」

これは、ユーザーが平易な言葉で表現したものです。

ハンドブック

L1

システム全体の概要

実行フロー

L2

行動単位の概要

関連する行動単位

L3

行動単位の詳細

実装の根拠

実装箇所のコード内での散在

prompts/system.md

tools/wrapper.py

state/manager.py

config/flags.py

telemetry/events.py

memory/store.py

これらは編集作業に入る前に特定された、5 つの散在する場所です。

一つの行動要求は、往々にして複数の実装箇所にまたがります。Harness Handbook は、これらの散在した場所をナビゲート可能な行動パスに再編成し、各ステップを検証可能なコード証拠と紐付けます。これにより、理解、監査、修正のすべてが単一のマップ上で完結します。

一目でわかる概要

• Harness Handbook が解決する課題: ハーネスはエージェントの行動がどのように展開されるかを形作りますが、その行動は往々にして暗黙的であり、複雑なコードの中に埋もれています。Harness Handbook はこれを、ナビゲート可能で検証可能な行動マップとして整理します。

• ハーネスの読み方: ハンドブックでは、まずシステムとしての振る舞いという観点からハーネスがどのように動作するかを解説し、その説明をコード証拠へと結びつけます。これにより、読者はファイルツリーやバラバラなソース断片から始める必要はありません。

コーディングエージェントを用いたハッチの変更は、より信頼性の高いものになります。ハンドブックは自然言語による変更要求を関連する動作単位と実装箇所へマッピングするため、エージェントが不要な検索をスキップし、依存関係の取りこぼしを防ぎ、より精度の高い編集計画を作成できるよう支援します。

既存のハッチ上で独自のエージェントを構築する場合も同様です。ハンドブックはハッチの動作や機能を自然言語で提示することで、ユーザーが低レベルのコードを読み込むことなくシステムの理解と調整を行い、自社のニーズに合わせたエージェントを構築することを可能にします。

Part 01

なぜエージェントハッチには「動作レベル」の手引が必要なのか？

AI エージェントについて語る際、人们はまずモデルの能力から議論しがちです。しかし、エージェントが実際に業務を開始すると、焦点はすぐに「モデルは何ができるか？」から「システムが何を許可するか？」へと移ります。コマンドの実行可否、ファイル削除前のユーザーへの確認要否、エラー発生時の処理方法などは、モデル単体の性能だけでなく、それを囲むハッチの設計によって決定されます。

これらの動作がどのようにして生まれるのかを理解するには、ハッチ（実行環境）そのものを詳しく調べる必要があります。しかし、本番環境で包括的に調査するのは容易ではありません。

例えば Codex は、モデル、ツール、状態、権限、そして実行環境を調整し、ユーザーの各リクエストを実際のアクションのシーケンスに変換します。しかし、関連する実装は2,267 件のファイル、34,000 以上の関数、そして約 160,000 のコード接続点にまたがって分散しています。この規模になると、ファイルツリーを見てもコードがどこにあるかはわかりますが、それらの部品がどう連携して動作を生み出しているかまでは把握できません。

ディレクトリ構成や検索結果だけでは、完全な動作を再構築することはできません。必要なのは、システムを読み解く別のアプローチです。つまり、「動作」から始めて、検証のためにソースコードへと遡る方法です。このアプローチには 3 つの目的があります。

理解（Understand）

ハッチがどのように稼働しているかを確認します。

1 つのリクエストがフルフローを通過する過程を追跡します。モデルに入力される情報、ツールが呼び出されるタイミング、状態がどう移動するか、そしてシステムが失敗にどう対応するかです。

監査（Audit）

実際の動作が期待通りかどうかを検証します。

実行パスをたどって、権限、確認ロジック、サンドボックス化、データフローを確認します。これらの保護措置を迂回する可能性のある異常な経路がないかもチェックします。

適応（Adapt）

自分だけのエージェントを構築します。

まずは、ハレス（Harness）が既に備えている機能と、それに対応する振る舞い・コードを確認しましょう。その後、必要に応じてシステムを拡張または調整します。

すべての目標は、特定の振る舞いから始まり、最終的にその根拠となるコードへと戻ります。ただし難しいのは、振る舞いとコードが 1:1 で対応していない点です。一つの振る舞いは、複数のモジュールに散らばった実装によって決定されることがよくあります。

なぜ一つの振る舞いが多くの場所に散在するのか？

「ファイル削除前にユーザーに確認する」というルールはシンプルに聞こえます。しかし、これがコード上でどのように機能しているかを確認するには、一連の意思決定を追跡する必要があります。モデルが確認を要求したのか、ツール呼び出しを傍受できるのか、ユーザーの選択はどこで記録されるのか、そしてどのような条件下で削除が実際に実行されるのか——その連鎖のどの环节が変わっても、結果は変わってしまいます。

振る舞いの問い

「ファイル削除前にユーザーに確認する。」

harness/
core/loop.py
tools/registry.py
prompts/config/memory/store.py
telemetry/consumers/state_manager.py
wrapper.py
system.md
tags.py
events.py
result_handler.py

• state_manager.py: ユーザーの承認を記録
• wrapper.py: 削除ツールの呼び出しを傍受
• system.md: 削除前に確認するようモデルに指示
• tags.py: 削除操作を「高リスク」と定義
• events.py: 確認結果を記録
• result_handler.py: サンドボックス実行とフォールバック処理を担当

各サイトが果たす役割

一つの動作には、複数の実装場所が存在します。

キーワード検索では、間接的な経路を見逃してしまいます。

「一つの動作には、複数の実装場所が存在します」

「ファイルを削除する前にユーザーに確認を求める」という挙動は、単一の関数によって決定されるものではありません。これは、プロンプト、ツールラッパー、権限設定、状態管理、サンドボックス実行、そしてフォールバックパスなど、複数の要素が共同して形成しています。ハルネス（基盤）を理解し、監査し、修正するためには、まずこれらの実装場所を特定することが不可欠です。

各実装場所は、その連鎖の一部しか制御していません。confirmBeforeDelete() 関数一つで、挙動全体を代表させることはできません。リクエストが実行されるのか、拒否されるのか、あるいは別のフローに入るのかを判断するには、プロンプトからツールラッパー、権限、状態を経て、サンドボックス実行やフォールバックパスまで一貫して追跡する必要があります。

したがって、「本当にファイルを削除する前に確認してくれるのか？」と問うとき、それは単なるキーワード検索ではありません。その決定プロセスの各段階におけるコード証拠を再構築し、挙動の連鎖を復元することになります。私たちはこれを「挙動の局在化（behavior localization）」と呼びます。この連鎖をいかに完全に再構築できるかが、説明の質、リスクレビュー、そして変更の範囲を決定します。

ハルネス・ハンドブックは、コードベースに隠された挙動の連鎖を、レイヤーごとに閲覧可能でソースコードとの照合が可能な「マップ」へと変換するものです。

Part 03

ハルネス・ハンドブック：ナビゲート可能な挙動マップ

ある一つの動作は、実装の複数の場所にまたがる可能性があるため、ハンドブックは単にファイルツリーを再構成するだけでは不十分です。Harness Handbook は、L1、L2、L3 の 3 つのレベルを用いて行動中心の視点からハネス（制御枠組み）を記述し、段階的に問いを絞り込んでいきます。各レベルでは検証可能なコード根拠が必ず保持されるため、読者はそれぞれの解説を確認でき、後続の修正もソースコードに基づいて行うことができます。

システム理解から動作証拠へ

このハンドブックは、3 つのレベルを通じて行動情報を順を追って整理します。

HARNESS REPOSITORY

コード事実を 3 レベル構成のハンドブックに体系化

L1: システム全体概要

出力：システム全体の行動フレームワーク

システム全体を理解するための枠組みを提供

問い：このハネスは全体としてどのように動作するのか？

重点：アーキテクチャ、実行フロー、主要なステージ、状態遷移の流れ。

L2: 行動ユニットの概要

出力：行動ユニットのマッピング

システムの行動ユニットを特定する

問い：どのような行動ユニットが存在し、それらはどう接続されているのか？

重点：各ユニットの責任範囲、入出力、実行順序、重要な状態。

L3

Behavior-Unit Detail

Output → verifiable implementation evidence

Go inside a single behavior unit

Question: How does this behavior unit execute?

Focus on triggers, state changes, exception paths, and evidence.

wrapper.py

manager.py

flags.py

Click a level to focus it — click again to reset.

From system understanding to behavior evidence. L1 establishes an overall view of the harness. L2 organizes the system into behavior units and describes their responsibilities, inputs, outputs, and dependencies. L3 examines a single unit in detail, connecting triggers, state changes, exception paths, and code evidence. Rather than exposing everything at once, the three levels turn a complex harness into a navigable behavior map.

L1 · System overview starts with a global view of the harness. Instead of listing files and functions, it follows one request through the system: how the request enters, which stages it passes through, how state moves between them, and how model output becomes a real action. It first answers: *How does this harness run as a whole?*

L2・行動ユニットの概要

システムフローを「行動ユニット」に分解します。各ユニットは、一貫性のある行動クラスを捉え、その責任範囲、入力と出力、依存関係、そして重要な状態を記録します。このレベルでは、複雑な行動がどのように分解され、エンドツーエンドの流れの中で各部がどう再結合するかが一目でわかります。

L3・行動ユニットの詳細

ついに一つのユニットにズームインし、行動がトリガーされた際の処理フロー、状態の変化、例外や失敗発生時の分岐経路、そして証拠となるファイルや関数がどこにあるかを解説します。ここで重要なのは、「ファイルを削除する前に確認する」というルールが、単なる独立した規則ではなく、個々の判断を一つずつ検証可能な行動連鎖として扱われる点です。

L3 行動ユニットの具体例

「ファイルを削除する前に確認する」という例に戻りましょう。以下の L3 エントリでは、この一行のルールを、通常の実行パスと個別の見直しが必要なエッジケースの両方を網羅した、項目ごとにチェック可能な行動ユニットへと展開しています。

行動ユニット・ツール実行ステージ

削除前の確認

エージェントがファイルの削除を要求した場合、ハッチ（管理システム）は即座に操作を実行しません。まず権限ポリシーとユーザーの確認状態を確認し、その結果に基づいて処理を続行するか、リクエストを拒否するか、エラーを返すかを判断します。

トリガー

モデルは、delete_file(path) のような削除呼び出しを出力します。

権限ルール

ファイル削除は高リスク操作として定義されており、実行前にユーザーの確認が必要です。この設定により、権限管理が機能します。

状態変化

ハレス（制御装置）は確認要求とユーザーの応答を記録し、その情報に基づいて現在の処理を継続できるか判断します。

実行パス

ユーザーが承認した場合：サンドボックスランナー内で実行されます。拒否または権限がない場合：呼び出しを中止し、エラーを返します。

エッジケース

ヘッドレスモードや自動承認ポリシー、フォールバック経路が存在する場合は、確認フローが変更される可能性があるため、別途チェックが必要です。

証拠資料

tools/file_ops.py · L32–78

tools/wrapper.py · L84–128

policy/permissions.py · L15–66

runtime/sandbox.py · L40–112

state/manager.py · L40–61

L3 の振る舞い単位。 ファイル削除には確認が必要だと単に述べるのではなく、L3 はその判断を検証可能な要素に分解します。具体的には、リクエストのトリガーとなる要因、権限ルールがどのようにそれを制約するか、確認状態がどう記録されるか、実行がどう進行・停止するか、そして各ステップを支えるコード証拠は何か——これらを明確にします。L3 は振る舞いの理解を深め、バイパスリスクの監査を可能にし、ポリシー変更が必要な際に適切な実装箇所を特定する役割を果たします。

Part 04

コードからどのように振る舞いマップが生成されるのか？

この三段階構造はハンドブックが振る舞いを提示する方法を決めますが、マップの信頼性はすべての説明が実際のコードに遡れるかどうかにかかっています。モデルにファイルを一つずつ要約させるだけでマップを構築することはできません。生成には「事実優先」のルールが適用されます。自然言語で振る舞いを説明する一方で、主張のすべてはモデルの推測ではなく、コードという事実に根ざしている必要があるのです。

Harness リポジトリ

1. 事実の抽出

ファイル、関数、呼び出し、状態、設定に対する静的解析を行い、プログラムグラフを構築します。

1. 行動単位での整理

コードを実行の骨格にマッピングし、マッピングが収束するまで精緻化を行います。これにより「行動マップ」が完成します。

1. 合成

3 つのレベルを統合し、すべての証拠リンクを保持したままハンドブック（L1〜L3）を生成します。

提案者とレビューヤーが相互に検証し、収束するまで繰り返します。

文章で説明する際も、事実が根拠となります。各項目は必ず検証可能なコードの証拠とリンクされています。

コードベースから行動レベルの手引きへ。 静的解析によってプログラムの事実を抽出し、行動中心の構成でそれらをシステムの動作にマッピングします。最後に、すべての証拠リンクを保持したまま 3 レベル構成のハンドブックとして出力します。

1. 事実の抽出

→ プログラムグラフ

最初のステップでは、ファイル、関数、クラス、呼び出し関係、状態の読み書き、設定の境界、外部 API 呼び出しといった静的なプログラム情報を抽出します。これらを統合して作成されるのがプログラムグラフです。これは Harness の散在する実装要素を結びつけ、行動単位での整理を行うための事実上の基盤となります。

行動別に整理する

→ behavior map

2 つ目のステップでは、プログラムグラフを「行動マップ」へと再構成します。まず、ハルネスのライフサイクルにおける大まかな実行骨格を描き出し、その後、関数やモジュール、コード領域を対応するステージや行動単位に割り当てていきます。最初のマッピングが完璧でない場合もあるため、提案者・レビュー者のループを繰り返して修正を行い、最終的にステージの区切り、単位の境界、そしてコード上の根拠が整合するように調整します。

ハンドブックを合成する

→ handbook

3 つ目のステップでは、収束したマップをもとに、システム全体の概要、行動単位の概要、そして各行動単位の詳細へとハンドブックとして出力します。解説は自然言語で生成されますが、ソースコードへのリンク、関数参照、およびコードスニペットはすべて、抽出されたプログラム事実から直接引用されなければなりません。つまり、文章は説明し、事実は根拠となるのです。すべての行動連鎖をコード上で検証可能に保つことが重要です。

行動に関する質問からコード上の証拠へどうたどり着くか？

一度行動マップが完成すれば、読者はリポジトリ全体を検索するのではなく、特定の質問から始めて段階的にコードの根拠へとたどり着くことができます。これを行動指向型段階的開示（Behavior-Guided Progressive Disclosure: BGPD）と呼びます。

L1 レベルではシステム全体の文脈を提供し、L2 で関連する行動ユニットを特定し、L3 では検証可能な実装の詳細を開示します。

1. 行動に関する質問

「ファイルを削除する前に、必ず確認が必要ですか？」

1. L1 システム概要

本文とライフサイクル図

入力 → プラン → ツール実行 → 観察 → 完了

1. L2 ユニット概要

ユニットマップ・役割と機能

• Delete guard（削除ガード）: 3 つの関数
• Permission rule（権限ルール）: 1 つの関数
• State record（状態記録）: 2 つの関数