エージェントハーネスエンジニアリング入門：LLMを信頼できるエージェントに変えるアーキテクチャ

素のLLMをそのまま使っても、エージェントは信頼できない。プロンプト管理・ツール呼び出し・メモリ・リトライロジックを組み合わせた「ハーネス」設計こそが、実用エージェントと実験エージェントを分ける境界線だ。

なぜ「素のLLM」だけではエージェントが壊れるのか

ChatGPTやClaude.aiを日常的に使っていると、AIはかなり賢いと感じるはずだ。しかし、それを自動化パイプラインに組み込んで「自律的に動くエージェント」として使おうとした瞬間、まったく別の問題が噴出する。幻覚（存在しないAPIを呼び出す）、無限ループ（同じ処理を繰り返す）、コンテキスト汚染（前回の作業の残滓が次の判断を狂わせる）——これらはすべて、LLMを「単体」で使ったときに起きる問題だ。

ハーネスエンジニアリングとは、LLMの周囲に設計された構造的な足場（ハーネス）を作る工学的アプローチだ。安全帯のハーネスが人間を守るように、エージェントハーネスはLLMをラップして、信頼できる動作を保証する。これは最先端のAI研究の話ではなく、「LLMをプロダクションに乗せるためのソフトウェアエンジニアリング」の話だ。

Anthropicが公開した「Building effective agents」というガイドラインは、まさにこのハーネス設計の原則を体系化したものだ。その核心にあるのは「シンプルに始めろ」という教えだ。複雑なマルチエージェントシステムを最初から作ろうとするな、まず単一のエージェントを信頼できる形で動かすことに集中しろ——という戒めは、多くの開発者が陥る罠を的確に指摘している。

ハーネスの5大コンポーネント

実用的なエージェントハーネスは5つのコンポーネントで構成される。第一がプロンプト管理レイヤーだ。エージェントが受け取るシステムプロンプトは、単なる指示文ではなく、エージェントの性格・制約・判断基準・エスカレーション条件を定義するコントラクトだ。これをコード上でバージョン管理し、A/Bテストできる状態にしておくことが信頼性の第一歩になる。

第二がツール呼び出し管理だ。LLMはツールを呼び出す際にパラメーターを誤る場合がある。入力スキーマのバリデーション、呼び出し結果のサニタイズ、タイムアウト設定——これらがないと、外部APIの一時障害がエージェント全体をクラッシュさせる。第三がメモリ管理で、コンテキストウィンドウの上限に達する前に過去の会話を要約・圧縮するロジックが必要だ。長期タスクを扱うエージェントにとって、コンテキスト管理の失敗は致命傷になる。

第四がリトライ・フォールバックロジックだ。LLM APIは一時的に失敗することがある。指数バックオフ付きのリトライ、エラー種別ごとの分岐処理、最終的なフォールバック（人間へのエスカレーション）を設計しておくことで、エージェントが想定外の状況で固まることを防げる。第五が評価ループだ。エージェントが正しく動いているかを継続的に測定する仕組みがないと、品質劣化に気づけない。

Orchestrator-Worker・Plan-Execute・ReActの3パターン

ハーネスの上に乗るエージェントのアーキテクチャパターンとして、現在最も広く使われているのが3つだ。Orchestrator-Workerは、指揮者エージェントがタスクを分解し、専門エージェント（ワーカー）に割り振るパターン。Claude Codeのマルチエージェントモードはこれに近い設計だ。コードレビュー・テスト生成・ドキュメント作成を並列に走らせるのに向いている。

Plan-Executeは、まずタスク全体の実行計画を立て（Planフェーズ）、その計画に従って順番に実行する（Executeフェーズ）パターンだ。Claude Codeのplanモードはまさにこの思想に基づいている。長期タスクや影響範囲が広い変更に向いており、途中での軌道修正も計画レベルで行えるため、デバッグが容易だ。

ReAct（Reason + Act）は、「考える→行動する→観察する」のサイクルを繰り返すパターンだ。ツールを呼び出すたびにその結果を推論に反映させるため、複雑な問題解決に強い。一方でループが深くなるとトークン消費が爆発的に増えるという欠点がある。3パターンのうちどれを選ぶかは、タスクの性質（並列性・依存関係・不確実性）に依存する。

信頼性を測る評価フレームワーク

ハーネスの品質を測るための評価フレームワークとして、現在標準的に使われているのがSWE-BenchとGAIAだ。SWE-Benchは実際のGitHub Issueを自律的に解決できるかを測る。GAIAはWebブラウジング・ファイル操作・計算を組み合わせた複合タスクの精度を評価する。これらのベンチマークで高スコアを出すには、単にモデルが賢いだけでなく、ハーネスの設計が優れていることが不可欠だ。

プロダクション向けの評価では、これらの公開ベンチマークに加えて「自社のタスク専用テストスイート」を作ることが重要だ。エージェントが本当にユーザーの役に立っているかを測る指標（タスク完了率、エラー率、人間介入頻度）を定義し、継続的にモニタリングする。ハーネスエンジニアリングにおいて、評価なき改善はない。

ハーネス設計でよくある失敗と回避策

最も多い失敗は「ハーネスを後付けで作ろうとする」ことだ。最初はプロトタイプとして素のLLM呼び出しで動かし、うまくいったら本番化しようとする。しかし、ハーネスなしで動いたものがハーネスありで同じように動くとは限らない。プロンプトが変わり、エラーハンドリングが加わり、メモリ管理が入ると、エージェントの振る舞いが変化する。ハーネスは最初から設計の一部として組み込むべきだ。