前のページでは、スキルが再利用可能なドメインの専門知識 (命令、参照資料、スクリプト) を自己完結型ユニットにパッケージ化し、任意のエージェントがオンデマンドで読み込むことができる方法を示しました。 ただし、エージェントを運用環境にデプロイすると、新しいカテゴリの問題が発生します。エージェントの機能に関係なく 、すべての 対話を切り取る問題です。
すべての要求と応答をログに記録する必要があります。 モデルが見る前に有害なコンテンツをブロックするガードレールが必要です。 エージェントのコア ロジックに触れることなく、レート制限を適用し、例外を適切にキャッチし、テレメトリを挿入する必要があります。 これらの懸念事項をすべてのエージェント (またはすべてのツール、またはすべてのスキル) にコピー貼り付けしても、スケーリングが行われず、メンテナンスの悪夢が生じません。
ミドルウェア はこれを解決します。 ミドルウェアを使用すると、適切に定義されたポイントで要求と応答をインターセプト、検査、変更する再利用可能な動作でエージェントの 実行パイプライン をラップできます。 ミドルウェアはエージェントの周りの一連の同心円レイヤーと考えてください。各レイヤーは、エージェントに到達する前に入力に作用し、呼び出し元に到達する前に出力に作用する機会を得ます。
使用タイミング
次の場合に、ミドルウェアをエージェントに追加します。
- モデルが処理する前または後に、有害なコンテンツ、トピック外コンテンツ、またはポリシー違反コンテンツをブロックするには、 ガードレール が必要です。
- 各エージェントを個別に変更することなく、すべてのエージェントの対話に対して 一元的なログ記録またはテレメトリ が必要です。
- エージェント ロジックを変更せずに、 要求または応答 (プロンプトの強化、出力の変換、または結果全体の置換) を変更する必要があります。
- すべての実行に適用されるレート制限、コンテンツ フィルター、認証チェックなどの ポリシーを適用 する必要があります。
- 例外を一貫して 処理 する必要があります。一時的な障害の再試行、グレースフル フォールバック応答の返し、または診断のエラーのログ記録を行います。
- パイプライン全体で 状態を共有 する必要があります。たとえば、要求のタイミングの追跡や、複数のミドルウェア コンポーネントに必要なメトリックの蓄積などです。
ヒント
Agent Framework には、トレースとメトリックのための組み込みのインストルメンテーションが含まれています。 詳細については 、「可観測性」 を参照してください。
ミドルウェア パイプラインのしくみ
エージェントの実行メソッドを呼び出しても、要求はモデルに直接移動しません。 代わりに、ミドルウェア レイヤーのパイプラインを通過します。各レイヤーは、要求を検査または変更し、次のレイヤーに委任し、戻る途中で応答を検査または変更できます。
┌─────────────────────────────────────────────────────────┐
│ Caller: agent.run("What's the weather?") │
└──────────────┬──────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────┐
│ Middleware 1 (Logging) │
│ • Logs the incoming request │
│ • Calls next middleware │
│ • Logs the outgoing response │
└──────────────┬──────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────┐
│ Middleware 2 (Guardrails) │
│ • Checks input against content policy │
│ • If blocked → returns early with rejection message │
│ • If allowed → calls next middleware │
│ • Checks output against content policy │
└──────────────┬──────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────┐
│ Agent core (model invocation, tool calls, etc.) │
└─────────────────────────────────────────────────────────┘
重要なポイント:
- 各ミドルウェアは、続行するかどうかを決定します。 ミドルウェアは、チェーン内の次のレイヤーを呼び出して正常に続行するか、応答を直接返すことによってパイプラインをショートサーキットできます (たとえば、ガードレールが要求をブロックした場合)。
- ミドルウェアは双方向を見る。 ミドルウェアは、(入力を検査または変更するために) 委任する 前 にコードを実行し、応答が返された 後 (出力を検査または変更するため) します。 これは古典的な"玉葱"パターンです。
- 複数のミドルウェアが一緒にチェーンされます。 複数のミドルウェア コンポーネントを登録すると、それらが入れ子になります。最初に登録されたミドルウェアは最も外側のレイヤー、最後に登録されたミドルウェアはエージェントに最も近い最も内側のレイヤーです。
ヒント
ミドルウェアが完全なエージェント実行パイプライン (コンテキスト プロバイダーやチャット クライアント レイヤーを含む) にどのように適合するかの詳細なビューについては、 エージェント パイプラインのアーキテクチャを参照してください。
ミドルウェアでできること
Agent Framework では、パイプラインの 3 つのレイヤー (エージェントの実行、関数呼び出し、チャット クライアント) でミドルウェアがサポートされており、実行をインターセプトする場所をきめ細かく制御できます。 一般的なパターンは次のとおりです。
| パターン | 例 | リファレンス |
|---|---|---|
| ガードレール & ターミネーション | 有害なコンテンツをブロックし、会話の長さを制限する | ターミネーションとガードレール |
| 例外処理 | 一時的な障害時に再試行し、フォールバック応答を返す | 例外処理 |
| 結果のオーバーライド | 機密データの編集、エージェント出力のエンリッチまたは置換 | 結果の上書き |
| 共有状態 | ミドルウェア間で要求 ID またはタイミング データを渡す | 共有状態 |
| ランタイム コンテキスト | セッション、ユーザー、または実行ごとの構成に基づいて動作を変更する | ランタイム コンテキスト |
| スコープ設定 | すべての実行または単一の実行にミドルウェアを適用する | エージェントと実行スコープ |
ミドルウェアの定義と登録の完全なチュートリアルについては、「ミドルウェアの 定義」を参照してください。 アーキテクチャの概要については、「 ミドルウェアの概要」を参照してください。
考慮事項
| 考慮事項 | 詳細情報 |
|---|---|
| 懸念事項の分離 | ミドルウェアは、クロスカットのロジックをエージェントコード、ツール、およびスキルから排除します。 各ミドルウェア コンポーネントには、個別に追加、削除、または並べ替えを行うことができる、ログ記録、ガードレール、エラー処理という 1 つの責任があります。 |
| 順序依存 | ミドルウェアはチェーンを形成します。 ミドルウェアを登録する順序は重要です。最初に実行されるログ ミドルウェアには生の入力が表示され、最後に実行されたミドルウェアには、以前のミドルウェアによって既に変更された入力が表示されます。 パイプラインの順序を意図的に計画します。 |
| デバッグの複雑さ | ミドルウェアが入力または出力を変更する場合、デバッグには完全なパイプラインを理解する必要があります。 応答は、エージェントのためではなく、ミドルウェアによって変換されたために間違って見える可能性があります。 優れたログミドルウェアが（チェーンの初期段階において）これらのケースを診断するのに役立ちます。 |
| パフォーマンスのオーバーヘッド | 各ミドルウェア レイヤーは、すべての要求に処理時間を追加します。 ログ記録などの軽量操作の場合、これはごくわずかです。 外部コンテンツ モデレーション API の呼び出しなどの負荷の高い操作では、待機時間が増加します。特に、このようなミドルウェアが複数チェーンされている場合です。 |
次のステップ
エージェントにツール、スキル、ミドルウェアが用意されたので、次の手順は コンテキスト プロバイダー です。各実行前に、メモリ、ユーザー プロファイル、動的知識をエージェントのコンテキスト ウィンドウに挿入するコンポーネントです。
より深く進む:
- ミドルウェアの概要 - すべてのミドルウェアの種類の完全なリファレンス
- エージェント パイプライン アーキテクチャ - ミドルウェアが実行パイプラインにどのように適合するか