LangGraph zu AgentCore migrieren – der Wrapper ist erst der Anfang

Ein bestehender LangGraph-Agent lässt sich ohne sofortigen Umbau des Graphen in Amazon Bedrock AgentCore Runtime ausführen: Die AWS-Dokumentation zur LangGraph-Integration verbindet eine BedrockAgentCoreApp über eine Entry-Point-Funktion mit graph.invoke und gibt das Ergebnis des Graphen zurück. Dieser Wrapper belegt aber nur, dass der Agent in der neuen Laufzeit startet; für den Produktivbetrieb müssen Zustand, Identitäten, Tool-Zugriffe, Fehlerbehandlung, Telemetrie und Kapazität separat abgesichert werden.

Der belastbare Migrationspfad hat deshalb zwei Etappen: Zuerst läuft die vorhandene Entscheidungslogik parallel zum alten Runtime-Pfad in AgentCore. Erst nachdem Sitzungen dauerhaft fortgesetzt, Berechtigungen geprüft, Fehler kontrolliert und Lastgrenzen gemessen wurden, wird der Verkehr schrittweise umgeschaltet; bis dahin bleibt der bisherige Pfad als Rückfalloption verfügbar.

1. Eine Referenz schaffen und nur die Laufzeit wechseln

Fixieren Sie zunächst die bestehende Version des Agenten samt Modellkonfiguration, Prompts, Tools und Abhängigkeiten. Zeichnen Sie für einen repräsentativen Testsatz auf, welche Tools mit welchen Argumenten aufgerufen werden, welchen Endzustand der Graph erreicht und welcher Antworttyp entsteht. Bei probabilistischen Modellen ist semantische Gleichwertigkeit wichtiger als identischer Wortlaut; unverändert bleiben müssen jedoch erlaubte Aktionen und fachliche Grenzen.

Der erste AgentCore-Pfad sollte möglichst wenig neue Logik enthalten: Payload prüfen, den kompilierten Graphen aufrufen und ein versioniertes Antwortobjekt liefern. Das offizielle AWS-Migrationsbeispiel lässt in seiner ersten Migrationsstufe Graph, Router, Prompts und Tool-Implementierungen unverändert, warnt aber ausdrücklich davor, die demonstrierten Sicherheits-, Fehler- und Größenkonfigurationen ungeprüft produktiv einzusetzen.

Validieren Sie leere, fehlende und falsch typisierte Eingaben bereits am Entry Point. Halten Sie neue Routingregeln aus dem Wrapper heraus: Wenn Laufzeit und Agentenverhalten gleichzeitig verändert werden, lässt sich eine Abweichung später nicht eindeutig dem Hosting, dem Modell oder dem Graphen zuordnen. Initialisieren Sie den Graphen außerdem nicht unnötig für jeden Aufruf neu, wenn dabei Modell-Clients oder langlebige Tool-Verbindungen erneut aufgebaut werden.

2. Sitzungszustand dauerhaft und eindeutig abbilden

Ein In-Memory-Checkpointer reicht nach dem Umzug nicht aus. Sein Inhalt ist an einen Prozess gebunden; eine andere Instanz kann die Unterhaltung nicht fortsetzen, und ein Neustart beendet den gespeicherten Kontext. Ordnen Sie deshalb die bisherige LangGraph thread_id einer stabilen Session-ID und, falls der Speicher mehrere Nutzer trennt, einer eindeutigen Actor-ID zu.

Trennen Sie Daten nach Lebensdauer. Zwischenergebnisse eines einzelnen Aufrufs können flüchtig bleiben, während Gesprächsverlauf und benötigte Checkpoints in AgentCore Memory oder einem bereits etablierten dauerhaften Store liegen müssen. Nutzerpräferenzen gehören nur dann in einen sitzungsübergreifenden Speicher, wenn Zweck, Zugriffsgrenze, Aufbewahrung und Löschung festgelegt sind.

Während der Übergangsphase kann ein Kompatibilitätsadapter alte und neue Schlüssel lesen, sollte aber ausschließlich das neue Format schreiben. Prüfen Sie die Wiederaufnahme durch eine andere Instanz, parallele Gespräche desselben Nutzers, doppelt zugestellte Requests und zwei gleichzeitige Aufrufe derselben Sitzung. Legen Sie für Konflikte eine eindeutige Strategie fest, statt sich auf die Reihenfolge der Verarbeitung zu verlassen.

3. Identitäten, Tools und Fehlergrenzen trennen

Behandeln Sie drei Identitäten getrennt: den aufrufenden Menschen oder Dienst, die Ausführungsrolle der Runtime und die Identität gegenüber dem Zielsystem eines Tools. Die Runtime-Rolle erhält nur die benötigten IAM-Aktionen auf die erforderlichen Ressourcen. Wenn ein Tool im Namen eines Nutzers arbeitet, darf eine gemeinsame technische Rolle dessen Berechtigungsgrenze nicht ersetzen; Authentifizierung, Autorisierung und Erneuerung delegierter Tokens gehören dann in den Aufrufpfad.

