Learn Agent Architecture

現代の AI agent が LLM の周りにどう組み立てられているかを学びます。

English · 繁體中文 · 简体中文 · 日本語 · 한국어

推論するのはモデルです。harness はその推論を制御された行動に変えます。tool を実行し、呼び出しをまたいで状態を保ち、副作用にゲートをかけ、複数の loop を調整します。 モデルを一度呼び出すだけでは、そのどれもできません。

この repo は harness をセクションごとに解説します。loop、tool、memory、permission、context、task、そしてインターフェースです。 一度身につければ多くの agent が読めるようになります。コーディング用の tool もチャットアシスタントも自律実行型の runner も、違いのほとんどは harness の選択にあるからです。

1 セクションでは収まらない話題は、3 つの姉妹 repo で掘り下げています。

• learn-agent-memory: memory loop を本番向けの memory サブシステムまで拡張します。
• learn-deepseek-harness: deepseek-harness をゼロから学びます。plugin の接合部を 1 つずつ追います。
• EvalGrill: agent を使う実際の事例を、再現でき検証できる eval セットに変えます。

目次: Loop · 学び方 · 研究対象のシステム · セクション一覧 · リポジトリ構成 · デモの実行

---

Agent loop

ほとんどの agent は同じ制御フローを共有します。モデルを呼び出し、要求された tool を実行し、結果を追記し、もう一度モデルを呼び出します。

loop そのものは小さいです。工学の大部分はその周りにあります。tool の dispatch、副作用のゲート、context の管理、状態の永続化、そして他の loop との調整です。

---

学び方

どのセクションも独立していて、同じ 4 部構成のレンズを使います。

1. 導入。 この層がどんな問題を解くか。
2. 仕組み。 一般的な設計と制御フロー。
3. システム別。 実在のシステムがどう実装しているか。
4. 失敗モード。 何が壊れ、どう緩和するか。

この repo から学ぶには、次のようにしてください。

• セクションを順番に読んでください。どのセクションも 1 つ前の層の上に積み上がります。
• 実行できるセクションでは、まず src/loop.py を読み、それから demo.py を動かしてください。
• あるセクションの src/ を 1 つ前のセクションと diff してください。その差分が、そのセクションが足した唯一の仕組みです。

---

研究対象のシステム

どのシステムも、以下のセクションのための実例です。

システム	使われる理由	何を読み取るか	セクション	調査したバージョン
Claude Code	最前線のコーディング agent。ファイルを編集し、コマンドを実行し、実際の repo に変更を反映します。	harness の全体像。まずここから	0 から 23 (すべて)	v2.1.88
Hermes Agent	長期的なアシスタント。あなたを覚え、作業の流れを学び、どこでも動きます。	memory、skill、常時接続の channel	7, 9, 14, 16, 19, 21, 22	v2026.7.1
mini-swe-agent	研究用のベースライン。bash tool が 1 つだけ、約 150 行です。	最小構成で完結した loop、予算、eval harness	0 から 3, 8, 10, 11, 20 から 23	v2.4.5
deepseek-harness	plugin 中心の harness。loop さえ差し替え可能な plugin です。	plugin の接合部、永続的な session log、ACP	1 から 8, 10 から 14, 16 から 21	dsh-v0.1.0-rc.7
(more soon)

今後 OpenClaw や aider を含む他のシステムを追加できます。 さらに深く掘り下げる姉妹 repo が 2 つあります。memory 層は learn-agent-memory、 deepseek-harness をゼロから学ぶなら learn-deepseek-harness です。

---

セクション一覧

基本の loop から自走する harness まで、8 つの層があります。各行は独立した 1 本の解説へのリンクです。

セクション 9 は learn-agent-memory に続きます。その memory loop を本番規模へ広げる 10 段階です。

#	セクション	問い	主な仕組み
	層 0 · 土台
0	Harness の主題	agency はどこから来るのか	モデルと harness、行動、観測、permission
	層 1 · 中心の loop
1	Agent loop	agent はどうやって動き続けるのか	messages[]、loop、stop_reason
2	Tool runtime	tool はどう呼ばれ、どう振り分けられるのか	registry、schema、dispatch、遅延読み込みの検索
3	Permission と sandbox	副作用にはどうゲートをかけるのか	permission モード、承認、sandbox 化
4	Hooks	拡張は loop のどこに取り付くのか	PreToolUse、PostToolUse、ライフサイクルイベント
	層 2 · 複雑な作業
5	計画と todo	大きな仕事はどう分解するのか	plan mode、todo リスト、編集前の承認
6	Subagent	部分問題はどう切り離すのか	新しい messages[]、委譲、child loop
7	Skill	能力はどう必要に応じて読み込むのか	SKILL.md、カタログ、段階的な開示
8	Context 管理	長い session をどうやって窓に収めるのか	予算管理、スタブ、compaction、要約
	層 3 · 知識と回復力
9	Memory	実行をまたいでどう覚えるのか	選別、recall、抽出、統合
10	System prompt の組み立て	prompt は turn ごとにどう作られるのか	prompt の各区画、実行中の状態、cache 境界
11	エラー回復	長い仕事はどう失敗を乗り切るのか	リトライ、あふれからの回復、フォールバックモデル
	層 4 · 長時間実行と非同期
12	Task システム	仕事は turn を越えてどう残るのか	task レコード、依存関係、ロック
13	バックグラウンド実行	仕事はどうやってメイン loop の外で動くのか	ハンドル、task の状態、通知キュー
14	スケジューリング	agent はどうやって後から動くのか	cron、スリープ、リモートからの起動、キュー
15	Worktree の分離	並行作業はどう衝突を避けるのか	git worktree、cwd の束縛、安全な後片付け
	層 5 · マルチ agent
