Swarmによるフェデレーテッドハンドオフ

1 つのコネクタがすべてのドメインを担当する必要はありません。MCP Fusion Swarm は Federated Handoff Protocol を実装します。ゲートウェイはライブセッションを金融、サポート、データの専門エージェントへ移し、そのエージェントのツールを書き換えた名前空間で公開し、意図を失わずにセッションを戻せます。

ハンドオフはレスポンスです

ゲートウェイのツールは、ドメイン全体を自分でプロキシしようとせず、ハンドオフを示すレスポンスを返します。

import { handoff } from '@mcpfusion/core';

export default f.action('triage.route')
  .describe('Route the request to the right specialist')
  .handle(async (input) => {
    return handoff(`mcp://${input.domain}-agent`, {
      carryOverState: { intent: input.context },
      reason: `Triage to ${input.domain}`,
      modelHint: 'balanced',
    });
  });

レスポンスには _MCPFUSION_handoff が付くため、サーバーアタッチメントが認識してゲートウェイのハンドオフ経路を有効化します。通常のツールエラーでも HTTP リダイレクトでもありません。

ゲートウェイ

import { SwarmGateway } from '@mcpfusion/swarm';

const gateway = new SwarmGateway({
  registry: {
    finance: 'http://finance-agent:8081',
    support: 'http://support-agent:8082',
  },
  delegationSecret: process.env.MCPFUSION_DELEGATION_SECRET!,
  gatewayName: 'triage',
  tokenTtlSeconds: 60,
  connectTimeoutMs: 5_000,
  idleTimeoutMs: 300_000,
  maxSessions: 100,
});

レジストリは専門エージェント名を upstream URL に対応付けます。ゲートウェイは upstream トランスポートとして auto、http、sse を使用でき、タイムアウトと最大セッション数で接続を制限します。activateHandoff、proxyToolsList、proxyToolsCall、returnToGateway、hasActiveHandoff、isConnecting、sessionCount、connectingCount、dispose が運用 API を構成します。

署名付き委任

ゲートウェイと専門エージェントは秘密情報を共有します。mintDelegationToken(scope, ttlSeconds, secret, issuer, carryOverState, store, traceparent) は HMAC 委任トークンを作成します。クレームには発行者、サブジェクト、発行時刻、有効期限、対象 ID、オプションの状態、traceparent が含まれます。専門エージェントは次のようにツールを保護します。

import { requireGatewayClearance } from '@mcpfusion/core';

registry.attachToServer(server, {
  middleware: [requireGatewayClearance(process.env.MCPFUSION_DELEGATION_SECRET!)],
});

verifyDelegationToken は有効期限、署名、スコープを検証します。失敗は HandoffAuthError として型付けされ、トークンの欠落、無効なトークン、期限切れのトークン、無効な署名が含まれます。これは共有秘密によるフェデレーションであり、公開ディスカバリープロトコルではありません。秘密情報をローテーションし、upstream へのネットワークアクセスを制限し、トークンの有効期間を短くしてください。

名前空間の分離

upstream がゲートウェイのツールを密かに上書きすることはできません。NamespaceRewriter はリストをプロキシするときに専門エージェントの名前へプレフィックスを付け、upstream へ戻すときにプレフィックスを外します。プレフィックスが正しくない名前では NamespaceError が発生します。そのためモデルにはどのドメインが機能を所有するかが見え、専門エージェントには元のアクション名が渡されます。

ゲートウェイは安全な復帰ツールも注入します。injectReturnTripTool(tools, gatewayName) は triage への復帰ルートを追加し、formatSafeReturn(summary, domain) は復帰ペイロードを限定的で明確なものに保ちます。

引き継ぎ状態とクレームチェック

小さな意図の状態は委任クレーム内を移動します。大きな状態は移動しません。クレームサイズの上限を超えると、Swarm は状態を HandoffStateStore に保存し、トークンには参照を入れます。組み込みの InMemoryHandoffStateStore は開発用です。本番では、どのゲートウェイインスタンスからでもクレームチェックを取得できる共有ストアが必要です。

トレースコンテキストは traceparent に引き継がれるため、各専門エージェントが独自の MCP サーバーを持っていても、サービス間でハンドオフを追跡できます。

障害境界

• 接続タイムアウト: ゲートウェイは upstream が利用できないことを報告し、無条件に再試行しません
• アイドルタイムアウト: 非アクティブなハンドオフを閉じてセッションを解放します
• 名前空間の不一致: ゲートウェイは誤ったドメインからのツールレスポンスを拒否します
• 無効な委任: ハンドラーが呼び出しを見る前に専門エージェントが失敗します
• upstream からの復帰: ゲートウェイは以前のルートを復元し、安全な復帰経路を注入します

Swarm はプロトコルとプリミティブを提供します。サービスディスカバリー、共有シークレット保管庫、汎用的な分散状態ストアは提供しません。これらはデプロイ時の判断として残ります。

次のステップ

• Authentication: ゲートウェイと専門エージェントのツールを保護
• MCP 2.0 compliance: 通知とトランスポートの詳細
• A2A bridge: MCP Fusion エージェントを A2A クライアントに公開