カスタムエージェントハネスの構築方法
LangChain は、既存の包括的なハッチス（Deep Agents など）では対応しきれない詳細なカスタマイズニーズに応えるため、モデルとツールを接続する最小限の基盤である「create_agent」関数を導入し、開発者がコンテキスト管理やガードレールを自由に設計できる「カスタムエージェントハッチス」構築の指針を示した。
キーポイント
エージェントの本質とハッチスの定義
エージェントは「モデル＋ハッチス」として定義され、ハッチスはモデルを現実世界に接続し、各ステップで適切なコンテキストを提供する足場（scaffolding）の役割を果たす。
既存フレームワークの限界とカスタマイズの必要性
Deep Agents や Claude Agent SDK などの事前構築型ハッチスは開発を迅速化するが、独自のビジネスロジック、詳細なプロンプト制御、ガードレールが必要なケースには対応しきれない。
create_agent の最小限アプローチ
LangChain は「create_agent」関数を通じて、モデル、ツール、システムプロンプトを明示的に渡すことで、開発者がハッチスの構造をゼロから設計・カスタマイズできる最小限の基盤を提供する。
影響分析・編集コメントを表示
影響分析
この記事は、LLM エージェント開発における「使いやすさ」と「制御の自由度」のトレードオフに対する明確な解決策を示しており、大規模システムや複雑なビジネスロジックを扱う開発者にとって重要な指針となる。LangChain が提供する最小限の抽象化層（create_agent）を活用することで、開発者は既存フレームワークの制約に縛られず、自社の要件に最適化した堅牢なエージェント基盤を構築できるようになる。
編集コメント
既存のフレームワークに依存せず、自社のビジネス要件に合わせてエージェントの骨格を設計する重要性が再認識される記事です。開発者が「黒箱」から「白箱」へと思考を転換し、より制御可能な AI エージェントを構築するための重要なステップと言えます。
有用なエージェントを構築する上で重要なのは、主に*カスタマイズ*です。つまり、現在のタスクに対して適切なコンテキスト、データ、および環境にエージェントを接続することです。
本質的に、エージェントとは、タスクが完了して結果を返すまで、モデルがツールをループ呼び出し続けるものです:
また、エージェントを以下のように定義することもできます:
**agent = model + harness
harness（ハルネス）とは、モデルの周囲にある足場であり、それを現実世界に接続するものです。
本記事の残りの部分では、以下の前提を置きます:
- エージェントの質は、モデルに提供されるコンテキストの質に依存する
- ハルネスの役割は、各ステップでモデルにコンテキストを提供すること
したがって、有用なエージェントを構築するには、与えられたタスクに対して適切なコンテキストをモデルへ効果的に配信できるハルネスが必要です。
ベースとなるハルネス
create_agent は、LangChain においてハルネスを構築するための基本機能（プリミティブ）です。モデル、ツール、システムプロンプトを渡すだけで、動作するエージェントが完成します:
from langchain.agents import create_agent
agent = create_agent(
model="anthropic:claude-sonnet-4-6",
tools=tools,
system_prompt="you are a helpful assistant..."
)
Deep Agents や Claude Agent SDK のようなハルネスは、メモリ管理、コンテキスト管理、サンドボックス化などを含む、特定の設計思想に基づいたミドルウェアスタック（以下で説明）が事前に組み込まれています。これらは、生産環境で即座に使用可能なエージェントを迅速に構築するために設計されており、多くのケースで良好に機能します。しかし、多くのエージェントでは、これらのハルネスがサポートする範囲を超えた、より細粒度のカスタマイズが必要となります：カスタムプロンプト、ビジネスロジック、ガードレールなどです。
create_agent は異なるアプローチを採用しています：それは*あえてミニマリスト*な設計です。私たちの哲学は、非常に高い設定自由度を持つコーディングエージェントハルネスである Pi と似ています。create_agent はコアとなるエージェントループを実装するだけであり、カスタマイズのためのプリミティブとしてミドルウェアを公開します。
ミドルウェア：ハルネスのカスタマイズ方法
ミドルウェアは、モデル呼び出しの前と後、ツール呼び出しの前と後、エージェントの起動時および終了時など、エージェントループの各ステップにフックします。それぞれのコンポーネントは一つの懸念事項のみを扱い、他のどのコンポーネントとも自由に組み合わせることができます。
ミドルウェアを使用することで、エージェントにいくつかのレバー（多くの場合これらは連携して機能します）を通じて機能を追加することができます。
決定論的ロジック。 ビジネスロジック、ポリシーの強制実行、動的なエージェント制御 — ループ内の特定の時点で発火する必要があるあらゆるもの。これには、タスクの複雑さに基づいてモデルを切り替えたり、プロンプトを調整したり、エージェントのメッセージ履歴を更新（例えば圧縮時など）したりするなど、エージェント自体に対するランタイム制御も含まれます。これは、プロンプト内に存在できない（または存在すべきでない）あらゆるものの適切な場所です。
ツール。 ツールを直接エージェントに登録するのではなく、ミドルウェアがセットアップ、テardown、登録という完全なライフサイクルを処理し、エージェントに作業用のクリーンなツールのセットを手渡します。これは、ツールに依存関係がある場合や初期化が必要である場合、または実行の最後にきれいに終了させる必要がある場合に重要です。また、ツールの設定をエージェント定義全体に散在させるのではなく、それを支配するロジックの近くに保つことができます。
カスタム状態。 ミドルウェアがフック間で状態を追跡する必要がある場合、ミドルウェアはエージェントの状態にカスタムプロパティを追加して拡張できます。これにより、ミドルウェアは実行全体を通じて状態を追跡し（エージェントの実行中に持続するカウンター、フラグ、または他の値を維持）、フック間でデータを共有することが可能になります。
ストリームハンドラ。 ミドルウェアは、エージェントの出力ストリームをインターセプトして変換することができます。イベントのフィルタリング、メタデータの注入、異なるイベントタイプを異なるコンシューマーへルーティングなどです。スタックの異なる部分が、エージェントが行う異なる事柄に反応する必要がある場合に有用です：トークンデルタを消費する UI、ツール呼び出しを記録する監査ログ、レイテンシーを追跡する監視システムなど。
ミドルウェアの素晴らしい点は以下の通りです。
- エージェントループ内の任意の時点でカスタマイズを可能にする
- 関連するロジックを合成可能で共有可能なコード単位にバンドルする
LangChain は、最も一般的なパターンに対して 事前構築されたミドルウェア を提供しています。ユースケース固有のものは、カスタムミドルウェア 1 つで対応可能です。各コンポーネントが独立しているため、同じミドルウェアを組織内のすべてのエージェント間で再利用でき、新しいエージェントは再構築することなく、実戦で検証された振る舞いを継承できます。
ハーネスの機能
ハーネスの役割は、与えられたタスクに対して、モデルに適切なタイミングで適切なコンテキストを提供することです。
以下の表では、一般的な機能をそれをサポートするミドルウェアに対応付けています。実際の運用環境のエージェントは、エージェントの要件（長時間実行されるか？タスクはどの程度複雑か？エージェントのアクションはどれほど機密性が高いかなど）に応じて、複数の機能を組み合わせて使用することがほとんどです：
機能
なぜ重要なのか
ミドルウェア
コンテキストオーバーフローの防止
長時間実行されるセッションではメッセージ履歴が急速に蓄積されます。介入がないと、コンテキストウィンドウ（context window）が溢れてしまいます。
SummarizationMiddleware, ContextEditingMiddleware
メモリへのアクセスと更新
起動時に必要な知識を読み込み、実行終了時に書き戻します。これにより、エージェントは実際の使用を通じて時間とともに改善できます。
FilesystemMiddleware, MemoryMiddleware, SkillsMiddleware
環境内でのアクション実行
固定されたツールセットではエージェントの行動範囲が制限されます。ファイルシステムや実行環境へのアクセスにより、より創造的な解決策が可能になり、多くの場合トークン効率も向上します。
ShellToolMiddleware, FilesystemMiddleware, CodeInterpreterMiddleware
タスクの委任
サブエージェントはクリーンなコンテキストウィンドウで複雑なサブタスクを処理します。ToDo リストによって、長時間の実行全体にわたる進捗を追跡できます。
SubAgentMiddleware, AsyncSubAgentMiddleware, TodoListMiddleware
一時的な障害への対応
モデルやツールは予測不能な形で失敗することがあります。本番環境のエージェントでは、モデルが利用できない場合にバックオフ（backoff）とフォールバック（fallback）を備えたリトライロジックが必要です。
ToolRetryMiddleware, ModelRetryMiddleware, ModelFallbackMiddleware
ポリシーの適用
PII（個人識別情報）の処理、コンプライアンスチェック、承認ゲート — これらはモデルが何を行おうとも、すべての呼び出しで発火する必要があります。これらをプロンプト内に記述すべきではありません。
PIIMiddleware, HumanInTheLoopMiddleware
エージェントの誘導
完全な自律性が常に適切とは限りません。重要なアクションの前には一時停止し、人間の承認、拒否、またはリダイレクトを待機してください。
HumanInTheLoopMiddleware
コストの制御
プロンプトキャッシングは、長時間実行されるタスクにおけるトークン使用量を削減します。呼び出し制限により、コストが無制限に蓄積するのを防ぎます。
ModelCallLimitMiddleware, ToolCallLimitMiddleware, PromptCachingMiddleware
事前構築されたミドルウェアの完全なリストは こちら でご覧ください。
タスクとハネスの適合性
タスクとハネスの適合性とは、ハネスが実際のタスクの要件にどれだけ合致しているかを指します：必要なコンテキスト、遭遇する可能性のある失敗、適用しなければならないポリシー、および動作環境です。カスタマーサービスエージェント用のハネスは、長時間実行されるコーディングエージェント用に構築されたものとは大きく異なります。
LangChain で構築するすべてのエージェント、GTM エージェント、非同期コーディングエージェント、そして ノーコードエージェントビルダー はすべて、各エージェントの使命に合わせてカスタマイズされたミドルウェアスタックを備えた create_agent を基盤として構築されています。
優れたエージェントは、単に能力の高いモデルで構築されるだけでなく、タスクにきっちりフィットするハーン（harness）によって構築されます。カスタムハーンを構築する最も簡単な方法は、create_agent を使用することです。
参考文献
はじめに
- クイックスタート：create_agent で最初のエージェントを構築する
- create_agent ガイド
- ミドルウェアリファレンス
- カスタムミドルウェアガイド
- Deep Agents: create_agent を基盤とした本番環境向けハーン
原文を表示
Building useful agents is largely about *customization:* connecting your agent to the right context, data, and environment(s) for the task at hand.
At its core, an agent is a model calling tools in a loop until it completes a task and returns a result:
You can also define an agent as:
agent = model + harness
The harness is the scaffolding around the model that connects it to the real world.
The remainder of this post assumes the following:
- An agent is only as good as the context provided to the model
- The job of a harness is to provide context to the model at every step
So, to build a useful agent, you need a harness that’s great at delivering the right context for the given task to the model.
The base harness
create_agent is LangChain's primitive for building a harness. Pass in a model, tools, and a system prompt, and you have a working agent:
from langchain.agents import create_agent
agent = create_agent(
model="anthropic:claude-sonnet-4-6",
tools=tools,
system_prompt="you are a helpful assistant..."
)
Harnesses like Deep Agents and the Claude Agent SDK come pre-assembled with an opinionated middleware (explained below) stack: memory, context management, sandboxing, and more. They're designed to get you to a production-ready agent fast, and they work well for most cases. But many agents need finer grained customization than these harnesses support: custom prompting, business logic, guardrails, etc.
create_agent takes a different approach: it’s *purposefully minimalistic*. Our philosophy is similar to that of Pi, a highly configurable coding agent harness. create_agent just implements the core agent loop, and it exposes middleware as a primitive for customization.
Middleware: how you customize the harness
Middleware hooks into the agent loop at each step: before and after model calls, before and after tool calls, at agent startup and teardown. Each piece handles one concern and composes freely with any other:
Middleware allows you to add capabilities to your agent via a few levers that often work together:
Deterministic Logic. Business logic, policy enforcement, dynamic agent control — anything that needs to fire at a specific point in the loop. This includes runtime control over the agent itself: swapping the model based on task complexity, adjusting the prompt, and updating the agent’s message history (during compaction, for example). The right place for anything that can't (or shouldn't) live in a prompt.
Tools. Rather than registering tools directly on the agent, middleware can handle the full lifecycle — setup, teardown, registration — and hand the agent a clean set of tools to work with. This matters when tools have dependencies, require initialization, or need to be torn down cleanly at the end of a run. It also keeps tool configuration close to the logic that governs it, rather than scattered across the agent definition.
Custom state. If your middleware needs to track state across hooks, middleware can extend the agent’s state with custom properties. This enables middleware to track state throughout execution (maintain counters, flags, or other values that persist throughout agent runs) and share data between hooks.
Stream handlers. Middleware can intercept and transform the agent's output stream — filtering events, injecting metadata, routing different event types to different consumers. Useful when different parts of your stack need to react to different things the agent does: a UI consuming token deltas, an audit log capturing tool calls, a monitoring system tracking latency.
The beauty of middleware is that it:
- Enables customization at any point in the agent loop
- Bundles related logic in composable, sharable units of code
LangChain ships prebuilt middleware for the most common patterns. Anything bespoke to your use case is one custom middleware away. Because each piece is isolated, the same middleware can be reused across every agent in an organization so that new agents inherit battle-tested behavior without rebuilding it.
Harness capabilities
The job of a harness is to get the model the right context at the right time for the given task.
The table below maps common capabilities to middleware that support them. Most production agents end up using several together, depending on the agent’s needs (is it long running? how complex are the tasks? how sensitive are the agent’s actions?, etc):
Capability
Why it Matters
Middleware
Prevent context overflow
Long-running sessions accumulate message history fast. Without intervention, it overflows the context window.
SummarizationMiddleware, ContextEditingMiddleware
Access and update memory
Load relevant knowledge at startup, write it back at the end of a run. Lets the agent improve over time from real usage.
FilesystemMiddleware, MemoryMiddleware, SkillsMiddleware
Take actions in an environment
A fixed toolset limits what an agent can do. Access to a filesystem and execution environment unlocks more creative solutions, often with greater token efficiency.
ShellToolMiddleware, FilesystemMiddleware, CodeInterpreterMiddleware
Delegate tasks
Subagents handle complex sub-tasks with clean context windows. A todo list tracks progress across a long run.
SubAgentMiddleware, AsyncSubAgentMiddleware, TodoListMiddleware
Handle transient failures
Models and tools fail unpredictably. Production agents need retry logic with backoff and fallbacks when a model is unavailable.
ToolRetryMiddleware, ModelRetryMiddleware, ModelFallbackMiddleware
Enforce policies
PII handling, compliance checks, approval gates — these need to fire on every call regardless of what the model does. They don't belong in a prompt.
PIIMiddleware, HumanInTheLoopMiddleware
Steer the agent
Full autonomy isn't always appropriate. Pause before consequential actions and wait for a human to approve, reject, or redirect.
HumanInTheLoopMiddleware
Control costs
Prompt caching reduces token spend on long-running tasks. Call limits prevent costs from accumulating unchecked.
ModelCallLimitMiddleware, ToolCallLimitMiddleware, PromptCachingMiddleware
See the full list of prebuilt middleware here.
Task-harness fit
Task-harness fit is how well your harness matches the actual demands of the task: the context it needs, the failures it'll encounter, the policies it must enforce, the environment it operates in. A harness for a customer service agent looks very different from one built for a long-running coding agent.
Every agent we build at LangChain, including our GTM agent, asynchronous coding agent, and our no-code agent builder, is built on create_agent with a middleware stack tailored to that agent’s mission.
The best agents aren't just built with capable models, they're built with harnesses that tightly fit the task. The easiest way to build a custom harness is with create_agent.
References
Get Started
- Quickstart: build your first agent with create_agent
- create_agent guide
- Middleware reference
- Custom middleware guide
- Deep Agents: a production harness built on create_agent
関連記事
エージェントの観測可能性：本番環境でのLLMエージェントの監視と評価方法
LLMエージェントの本番環境におけるモニタリングには、新しい観測ツールが必要である。大規模なAIエージェントのトレース、評価、改善を行う手法について解説する。
AI エージェントに専用コンピューターを付与する
LangChain は、数百万のタスクを実行する AI エージェントが安全かつ効率的に動作するために、各エージェントに個別のファイルシステムやシェル環境を持つ仮想コンピューターを提供するインフラシフトの必要性を提唱している。
LangGraph の耐障害性：リトライ、タイムアウト、エラーハンドラー
LangChain が公開した記事で、LangGraph に組み込まれた耐障害性の三つの仕組み（バックオフ付き自動リトライの RetryPolicy、時間制限の TimeoutPolicy、リトライ失敗後のクリーンアップを行う error_handler）について解説し、SAGA パターンを用いた現実的なマルチステップワークフローの処理方法も紹介している。