エージェントワークフローのツール配線：パターンと落とし穴
エージェントワークフローを構築していますか？失敗の原因はモデルではないことがほとんどです。ツール配線、権限設定、オーケストレーションが本番環境で実際にどのように壊れるかを解説します。
先週、時間を数えた。5日間のスプリントで、エージェントパイプラインを配線していた——ツール7つ、外部API3つ、コードサンドボックス、ブラウザ自動化レイヤー——そのデバッグに費やした時間は約14時間だった。そのうち11時間が配線に費やされた。モデルではなく、プロンプトでもなく。モデルがツールを呼び出すと判断した瞬間から、そのツールが実際に正しい動作をするまでの空間に。
チームのSlackで誰かがこう尋ねた。「Dora、難しいのはプロンプトエンジニアリングじゃなかったの？」8ヶ月前はそうだった。今ではプロンプトは午後一つで完成する。ツールのディスパッチ、認証スコーピング、フェイルリカバリーを実際の負荷のもとで正常に動作させるのが、残りの週をすべて使う。
あなたのエージェントシステムがデモでは動くが本番で壊れる段階に達しているなら——ツールがサイレントにタイムアウトし、リトライループがトークン予算を食い尽くし、モデルが解釈できないパーミッションエラーが発生する——それが配線が真のエンジニアリング課題となる段階だ。この記事では、そのレイヤーで私がぶつかったパターンと障害モード、そしてシステムが回復するかスパイラルするかを決定した設計上の判断について記述する。
なぜツール配線が難しいのか
モデルがボトルネックになることはほとんどない。 私が追跡してきた本番環境の障害の多くは、LLMの推論に起因しない。モデルがツールを呼び出すと決定した後に起こること——ディスパッチ、認証ハンドシェイク、レスポンスのパース、エラー処理——に起因する。Anthropicのエフェクティブエージェント構築に関するエンジニアリングガイダンスはこの点を明確にしている：拡張されたLLMは単なる構成要素に過ぎない。難しいのはその周囲のすべてだ。
エージェントシステムにおける「配線」が実際に意味すること。 ツール配線は単に「APIを接続する」ことではない。それは全体的なサーフェスだ：ツールがどのように発見されるか、モデルにどのように説明されるか、ツールごとにパーミッションがどのようにスコープされるか、レスポンスがコンテキストウィンドウに戻される前にどのように検証されるか、そしてこれらのポイントのいずれかでの障害がセッションをクラッシュさせずにどのように処理されるか。Model Context Protocolの仕様はまさにこのレイヤーを標準化するために設計された——ツールの発見、呼び出し、結果のフォーマット——なぜならすべてのチームがそれを再発明していたからだ。
デモから本番への一般的な誤解。 デモではツールを3つ配線し、モデルが正しく呼び出し、魔法のように感じる。本番では、ツールが15個あると説明文が注意を奪い合うことに気づく。パラメータスキーマが異常に正確でなければ、モデルは引数を幻覚する。プロトタイプで実証された「ハッピーパス」は、実際の呼び出しの40%程度しかカバーしない。Anthropicのエージェント向けツール作成に関する最近の投稿では、ツールの説明への微妙な変更——例えばClaudeが検索クエリに「2025」を付加するかどうか——でもパフォーマンスが著しく低下する可能性があることを発見した。インターフェース設計はモデルと同じくらい重要だ。
本番ツールオーケストレーションにおけるコアパターン
静的 vs 動的ツールサーフェス。 静的ツールサーフェスとは、すべての呼び出しでモデルが同じツールセットを見ることを意味する。シンプルで、予測可能で、テストしやすい。動的サーフェスとは、セッションコンテキスト——ユーザーの役割、現在のワークフローステップ、すでに呼び出されたもの——に基づいてツールがロード、フィルタリング、または生成されることを意味する。動的サーフェスはより柔軟だが、デバッグが格段に難しい。私はハイブリッドで運用している：固定のコアセットとワークフロー状態によってゲートされた条件付きツールだ。
逐次 vs 並列ツールディスパッチ。 逐次ディスパッチは単純だ——ツールAを呼び出し、結果をパースし、ツールBを呼び出す。初期のエージェントシステムのほとんどはこの方法で動作する。並列ディスパッチは、モデルが複数のツール呼び出しを同時にリクエストする場合で、レイテンシを削減するが協調の複雑さが増す。LangGraphのオーケストレーションフレームワークはグラフベースの状態管理を通じて両パターンをサポートしており、実際のレイテンシの差は顕著だ——バッチ操作で3〜4倍のスピードアップを測定した。しかし並列ディスパッチは部分的な障害も処理する必要があることを意味する：ツールAが成功してツールBがタイムアウトした場合に何が起こるか？
ツールタイプごとのパーミッションゲーティング。 すべてのツールが同じリスクを持つわけではない。読み取り専用のデータベースクエリは、ファイルを削除したりメールを送信したりできるツールとは根本的に異なる。私はツールを3つの階層にゲートしている：読み取り専用（自動承認）、ロールバック付き書き込み（ログ記録あり、監査付き自動承認）、破壊的/外部（明示的な確認が必要）。NVIDIAのAI Red Teamが発表した実用的なサンドボックスガイダンスはこれをうまく整理している：必須のコントロールはネットワーク出力制限とワークスペース外へのファイル書き込みのブロックだ。それ以外はすべて二次的なものだ。
サンドボックスと分離戦略。 エージェントがコードを実行する場合、サンドボックスが必要だ。Dockerコンテナではない——コンテナはホストカーネルを共有しており、信頼されていないLLM生成コードには十分な分離ではない。本番環境のオプションはmicroVM（Firecracker、Kata Containers）、syscallインターセプション用のgVisor、または信頼されたコードのみに対する強化されたコンテナだ。私はほとんどのツール実行にgVisorを使用している。オーバーヘッドは許容範囲内だ。代替手段——LLM生成のbashコマンドがマウントされたボリュームでrm -rfを実行することを発見すること——はそうではない。
想定すべき障害モード
ツール呼び出しループと無限委任。 最もコストのかかる障害パターン。モデルがツールを呼び出し、エラーを受け取り、同じパラメータで同じ呼び出しを再試行し、同じエラーを受け取り、再試行する。リトライ予算が制限されていなければ、トークン上限またはAPI課金閾値に達するまでこれが続く。これは特に認証失敗で発生するのを見てきた——モデルは決して成功しないものを再試行し続ける。再試行可能 vs 再試行不可能なエラーを分類した上で、2〜3回の試行の制限されたリトライカウントが最低限だ。
出力の切り捨てによる下流ステップの破損。 コンテキストウィンドウを超えるツールレスポンスはサイレントに切り捨てられる。モデルは不完全なデータに気づかずに推論する。これは大きな結果セットを返すデータベースクエリで特に厄介だ。私は今、すべてのツールレスポンスに厳格なトークン上限——最大25,000トークン——を適用し、結果が切り捨てられた場合は明示的なページネーションシグナルを返している。
セッション中の認証期限切れ。 長時間実行されるエージェントセッションはOAuthトークンの有効期限を超える可能性がある。ツールは最初の1分では正常に動作した。47分後、トークンが期限切れになり、その後のすべてのツール呼び出しが失敗する。モデルはなぜかわからない。ここにはまだエレガントな解決策がないと思う——私の現在のアプローチはディスパッチ前にトークンの期限切れを事前チェックして積極的にリフレッシュすることだ。
ガードレールなしの破壊的コマンド。 シェル実行またはファイルシステムツールにアクセスできるモデルは、時折破壊的なコマンドを生成することがある。悪意からではなく——単に誤って。AWSのワークフローオーケストレーションエージェントに関するプレスクリプティブガイダンスは、ワーカーエージェントごとに実行状態を追跡し、本番システムに影響するものについては承認ゲートを実装することを推奨している。同意する。書き込み、削除、または送信できるツールには明示的な確認ステップが必要だ。
ツール呼び出し全体でのレート制限カスケード。 1つのツールがレート制限に達すると、モデルはすぐに再試行しようとする。または同じ基盤APIに達する別のツールを呼び出す。カスケード効果により、数秒でツール全体のレート制限が飽和する可能性がある。ツールエンドポイントごとのジッター付き指数バックオフが基本だ——モデルごとではなく、ツールごとに。
リカバリーとレジリエンスのパターン
指数バックオフによるリトライロジック。 1秒から始め、リトライごとに倍にし、60秒でキャップし、ランダムジッターを追加する。これはオプションではない。ジッターがなければ、並列セッションが同時にリトライしてサンダリングハード効果を生み出す。まずエラーを分類する：レート制限と5xxエラーはリトライする。認証失敗と検証エラーはしない——間違ったAPIキーはいくらリトライしても直らない。一時的なエラーには2〜3回のリトライ。再試行不可能なものにはゼロ。
チェックポイントとコンパクション戦略。 複数のコンテキストウィンドウにわたって作業する長時間実行エージェントは、進捗を永続化する方法が必要だ。Anthropicのエンジニアリングチームはこれを長時間実行エージェントのための効果的なハーネスに関する作業でドキュメント化した——重要な洞察は、進捗ファイルをgit履歴と並行して使用することで、新しいコンテキストウィンドウがすでに完了したことを素早く再構築できるようにすることだ。私は同様のパターンを採用した：コンパクション前に、エージェントは完了したステップ、保留中のステップ、既知の障害をまとめた構造化されたチェックポイントを書き込む。次のコンテキストウィンドウは推測する代わりにそのファイルを読むことから始まる。
ツールが利用できない場合のグレースフルデグラデーション。 データベースコネクタがダウンした場合、エージェントはクラッシュすべきではない。障害を認識し、そのステップをスキップし、できることを継続するか——または完了できなかったことをユーザーに伝えるべきだ。これには、ツールサーフェスをワークフロー全体のハード依存性がない単一ツールになるよう設計する必要がある。フォールバックチェーンが役立つ：プライマリツールが失敗したら、より安価またはシンプルな代替が実行される。モデルの指示には、ツールがデータを返さない場合に何をすべきかを明示的にカバーすべきだ。
エージェントインフラの評価
ビルド vs 購入：独自のハーネスをいつ構築するか。 ワークフローが予測可能な入力を持つ3〜4ツールの線形チェーンであれば、カスタムハーネスは1日で構築でき、フレームワークよりも保守が容易だ。動的ルーティング、並列ディスパッチ、セッション間の状態永続化、ヒューマンインザループのチェックポイントが必要な場合、ゼロから構築するには数ヶ月かかる。そのときにLangGraphなどのフレームワークや管理プラットフォームが役立つ。私はカスタムから始めた。3回目に状態チェックポイントを再実装した後で移行した。
本番対応性の主要なシグナル。 これらに答えられるか：ツール呼び出しがタイムアウトした場合に何が起こるか？ツール呼び出しのログはどこに保存され、クエリできるか？有効なJSONだが意味的に間違っているツールレスポンスをシステムはどのように処理するか？失敗したセッションをチェックポイントから再生できるか？これらの質問のいずれかで立ち止まるなら、システムは本番対応ではない。
スケールアップ前にベンチマークすべきこと。 負荷下でのツール呼び出しあたりのレイテンシ。ツールタイプごとのエラー率。セッションあたりのトークン消費量（ツールレスポンスは主要なドライバーだ）。現在のトラフィックの2倍でのレート制限ヘッドルーム。私はトークン消費量メトリクスを数週間無視し、実際に測定したときにショックを受けた——ツールレスポンスが総トークン支出の60%を占めていた。
FAQ
エージェントAIシステムにおけるツール配線とは何か？
ツール配線とは、LLMと呼び出せる外部ツールとの間の完全な統合レイヤーを指す——ツールの発見、スキーマ定義、パーミッションスコーピング、ディスパッチロジック、レスポンスパース、エラー処理を含む。これは、モデルが「関数を呼び出す」という決定が、実際に正しい関数が正確に呼び出されるかどうかを決定するインフラだ。Model Context Protocolは、異なるLLMアプリケーション間でこのレイヤーを標準化するために作成された。
エージェントワークフローで破壊的なコマンドを防ぐにはどうすればよいか？
ツールをリスクレベルで階層化する。読み取り専用の操作は自動承認できる。書き込み操作はロールバック機能付きでログに記録すべきだ。破壊的な操作——データを削除したり、外部通信を送信したり、本番状態を変更したりするもの——は明示的な人間の確認が必要だ。これをサンドボックス（コード実行にはgVisorまたはmicroVM）と、デフォルトで任意のアウトバウンド接続をブロックするネットワーク出力コントロールと組み合わせる。
本番環境でツール呼び出しの失敗を処理する最善の方法は何か？
エラーを再試行可能（レート制限、タイムアウト、5xx）と再試行不可能（認証失敗、検証エラー、パーミッション拒否）に分類する。再試行可能なエラーには、2〜3回の試行でキャップしたジッター付き指数バックオフを適用する。再試行不可能なエラーには、モデルがアプローチを調整するか——またはユーザーにエスカレートできるように、明確なエラーメッセージを返す。これに、ツールが一貫して失敗していることを検出してその周りをルーティングするサーキットブレーカーを重ねる。
マルチツールエージェントでパーミッション管理はどのように機能するか？
各ツールには定義されたパーミッションスコープが必要だ：何にアクセスできるか、どのアクションを実行できるか、どのデータを返せるか。本番環境では、これはセッションごとの短命な認証情報（共有サービスキーではない）、ディスパッチ前の明示的な機能チェック、すべてのツール呼び出しの監査ログを意味する。原則は最小権限だ——テキスト分析を行うエージェントにはファイルシステムへの書き込みアクセスは必要ない。
管理されたエージェントレイヤーを使用すべきか、独自に構築すべきか？
ユースケースが予測可能な逐次実行を持つ5つ未満のツールを含む場合は、独自に構築する——デバッグと保守が速い。動的ルーティング、並列実行、状態永続化、ヒューマンインザループゲート、またはマルチエージェント協調が必要になったら、カスタムインフラの構築と保守のエンジニアリングコストがフレームワークの学習曲線を上回る。決定的な要因は通常、状態管理だ：セッションがプロセスの再起動を生き延びる必要がある場合、スクリプトではなくインフラが必要だ。
パーミッションゲーティングモデルはまだ調整中だ。3つの階層では細かくないかもしれない——一部の書き込み操作は自動承認すべき（ログファイルへの追記）と感じられる一方で、他は明らかにそうすべきでない（顧客レコードの更新）。ワークフローが複雑になるにつれて、その境界は移動し続けている。続きはまた。
過去の投稿：
