Agent Engineering はどのように機能しますか?実際のリンクで明確にします

このリンクは Notion の要件から始まります

実際のシナリオは次のとおりです。マイクロサービスを開発していて、既存のコード ベースにアラーム モジュールを追加する必要があります。タスクは Notion 上で記述され、要件分析からコードの提出までのプロセス全体の完了を支援するエージェントが必要です。

最初のステップはコードを書くことではなく、ツールを定義することです。 Notion ドキュメントの取得方法、コード ベースの検索ツール、ターミナル コマンドの実行権限、Git 操作インターフェイスをエージェントに伝える必要があります。各ツールは、パラメータ、戻り値、失敗処理を含む API 呼び出し宣言です。これは、Agent Engineering の最も基本的で見落とされやすいリンクです: ツール定義。

ツール定義が不完全な場合、エージェントは最初のレベルで停止します。たとえば、Notion API のみが指定され、認証トークンが指定されていない場合、エージェントは 3 回試行し、エラーで終了します。多くのチームは、この失敗の原因を「AIの能力不足」にあると考えています。実際、ツール層は固体ではありません。

コアループ: 計画、呼び出し、観察、調整

ツールの準備が完了すると、エージェントはコア ループを開始します。例として、先ほどのアラーム モジュール タスクを取り上げます。

1. 計画: エージェントは Notion の要件を読み取り、コード検索ツールを呼び出して現在のプロジェクト構造を見つけて、新しいファイルの作成、構成ファイルの変更、依存関係の追加などの実行計画を生成します。
2. ツールの呼び出し: まず git pull を実行して最新のコードを取得し、次に新しいファイルを作成します。ここで重要なのは、エージェントが特定のコマンドを生成し、システムがそれを実行のために端末に転送するということです。
3. 観察結果: ファイルが正常に作成された場合、端末はパスと権限情報を返します。失敗した場合 (ディレクトリが存在しないなど)、エラー コードが返されます。エージェントは観察に基づいて次のステップを調整する必要があります。
4. 調整: エージェントは、失敗した場合に再計画します。たとえば、最初にディレクトリを作成し、次にファイルを作成します。このプロセスは数回繰り返される場合があります。

このサイクルは単純に見えますが、失敗は細部に隠されています。最も典型的な間違いは、最初のツール呼び出しが成功した後、エージェントが自信過剰になり、検証をスキップして次のステップに直接進むことです。たとえば、ファイルを作成した後、内容が正しいかどうかを確認せずに、直接コードの整形を行った結果、空のファイルが整形されました。

コンテキストと MCP: エージェントを迷子にさせないでください

ループの場合、エージェントは自分が何をしているのかを覚えておく必要もあります。これは コンテキスト管理 です。

各ツール呼び出しの入力と出力はコンテキスト ウィンドウに書き込まれます。問題は、コンテキスト ウィンドウには GPT-4 の場合は 128,000 トークン、クロードの場合は 200,000 トークンという上限があることです。ループが 10 回を超えて実行されると、コンテキストが履歴ログでいっぱいになる可能性があります。この時点で、エージェントは「忘れ」始めます。元の要件を忘れたり、すでに完了した操作を繰り返したりする可能性があります。

解決策は MCP (モデル コンテキスト プロトコル) です。これは本質的にコンテキスト プルーニング戦略です。現在のステップに関連するシステム プロンプト、ツールの結果、および概要のみを保持し、無関係な詳細は破棄します。実装中に、スライディング ウィンドウや重要度スコアリングなどを通じてコンテキストの品質を制御できます。

たとえば、私の実践では、各サイクルでは最後の 5 回のツール呼び出しの結果のみが保持され、それ以降の結果は 1 文の要約に圧縮されます。これにより、エージェントは 30 ステップを超える複雑なタスクにおいて 90% 以上の精度を維持できます。

権限モデル: 最も見落とされやすい落とし穴

Agent Engineering と通常のプログラミングの最大の違いは次のとおりです。 エージェントに付与するのは操作権限であり、コード ロジックではありません。

次の 3 つの質問に答える必要があります。

• エージェントはどのファイル システム パスにアクセスできますか?
• エージェントはどのような端末コマンドを実行できますか (例: rm -rf を無効にする必要があります)?
• エージェントはどのような外部 API を呼び出すことができますか (たとえば、運用環境データベースは読み取り専用である必要があります)?

