Agent Engineering 爆発後に学んだ 5 つのエンジニアリングの教訓

エージェントの暴走コールから始める

3 か月前、私は AI エージェント プロジェクトを引き継ぎました。これにより、エージェントが作業指示書の読み取り、責任者の割り当て、返信の送信など、顧客の作業指示書システムを自動的に管理できるようになりました。簡単そうに聞こえますよね？その結果、開始初日に、エージェントは「再割り当て」API をループで 37 回呼び出し、同じ作業指示を 37 人に転送しました。顧客はCEOに直接苦情を言いました。その瞬間、Agent Engineering は単にいくつかのプロンプトを書くだけではなく、体系的なエンジニアリング的思考が必要であることに気づきました。

その後のリファクタリング中に私が学んだ 5 つの重要な教訓を次に示します。

1. ツール アーキテクチャのスキーマを記述するだけでなく、「制約」も記述します

最初にツール関数を定義したときは、関数名、パラメーター、戻り値の型のみを記述しました。たとえば、assign_ticket(ticket_id, assignee_id)。その結果、エージェントは存在しない assignee_id を渡したり、退職者に作業指示書を割り当てたりすることがよくあります。

私の判断を大きく変える結論は、ツール スキーマにはビジネス セマンティック制約が含まれている必要があるです。

私のアプローチ:

• パラメータの説明に「assignee_id が現従業員であることを確認してください」などのルールを記述します。
• より根本的には、パラメータ レベルで列挙または検証正規表現を追加します。たとえば、assignee_id では数値のみが許可され、長さは 6 に固定されます。
• 「直属の部下にのみ割り当てられる」など、パラメーターが外部データに依存している場合は、検証のためにツール コードで最初にデータベースをチェックし、エージェントに推測させるのではなく、明確なエラーを返します。

修正前、私のスキーマには 5 行しかありませんでした。修正後は、各ツールの記述が平均 15 行に増加し、パラメータ検証が組み込まれました。代償としてコードの量が増えましたが、エージェント呼び出しの失敗率は 23% から 4% に低下しました。

2. 権限制御を「デフォルトの許可」から「明示的な拒否」に変更する必要があります。

多くのエージェント フレームワークのデフォルトでは、エージェントは登録されているすべてのツールを呼び出すことができます。初期の私にも同じことが起こりました。その結果、エージェントが自動的に「作業指示の削除」インターフェイスを呼び出し、テスト以外の作業指示を誤って削除してしまいました。

教訓: エージェントの権限の範囲は可能な限り小さくし、その後徐々に緩和する必要があります。

できること:

• 構成ファイルまたはデータベース テーブルを使用して、各エージェントが実行できる操作を明示的にリストします。
• ツールの登録フェーズでは、デコレータまたはミドルウェアを使用して権限チェックを実行します。たとえば、@require_permission('ticket:assign')。
• 危険な操作 (削除、金額の変更、外部通知の送信) の場合は、二次確認ステップを追加して、エージェントが「実行前」リクエストを生成できるようにします。このリクエストは手動確認後に実際に実行されます。

その後、リファクタリングに「権限リスト」オブジェクトを追加しました。このオブジェクトは、エージェントの起動時に読み込まれ、各ツール呼び出しの前に検証されました。この変更により、誤操作がゼロになります。ただし、ビジネスの役割が変わるため、権限リスト自体を定期的に監査する必要があることに注意してください。

3. ループは自然に消えることはありません。ループを積極的に検出して中断する必要があります。

前述の 37 回の再割り当てはループによって発生します。エージェントは、作業指示書のステータスが間違っていることに気づき、「再割り当てされるべきである」と考えました。割り当て後もステータスが変化しないため、割り当てを継続しました。

ループは、Agent Engineering の最も一般的な障害シナリオです。解決策は複雑ではありません。

• ステップ カウンター: エージェント実行の合計ステップ数を制限します (たとえば、最大 20 ステップ)。制限を超えた場合は強制終了し、中間結果が返されます。
• ステータス指紋検出: 各ステータスのスナップショットを記録します。重複したステータスが検出された場合、ループに閉じ込められ、ブレークポイントがトリガーされる可能性があります。
• 組み込みの重複排除ロジック: 一部のループは、エージェントが同じパラメーターでツールを繰り返し呼び出すことによって発生します。最近の呼び出し (最後の 5 つの呼び出しハッシュなど) をツール呼び出しレイヤーでキャッシュし、重複が見つかった場合は「実行済み、繰り返す必要なし」を返すことができます。

