Dokumentation

MCP Fusion/Core concepts/FSM-State-Gating

FSM-State-Gating

Frag die KI über Vinkius

Zeitliche Anti-Halluzination: Binden Sie Tools an Workflow-Zustände, damit eine Aktion außerhalb der Reihenfolge physisch aus der Tool-Liste verschwindet, statt nach dem Versuch des Agenten abgewiesen zu werden.

Die teuerste Halluzination in einem Agenten-Workflow ist kein falscher Wert, sondern der Aufruf von Schritt vier vor Schritt drei. Der Agent sieht ein Tool, ruft es auf, der Server weist es zurück und der Turn ist verloren. MCP Fusion entfernt den Schritt stattdessen aus dem Menü.

Ein Tool an einen Zustand binden

typescript
export default f.action('invoice.discharge')
  .describe('Discharge an approved invoice')
  .bindState('approved', 'DISCHARGE')
  .handle(async (input, ctx) => discharge(input.id));

bindState(states, transition) bedeutet: Dieses Tool erscheint in tools/list nur, solange sich der Workflow in einem der angegebenen Zustände befindet, und löst bei einem erfolgreichen Aufruf transition aus. Die Zustände stammen aus einer Maschine, die Sie einmal konfigurieren:

typescript
const fsm = f.fsm({
  id: 'invoice',
  initial: 'draft',
  states: {
    draft: { on: { SUBMIT: 'review' } },
    review: { on: { APPROVE: 'approved', REJECT: 'draft' } },
    approved: { on: { DISCHARGE: 'discharged' } },
    discharged: { type: 'final' },
  },
});

Die Form ist mit XState v5 kompatibel. XState ist ein optionaler Peer: Ist es installiert, führt das Gate einen echten Actor aus. Ohne XState steuert das Gate eine integrierte manuelle Transition-Tabelle, sodass sich die Funktion elegant verschlechtert, statt den Start zu verhindern.

Was der Agent erlebt

  • In draft steht invoice.discharge nicht in der Liste. Der Agent kann nicht aufrufen, was er nicht sieht.
  • Beim Tool, das zu approved führt, bewegt der erfolgreiche Aufruf die Maschine und der Server sendet notifications/tools/list_changed.
  • Der Client aktualisiert die Liste, und nun erscheint invoice.discharge mit seiner eigenen Beschreibung.

Das ist stärker als eine Guard: Eine Guard weist nach dem Versuch zurück, Gating entfernt die Versuchung. Validierungsfehler zur Reihenfolge verschwinden aus Ihren Logs, weil der Reihenfolgekonflikt nicht ausgedrückt werden kann.

Gating wird auch auf dem Aufrufpfad erzwungen, nicht nur in der Liste. Ein Client, der einen Tool-Namen errät, erhält weiterhin FORBIDDEN mit den erlaubten Aktionen. Sicherheit hängt daher nie davon ab, dass der Client sein Menü aktualisiert.

Progressive Offenlegung im Schema

Ein FSM-gebundener Connector kann auch seinen eigenen Kontext verkleinern. compactDescription() gibt einem Tool eine kurze Beschreibung, solange sich die Maschine im Anfangszustand befindet, und .describe() liefert in späteren Zuständen die vollständige Beschreibung. Das Agentenmenü in draft ist kleiner und klarer als dasselbe Tool in approved, ohne eine zweite Bereitstellung.

Serverless- und zustandsloser Zustand

Eine Zustandsmaschine ist dauerhafter Zustand, aber zustandslose MCP-2.0-Transporte haben keine Sitzung, an die sie ihn hängen können. Drei Mechanismen decken das ab:

  1. stateHandleKey: Der Tool-Aufruf kann ein explizites Handle-Argument enthalten, das das Modell zurückgibt, das von der Spezifikation empfohlene Muster für zustandslose Abläufe
  2. Sitzungs-ID: Wenn der Transport eine besitzt (Mcp-Session-Id), speichert das Gate den Zustand pro Sitzung
  3. Fallback pro Attachment: Ein Single-Tenant-Server ohne beide Schlüssel verwendet eine In-Process-Identität

Persistenz ist eine FsmStateStore-Schnittstelle, die Sie implementieren:

typescript
interface FsmStateStore {
  load(handle: string): Promise<{ state: string; updatedAt: string } | undefined>;
  save(handle: string, snapshot: { state: string; updatedAt: string }): Promise<void>;
}

Verwenden Sie den In-Memory-Store für einen einzelnen Prozess oder hinterlegen Sie ihn in Redis, DynamoDB, einem Edge-KV oder einer Datenbankzeile. Das Framework klont und restauriert das Gate pro Anfrage, sodass gleichzeitige Anfragen nie versehentlich eine Maschine teilen.

Wann Sie es einsetzen sollten

  • Freigabe- und Review-Workflows, nichts darf vor der Freigabe entladen werden
  • Zahlung und Fulfillment, erfassen Sie nach der Autorisierung, niemals vorher
  • Mehrstufige Migrationen und destruktive Wartungsfenster
  • Alles, bei dem eine falsche Reihenfolge Geld oder Daten kostet und ein abgewiesener Aufruf trotzdem einen Turn kostet

FSM-Gating lässt sich mit der Tool-Exposition kombinieren, da sich die sichtbare Oberfläche mit dem Zustand ändert, und mit Routing, da zustandsgebundene Tools in eigenen Dateien liegen. Die Handler ändern sich nicht: Sie wurden immer für einen Zustand der Welt geschrieben.

Nächste Schritte