障害シナリオは非常に具体的です。チームはエージェントに npm publish の直接実行を許可し、その結果、デバッグ プロセス中に未完成のパッケージを npm 公式リポジトリに公開しました。この種の問題は、迅速なエンジニアリングでは解決できないため、ツールの権限レベルから制御する必要があります。

私のアプローチは、ツール定義内の各コマンドにセキュリティ ID をバインドし、ターミナルで実行する前に権限を確認することです。たとえば、ファイルの書き込みは /src および /tests ディレクトリでのみ許可され、コマンド ブラックリストには rm -rf、sudo、publish などが含まれます。

障害回復: ワークフローを中断しないでください

ツール定義、ループ、コンテキスト、権限があっても、エージェントは依然として失敗します。問題は、** が失敗した場合はどうすればよいかということです。 **

ほとんどの実装は例外をスローして停止します。しかし、実際の開発シナリオでは、さらに多くのことが必要になります。おそらく手動による介入と修正が必要であり、その後、エージェントがブレークポイントから続行できるようになります。

考えられる設計の 1 つは「チェックポイント モード」です。サブタスク (ファイルの作成、テストの通過など) が完了するたびに、現在の状態がディスクに保存されます。後続の手順でエージェントが失敗した場合は、このチェックポイントまで手動で復元し、問題を修正して、後続のプロセスを再起動できます。

もう 1 つは「明示的認可モード」です。エージェントは、自動的に解決できないエラー (API 認証の有効期限など) に遭遇した場合、やみくもに再試行するのではなく、一時停止して人間による入力を要求する必要があります。

たとえば、私のワークフローには「手動介入ゲート」があります。エージェントが同じ操作の実行に 2 回続けて失敗すると、システムは端末プロンプトをポップアップ表示し、開発者に新しい資格情報を入力するか、パスを変更するように求めます。開発者がターミナルに入力した後、エージェントは実行を継続します。

いつエージェントをやめるべきですか?

Agent Engineering の適用可能な境界は無限ではありません。手動コーディングまたは従来の自動化の方が適切な状況がいくつかあります。

• セキュリティに非常に敏感な操作: 運用環境の構成の変更や財務データの実際の注文の操作など。
• 人間の判断を必要とする決定: インターフェイスの設計、名前の競合解決など。
• 非決定的タスク: エージェントは、ランダム性 (自動生成されたパスワードなど) が含まれるワークフローや、複数回の手動承認が必要なワークフローには適していません。
• 超長サイクルタスク: 1 つのタスクが 1 時間または 200 ステップを超えており、現在のコンテキスト管理テクノロジーでは一貫性を維持することが困難です。

これらの境界外では、Agent Engineering の効果は大幅に低下します。たとえば、コードのリファクタリングを行う場合、エージェントはプロジェクト全体の暗黙的な依存関係を理解できないため、バグが発生する可能性があります。この時点で、手動リファクタリング + 単体テストという従来のアプローチに戻る必要があります。

実行可能チェックリスト

実際のプロジェクトで Agent Engineering を使用する場合は、練習後に洗練したリストを次に示します。

1. ツール定義の整合性チェック: 各ツールの入力/出力/エラー コードが宣言されていますか?
2. 最小限の権限: エージェントは、本当に必要なファイルとコマンドのみにアクセスできます。
3. コンテキスト プルーニング戦略: 最大保持ラウンド数 (5 ～ 10 ラウンドを推奨) を設定し、超過後に圧縮します。
4. 障害回復メカニズム: チェックポイント + 手動介入インターフェイス。
5. 監視ログ: バックトラッキングを容易にするために、すべてのツールの呼び出しと決定を記録します。
6. サンドボックスのテスト: 最初に隔離された環境で実行し、すべてが正しいことを確認してから、アクセス許可を解放します。

このリストは 1 回限りの構成ではなく完了していますが、各タスクの前に確認する必要があります。 「先週は問題なかった」という理由で権限チェックがスキップされ、その結果、エージェントが今週データベースを削除したというケースを私はあまりにも多く見てきました。

次のステップ: エージェント エンジニアになる

普通の開発者からエージェントエンジニアに変身したい場合は、この記事の次のステップとして、より体系的なオリジナルの有料記事または講座を受講する必要があります。このコースでは、ツール呼び出しプロトコルを設計する方法、エージェントのコンテキスト ウィンドウをデバッグする方法、実稼働レベルの障害回復システムを構築する方法を学びます。