具体的な方法: 最新 10 件のステータス フィンガープリントのキューを維持するために LoopDetector クラスを作成しました。各ツール呼び出しの後、現在のステータスのハッシュが計算され、比較されます。繰り返し率がしきい値を超えると、中断して警告を出力します。このメカニズムがオンラインになった後、ループによって引き起こされる障害は 90% 減少しました。

4. MCP は諸刃の剣です。機能を拡張できるだけでなく、架空の依存関係を導入する可能性もあります。

MCP (モデル コンテキスト プロトコル) は、エージェントがデータベース、ファイル システム、Web API への接続などの外部コンテキストを取得するための優れた方法です。しかし、MCP を試してみたところ、エージェントは MCP で明確に記述されていないデータに依存することが多く、推論バイアスにつながることがわかりました。

典型的な問題: エージェントはユーザーの最近の注文リストを MCP から取得しますが、MCP から返されたデータにはキャンセルされた注文が混在しています。エージェントにはフィルタリングがなく、キャンセルされた注文のステータスをユーザーのアクティビティを判断する基礎として直接使用します。

私の教訓: MCP のデータには独自のフィルタリングと解釈が必要です。エージェントはデータ ソースが返すものをすべて使用します。エージェントがデータの信頼性を盲目的に推測することは望ましくありません。

解決策:

• MCP統合時に各データフィールドに「データソースの説明」と「有効期間」を追加します。
• データが返されると、「過去 1 時間以内に更新されました」、「キャンセルされた注文が含まれている可能性があります」などの「データ品質ラベル」が添付されます。 ・可能であれば、事前にツール機能でデータクリーニングを行ってください。たとえば、「ユーザー注文の取得」ツールは、キャンセルされた注文を内部的にフィルターで除外します。

これらの導入後、MCP に基づくエージェントの意思決定の精度は大幅に向上しました。ただし、MCP のデータを過剰に処理しないように注意してください。処理しすぎると、本当の問題が隠れてしまう可能性があります。

5. 産業連関比率が低下していることがわかったら、適切なタイミングで路線を変更する

すべての問題をエージェントが解決できるわけではありません。私のプロジェクトでは、このようなシナリオに遭遇しました。特定の作業指示書タイプのエージェントの処理を最適化するのに 2 週間を費やしましたが、精度は 80% から 82% に向上するだけでした。代わりに従来のルールと単純な分類モデルを使用すると、1 日で 95% に到達できます。

ルートを変更する時期かどうかを判断するにはどうすればよいですか?

• 限界利益: 各最適化による改善効果が 1% 未満で、コードの複雑さが急増する場合は、停止してください。
• 障害モード: エージェントの障害がランダムである場合 (たとえば、シナリオごとにエラーの原因がまったく異なる場合)、そのシナリオはエージェントに適していない可能性があり、代わりに決定論的な解決策を使用する必要があります。
• テスト容易性: 改善効果を検証するためのテスト ケースを構築することが難しい場合、問題が曖昧すぎる可能性があり、エージェントはただ運試しをするだけである可能性があります。

私の意思決定の原則: 主要な指標 (成功率など) が 3 回の反復以内に許容可能なレベルまで改善できない場合は、中止します。まず単純な解決策を使用して原因を解明し、その後、盲目的にプロンプ​​トを積み重ねるのではなく、根本原因の理解に時間を費やします。

投資を続けるのに適したシナリオは何ですか?

• タスクには明確なパターンがありますが、複雑なルールがあります (作業指示の分類や電子メールの返信など)。
• エージェントは独立して意思決定を行う必要がありますが、コンテンツの推奨や下書きの生成など、失敗のコストは制御可能です。
• エンジニアリング能力があり、ツールの定義、権限、サイクル検出を行うことができます。

いつルートを変更する必要がありますか?

• タスクは完全にランダムまたは不規則です (パターンのないユーザー入力など)。
• 金融取引や医療診断など、失敗のコストは非常に高くなります。
• 制御できない外部 API を統合するなど、エージェントの入出力形式を制御することはできません。

今すぐ始めたい場合、次のステップに従うのが最も価値があります。

実際だがリスクの低いタスク (内部作業指示の自動割り当てなど) を見つけて、まずエージェント構築プロセス全体 (ツールの登録、権限の設定、ループ検出の追加、10 のシナリオのテスト) を手動で完了します。次に、失敗データを記録します。完璧を目指す必要はありません。最初のバージョンはシンプルであるほど良いため、書き直すことになります。

このプロセス中に私が最も感じたことは、Agent Engineering の成功は、エージェントがどれほど賢いかではなく、エンジニアリング上の制約がどれほど厳格であるかにあるということです。