Nicht jedes Tool muss bei der ersten Etappe hinter AgentCore Gateway verschoben werden. Gemeinsam genutzte oder privilegierte Werkzeuge profitieren von einem zentral kontrollierten Pfad, während eine ausschließlich intern verwendete Funktion zunächst im Agentenprozess bleiben kann. In beiden Fällen benötigt das Tool validierte Argumente, ein Zeitlimit, begrenzte Wiederholungen und eine maschinenlesbare Fehlerantwort.

Unterscheiden Sie Validierungs-, Berechtigungs-, Drosselungs-, Timeout- und interne Fehler. Automatische Wiederholungen sind nur für idempotente Operationen sicher; schreibende Vorgänge benötigen gegebenenfalls einen Idempotenzschlüssel. Andernfalls kann ein erneuter Modell- oder Runtime-Aufruf Bestellungen, Rückgaben oder Nachrichten doppelt auslösen.

4. Telemetrie und Lastgrenzen vor dem Umschalten prüfen

Korrelieren Sie jeden Request mit Session-ID, Runtime Request ID und den notwendigen fachlichen Kennungen. Die AgentCore-Runtime-Telemetrie umfasst unter anderem Aufrufe, Drosselungen, Fehler, Latenz und aktive Sitzungen sowie CPU- und Speichernutzung; aktivierbare Spans enthalten Request-, Session- und Endpoint-Bezüge. Die dokumentierte Ressourcentelemetrie kann verzögert eintreffen und ist deshalb kein Ersatz für unmittelbar wirkende Schutzmechanismen.

Ergänzen Sie die Plattformmetriken um Tool-Fehler, abgebrochene Streams, Zustandskonflikte und fachliche Ergebnisse eines festen Evaluationssatzes. Request- und Response-Payloads können in Anwendungslogs erscheinen; prüfen Sie deshalb vor der Aktivierung, welche Inhalte protokolliert, maskiert, aufbewahrt und gelöscht werden dürfen.

Ein aussagekräftiger Lasttest bildet reale Gesprächslängen, parallele Sitzungen, große Zustände, langsame Tools und Fehlerbursts ab. Daraus folgen Grenzen für Parallelität, Timeouts, Backoff und gegebenenfalls Quotenanpassungen. Testen Sie auch, ob eine überlastete Abhängigkeit kontrolliert bis zum Client signalisiert wird, statt weitere Wiederholungen auszulösen.

5. Verkehr mit einem getesteten Rückfallweg umschalten

Betreiben Sie alten und neuen Runtime-Pfad zunächst nebeneinander. Schattenverkehr eignet sich nur für lesende oder zuverlässig simulierte Tool-Aufrufe; produktive Schreibaktionen dürfen dabei nicht ein zweites Mal ausgeführt werden. Anschließend erhält AgentCore einen begrenzten Anteil echter Sitzungen, wobei jede aktive Sitzung für ihre gesamte Lebensdauer demselben Pfad zugeordnet bleibt.

Definieren Sie vorab Abbruchschwellen für technische Fehler, Latenz, Tool-Erfolg und fachliche Qualität. Der Umschalter sollte vor beiden Laufzeiten liegen und ohne neuen Build auf den alten Pfad zurückstellen können. Halten Sie dessen Konfiguration und notwendige Speicherleserechte verfügbar, bis alte Sitzungen beendet oder kontrolliert in das neue Zustandsmodell übernommen wurden.

Vor der vollständigen Umschaltung sollten folgende Prüfpunkte erfüllt sein:

• Der unveränderte Graph besteht die vereinbarten Paritäts- und Regressionstests.
• Session- und Actor-IDs führen eindeutig zum richtigen Nutzer und Speicherstand.
• Erlaubte und verweigerte IAM-, Nutzer- und Tool-Zugriffe wurden getestet.
• Drosselung, Timeouts und interne Fehler erzeugen definierte Antworten und Alarme.
• Der Lasttest deckt die geplante Spitzenlast und eine festgelegte Reserve ab.
• Der Rollback wurde mit laufenden Sitzungen und schreibenden Operationen geprobt.

Damit bleibt der Wrapper bewusst klein: Er isoliert zunächst den Wechsel der Laufzeit. Produktionsreife entsteht in der zweiten Etappe durch dauerhaften Zustand, überprüfte Zugriffsgrenzen, belastbare Telemetrie und einen praktisch erprobten Rückfallweg.

Lesen Sie auch:

• Microsoft und HUMAIN schicken Ingenieure zum Kunden – das Modell ist der Engpass
• WhatsApp ersetzt die Sechs-Ziffern-PIN: Der Rollout lässt Fragen offen
• Claude kostenlos nutzen: Das Fünf-Stunden-Limit ist nicht die einzige Grenze