16	協調	多数の agent はどう会話するのか	inbox、ブロードキャスト、permission の持ち上げ
17	プロトコル	agent はどう合意し、どうきれいに止まるのか	計画の承認、停止のハンドシェイク
18	自律性	agent はどう自分たちを組織するのか	アイドル周期、task の確保、自己組織化
	層 6 · 拡張と統合
19	MCP / plugin / channel	harness はどう外の世界に手を伸ばすのか	トランスポート、channel、tool プールの組み立て
20	可観測性と評価	動いているとどう分かるのか	トレース、メトリクス、eval、失敗の分析
23	評価	変更で良くなったとどう分かるのか	eval 環境、リセット、判定器、Pass^k
	層 7 · 組み合わせ
21	Loop エンジニアリング	loop はどう積み重なって自走するシステムになるのか	検証 loop、トリガー、予算、成熟度レベル
22	グラフエンジニアリング	制御フローはいつモデルからコードへ移るのか	ノード、コードで書いた辺、循環、ノードとしての agent、型付きの判断で選ぶ辺

---

リポジトリ構成

24 本のセクション解説がすべて揃っています。00-harness-thesis/ から 23-evaluation/ までです。

learn-agent-architecture/
├── README.md                  # top-level map
├── sections/                  # one folder per section
│   ├── 00-harness-thesis/     # README.md per section
│   ├── 01-agent-loop/src/     # runnable chain starts here
│   ├── ...
│   └── 23-evaluation/
└── references/                # primary sources and prior art

各セクションのフォルダは NN-name/ という名前で、README.md を 1 つ含みます。

セクション 1 から 23 には実行できる src/ も付いています。コードはセクションごとに積み上がります。 各セクションは仕組みを 1 つ足して loop.py を発展させるので、隣り合うセクションの diff が変更点そのものになります。

1 セクションでは収まらない深掘りは、それぞれ独立した repo にあります。 learn-agent-memory はセクション 9 の loop を完全な memory サブシステムへ広げます。 learn-deepseek-harness は deepseek-harness をゼロから、plugin の接合部を 1 つずつ学びます。

---

デモの実行

セクション 1 から 23 には実行できるデモが付いています。repo のルートで一度だけ準備します。

uv venv
uv pip install -r requirements.txt
cp .env.example .env        # then add your ANTHROPIC_API_KEY

依存関係は requirements.txt に固定してあります。.env は gitignore されていて、次を持ちます。

• ANTHROPIC_API_KEY
• 省略可能な ANTHROPIC_MODEL
• 省略可能な ANTHROPIC_BASE_URL

実行できるセクションには次があります。

• test.py: オフラインの検査。キーは要りません。
• demo.py: API に対する実際のデモ。

python sections/01-agent-loop/src/test.py         # offline
uv run python sections/01-agent-loop/src/demo.py  # live

---

貢献するには

• システムを足す。 新しい agent を同じセクション構成に当てはめてください。
• セクションを深める。 仕組み、より分かりやすい図、より鋭い失敗モードを足してください。
• 記述を正す。 これらはソース、ドキュメント、実際の挙動からの再構成です。出典付きの訂正を歓迎します。

推測より、名前があって検証できる仕組みを優先してください。出典を挙げてください。 PR のチェックリスト全体は CONTRIBUTING.md を見てください。

---

参考文献

• claude-code: 仕組みの名前と実装の場所をたどるために使った Claude Code のソースのバックアップ。
• hermes-agent: 2 つめの研究対象にしたオープンソースの agent harness (MIT)。
• mini-swe-agent: 3 つめの研究対象にした最小構成の SWE agent (MIT)。
• deepseek-harness: 4 つめの研究対象にした plugin ベースの agent harness (MIT)。
• learn-claude-code: コード起点の harness 再構成と、セクションの組み立て方。
• EvalGrill: セクション 23 を実践する姉妹ツール (Apache-2.0)。agent を使う実際の事例から eval セットを作ります。
• Anthropic Agent Skills best practices: skill における段階的な開示のレベル。
• Anthropic prompt caching: cache の区切り、TTL、価格、最小 token 数。
• cobusgreyling/loop-engineering: loop の構成要素と成熟度レベル。
• LangChain · The art of loop engineering: 積み重なる 4 つの loop。
• Addy Osmani · Loop engineering: agent loop のための構成要素の組み合わせ方。
• MindStudio · What is loop engineering: 自律的なワークフローの終了条件。
• Lilian Weng · Harness engineering for self-improvement: 改善の loop と、loop の外に置くゲート。
• LangChain · 3 years of graph engineering: ノード、辺、循環、そしてノードとしての agent。
• Anthropic · Building effective agents: ワークフローと agent の違い、および 5 つのワークフロー類型。
• Google · Why we built ADK 2.0: コードで書くルーティングと、ノード間の context 分離。
• TypeSafe Jev docs: 型付きの decision model のリクエスト契約と答えの形。 セクション 22 は decide.py でそれをグラフの辺に組み込みます。
• ai-agent-book: 李博杰 著『深入理解 AI Agent』(Apache-2.0)。第 6 章が評価のセクションの土台です。

---

謝辞

本プロジェクトを掲載してくれた以下のコレクションに感謝します。

• walkinglabs/awesome-harness-engineering
• Jenqyang/Awesome-AI-Agents
• WenyuChiou/awesome-agentic-ai-zh