アーキテクチャの決定から本番デプロイまで、本ガイドは信頼性が高く安全で実際に役立つ AI エージェントを構築するために必要なすべてを網羅する。ReAct ループ、multi-agent オーケストレーション、ガードレール、評価、そしてデモと本番システムを分ける苦労して得たパターン。
AI エージェントとは、大規模言語モデルを推論エンジンとして用い、どのアクションを取るかを判断し、ツールを介してそれらのアクションを実行し、結果を観察し、目標が達成されるまで反復するシステムである。入力を受け取って出力を返す単純な LLM 呼び出しとは異なり、エージェントは環境に影響を与える能力を持ちながらループで動作する。
決定的な違いは自律性とツール利用にある。チャットボットは質問に答える。エージェントは会議を予約し、チケットを起票し、データベースに問い合わせ、レポートを書く — これまでに学んだことに基づいて各ステップで次に何をすべきかを判断する。
すべてのシステムが完全な自律性を必要とするわけではない。あなたのユースケースがこのスペクトラムのどこに位置するかを理解することが、アーキテクチャ、安全要件、運用上の複雑さを決定する。
プロンプトを入れ、応答を出す。ツールなし、ループなし。分類、要約、抽出。
モデルが 1 つ以上のツールを呼び出し、結果を統合する。ほとんどの function calling チャットボット。
モデルが推論し、行動し、観察し、繰り返す。いつ完了したかを自ら判断する。ReAct エージェント。
複数の専門エージェントが協調して複雑なタスクを解決する。supervisor または swarm パターン。
エージェントが最小限の人間の監督のもと、長い時間軸にわたって監視・計画・行動する。広範なガードレールを要する。
エージェントはレイテンシ、コスト、予測不能性を加える。決定論的なパイプライン（抽出、分類、固定ワークフロー）で問題を解決できるなら、そうすべきである。タスクが動的な意思決定を必要とするときにエージェントを用いる：どのツールを、どの順序で、何回呼び出すかを事前に予測できない場合である。分岐ロジックが設計時に既知ならワークフローを、実行時に判断する必要があるならエージェントを使う。
選択するアーキテクチャは、エージェントがどのように推論し、計画し、作業を調整するかを決定する。各パターンは制御性、レイテンシ、複雑さをめぐって異なるトレードオフを持つ。
エージェントはループの中で推論のトレースとツール呼び出しを交互に行う：思考、アクション、観察、繰り返し。
LLM がどのツールをどの引数で呼び出すかを判断し、結果を統合して最終的な回答にまとめる。
プランナー LLM が事前に複数ステップの計画を生成し、その後エグゼキューター LLM が各ステップを順次実行する。
複数の専門エージェントが協働し、それぞれが特定のドメインまたは能力を担い、supervisor によって調整される。
中央のエージェントがタスクを専門のサブエージェントに振り分け、その出力を集約する。関心事の明確な分離だが、supervisor はボトルネックであり単一障害点となる。
本番で最も一般的エージェントが文脈に基づいて互いに直接引き継ぐ。中央調整役は存在しない。より回復力が高いが、デバッグと把握はより難しい。
新興のパターンsupervisor のツリーであり、それぞれがサブエージェントのチームを管理する。複雑な組織構造を可能にするが、調整のオーバーヘッドが大きくなる。
複雑なユースケースのみうまくいき得る最も単純なアーキテクチャから始める。良いツールを備えた単一の ReAct エージェントは、設計の悪い multi-agent システムを毎回上回る。より単純なアプローチでは要件を満たせないという証拠があるときにのみ複雑さを加える。私たちが構築する本番エージェントシステムのほとんどは、よく設計された 5〜15 個のツールを備えた単一エージェントを使用している。
エージェントフレームワークの状況は急速に進化している。以下は、それぞれで本番システムを構築した私たちの経験に基づく主要な選択肢の率直な比較である。
| フレームワーク | 最適な用途 | 長所 | 短所 | 成熟度 |
|---|---|---|---|---|
| LangGraph | 複雑なステートフルなワークフロー、本番システム | きめ細かな制御、human-in-the-loop、永続化、ストリーミング | 学習曲線が急、グラフベースのメンタルモデル | 高 |
| CrewAI | multi-agent 協調、役割ベースのタスク | シンプルな API、役割/目標/背景モデル、組み込みの委任 | 実行フローの制御が少ない、デバッグが難しい | 中 |
| OpenAI Agents SDK | OpenAI ネイティブなアプリ、迅速なプロトタイピング | ネイティブな tool-calling、ハンドオフ、ガードレール、組み込みのトレーシング | ベンダーロックイン、モデル選択が限られる | 中 |
| AutoGen | 研究、会話型 multi-agent パターン | 柔軟な会話パターン、コード実行、ネストされたチャット | 複雑な設定、より重い抽象化 | 中 |
| Custom (no framework) | 完全な制御、最小限の依存、特定の制約 | 抽象化のオーバーヘッドなし、必要なものだけ、監査が容易 | より多くのボイラープレート、永続化/ストリーミングを自前で構築する必要 | 該当なし |
ほとんどの本番ユースケースでは、Python ベースのシステムには LangGraph を、TypeScript には カスタム実装 を推奨する。LangGraph は実行グラフのきめ細かな制御、組み込みの永続化、そして過度な抽象化のない human-in-the-loop パターンを提供する。より単純なユースケースでは、すでに OpenAI エコシステム内にいるなら OpenAI Agents SDK が本番への速い道を提供する。
ツールはエージェントの手と目である。ツールインターフェースの品質は、エージェントの性能を決定する単一で最大の要因である。優れたツールを備えた平凡なモデルは、設計の悪いツールを備えた最先端モデルを上回る。
ツール名は動詞-名詞の組み合わせであるべきだ（search_documents、create_ticket）。説明は、何をするかだけでなく、いつそのツールを使うかを説明すべきである。
enum、min/max 境界、必須フィールドを備えた厳格な JSON スキーマを定義する。スキーマが出力空間を制約すると、LLM はより良い引数を生成する。
エージェントが推論できる構造化されたエラーを返す。一般的な失敗ではなく、何が間違っていたか、そしてエージェントが何を違う形で試すべきかを返す。
読み取り専用のツールは自由に呼び出せるべきである。書き込みツールは可能な限り冪等であるべきで、破壊的なアクションは確認を要すべきである。
コード実行ツールは隔離されたコンテナで実行する。ファイルシステムへのアクセス、ネットワーク呼び出し、実行時間を制限する。エージェントに root や管理者の資格情報を決して与えない。
エージェントが必要とするものだけを返す。API 応答全体を吐き出すとコンテキストウィンドウのトークンを浪費し、モデルを混乱させる。要約するか主要なフィールドを抽出する。
すべてのツール説明は LLM に対して 3 つの問いに答えるべきである：このツールは何をするのか？ いつ使うべきか？ どのような制約があるか？
実際には、ほとんどのエージェントの失敗は 3 つの根本原因にたどり着く：(1) モデルに誤ったツールを選ばせる曖昧なツール説明、(2) モデルが解析するには大きすぎる、または構造化されていなさすぎるツール出力、(3) エージェントの回復を妨げるエラー情報の欠落。より強力なモデルに手を伸ばす前に、この 3 つを修正すること。
メモリのないエージェントはステートレスである — ターン間ですべてを忘れる。本番エージェントは、コンテキストを維持し、経験から学び、長時間実行されるタスクを管理するために、複数の層のメモリを必要とする。
メッセージとして LLM に渡される現在の会話履歴。これはメモリの最も基本的な形態であり、チャットフレームワークによって管理される。
セッションをまたいでベクトルストアまたは構造化データベースに永続化される事実、嗜好、知識。推論時に意味的類似性によって取得される。
過去のエージェントの軌跡の記録：エージェントが何を試み、何がうまくいき、何が失敗したか。再学習なしに経験から学ぶことを可能にする。
中間状態、部分的な結果、次のステップを追跡するために、エージェントが単一のタスク中に使用する構造化されたスクラッチパッド。
よくある誤解は、より大きなコンテキストウィンドウがメモリ管理の必要性を排除するというものである。そうではない。20 万トークン超のウィンドウでも、長いコンテキストの中ほどに埋もれた情報では性能が低下する。さらに重要なのは、すべてをコンテキストウィンドウに詰め込むのは高くつくということだ：現在の価格では、10 万トークンのコンテキストは、的を絞った取得を備えたよく管理された 4 千トークンのコンテキストより呼び出しあたり 10〜50 倍のコストがかかる。
エージェントは現実世界で実際のアクションを取る能力を持つ。このためガードレールは交渉の余地がない。制約の不十分なエージェントは、誤ったメールを送ったり、データを削除したり、API 予算全体を数分で使い切ったりしかねない。安全性は後から付け加える機能ではない — 初日からの設計上の制約である。
不可逆なアクション（メール送信、データベース変更、購入）の前に実行を一時停止する。計画されたアクションを提示し、明示的な承認を待つ。
エージェントの信頼度がしきい値を下回ったときに人間へ振り向ける。訓練分布の外にあるエッジケースに有用。
エージェントにタスクを完了させつつ、出力を非同期の人間によるレビュー用にフラグ付けする。速度が重要な大量かつ低リスクのタスクに適する。
明示的な反復制限がないと、エージェントは無限ループに陥ることがある — 同じツールをわずかに異なる引数で繰り返し呼び出したり、2 つの状態の間を振動したりする。すべての本番エージェントは、厳格な最大反復回数（通常 10〜25 ステップ）と実時間タイムアウトを持たねばならない。いずれかの制限に達したとき、エージェントは静かに失敗するのではなく、説明とともに部分的な結果を丁寧に返すべきである。
エージェントのテストは従来のソフトウェアのテストより根本的に難しい。エージェントは非決定論的であり、その振る舞いはモデル、ツール、環境に依存する。正確性、効率、安全性、コストを網羅する多層の評価戦略が必要である。
| 次元 | 説明 | 目標 | 測定方法 |
|---|---|---|---|
| タスク完了 | エージェントは述べられた目標を達成したか？ | > 85% | 保留タスクスイートでの二値の合否 |
| 軌跡の効率 | エージェントは最適に対して何ステップを要したか？ | < 1.5x 最適 | 専門家が作成した解とステップ数を比較 |
| ツールの正確性 | 正しいツールが正しい引数で呼び出されたか？ | > 90% | 期待されるツール呼び出し列とのトレース比較 |
| 安全コンプライアンス | エージェントはガードレールと境界を尊重したか？ | 100% | 敵対的プロンプトによる red-team テスト |
| レイテンシ（P95） | ユーザー入力から最終回答までのエンドツーエンドの時間 | < 30s | 本番トラフィック全体でのパーセンタイル追跡 |
| タスクあたりのコスト | 完了したタスクあたりの LLM + ツール呼び出しの総コスト | 予算内 | トレースごとのトークンと API 呼び出しの追跡 |
既知の入力と期待される出力で各ツールを単独でテストする。外部依存をモックする。これは標準的なソフトウェアテストであり、エージェントループで増幅する前に統合バグを捕捉する。
一連のテストタスクについて、ツール呼び出し、引数、観察の完全な列を記録する。ドメイン専門家が作成した参照軌跡と比較する。最終結果と取った経路の効率の両方を採点する。
既知の正しい結果を持つ 50〜200 の代表的タスクのスイートを構築する。これらのタスクに対して完全なエージェントを実行し、タスク完了率を測定する。すべてのデプロイ前とモデルアップグレード後にスイートを再実行する。
prompt injection、範囲外のリクエスト、エッジケース、敵対的入力でエージェントを体系的に探る。ガードレールがストレス下で持ちこたえることを検証する。これはユーザー向けエージェントで特に重要である。
本番のトレーシングと評価のプラットフォーム。すべてのエージェント実行を記録し、トレースに注釈を付け、履歴データで評価を実行し、退行を捕捉する。
プロンプトとエージェントの評価フレームワーク。テストスイートをコードとして定義し、カスタム評価器で出力を採点し、CI パイプラインに統合する。
動作するデモと本番エージェントの間の隔たりは巨大である。本番エージェントは、可観測で、コスト効率が高く、障害に強く、負荷下でスケーラブルでなければならない。
本番で動作する単一エージェントシステムを得たら、これらのパターンは新たな能力を解き放ち得る。それぞれが大きな複雑さを加えるため、明確なニーズとそれを支える運用上の成熟度があるときにのみ採用すること。
出力を生成した後、別の LLM 呼び出し（または批評プロンプトを伴う同じモデル）が結果の品質を評価し、改善を提案する。エージェントはその批評に基づいて出力を修正する。これは反復によって品質が向上するコード生成、執筆、分析タスクで特に効果的である。
実装上の注記：リフレクションは 2〜3 ラウンドに制限する。それを超えると、コストが線形に増える一方で品質は頭打ちになる。曖昧なフィードバックループを避けるため、批評者には構造化された採点基準を用いる。
品質に敏感な出力に最適エージェントを他のシステムが呼び出せる API エンドポイントとして公開する。エージェントはタスクの記述を受け取り結果を返すマイクロサービスになる。これは組み合わせを可能にする：オーケストレーターエージェントが、それぞれ独自のツールとドメイン知識を持つ専門エージェントサービスを呼び出せる。
主要な設計上の考慮事項：長いタスクのための webhook を伴う非同期実行、再試行の安全性のための冪等キー、バージョン管理された API 契約、応答時間と成功率に関する明確な SLA。
プラットフォームチームと社内ツールに最適メタエージェントが複雑なタスクをサブタスクに分解し、それぞれを最も適した専門エージェントに振り分け、結果を集約する。これは大規模な multi-agent supervisor パターンであり、各サブエージェント自体が独自のツール、メモリ、ガードレールを持つサービスであり得る。
オーケストレーターに必要なもの：タスク分解戦略（LLM ベースまたはルールベース）、利用可能なエージェントの能力レジストリ、部分的失敗のためのエラー処理、サブ結果を一貫してまとめる統合ステップ。
複数ドメインにまたがる企業ワークフローに最適エージェントは成功した軌跡と失敗した軌跡を記録し、推論時に類似する過去の経験を取得して現在の判断に役立てる。時間とともに、エージェントはモデルのファインチューニングなしに自らの本番履歴から実質的に学習する。失敗した軌跡は根本原因分析で注釈付けされ、負の例として注入される。
これには次が必要である：軌跡ストア（タスク記述でインデックスされたベクトル DB）、取得のための類似度しきい値、失敗モードの人間による注釈、過去の例を few-shot コンテキストとして取り込むプロンプトテンプレート。
反復的なドメイン固有タスクに最適すべてのエージェントがユーザープロンプトに応答するわけではない。スケジュール（cron 的）で実行されたり、イベント（新着メール、Slack メッセージ、データベース変更）でトリガーされたりするものもある。これらのバックグラウンドエージェントは、人間の起動なしに監視し、要約し、エスカレーションし、定型ワークフローを自動化する。
設計パターン：ポーリング + 変更検出、webhook トリガーの実行、失敗した実行のためのデッドレターキュー、重複イベントを安全に扱う冪等処理。
運用自動化に最適