Wie deployen Sie einen KI-Agenten mit Amazon Bedrock AgentCore? Vom lokalen Test bis zur Abnahme

Für einen kontrollierten Start in AWS sollten Sie AgentCore Runtime zunächst mit einer kleinen Zahl echter Anfragen prüfen. Dieser Leitfaden führt vom Eignungscheck über Rollen, Bereitstellung und Sitzungstests bis zu Beobachtbarkeit, Rücknahme und einer begründeten Go-live-Entscheidung.

Entscheidungsrahmen: Wenn Sie einen lokalen Agenten schnell in einer kontrollierbaren, beobachtbaren AWS-Laufzeit prüfen möchten, bewerten Sie zuerst AgentCore Runtime. Erweitern Sie den Einsatz erst, wenn Berechtigungen, Sitzungsverhalten, Logs und Kosten mit echten Anfragen geprüft sind. Gibt es bereits eine ausgereifte Containerplattform samt Betriebsteam, vergleichen Sie zuerst den Migrationsaufwand mit dem konkreten Nutzen des verwalteten Dienstes.

Geeignet: Entwicklerinnen und Entwickler mit einem lokalen Agentenprototyp, der erstmals in AWS laufen soll. Ebenfalls relevant: Teams, die eine verwaltete Laufzeit prüfen oder vor dem Start Verantwortlichkeiten für Zugriffsrechte, Logs und Ressourcenabbau festlegen müssen. Nicht der richtige erste Schritt: Ein ungeprüfter Umzug eines produktiven Agenten, dessen Sitzungslogik oder Containerbetrieb bereits zuverlässig funktioniert.

Eignung für AgentCore Runtime

AgentCore Runtime ist eine verwaltete Laufzeit für Agenten. Die AWS-Dokumentation beschreibt unter anderem die Ausführung von Agenten, deren Einbindung in Anwendungen und Funktionen für Betrieb und Beobachtbarkeit. Das ist ein Grund, die Laufzeit für einen ersten kontrollierten Cloud-Test in Betracht zu ziehen. Es ist aber kein Beleg dafür, dass jedes bestehende Framework ohne Änderung läuft. Prüfen Sie die in der offiziellen AgentCore-Übersicht beschriebenen Fähigkeiten gegen den tatsächlichen Aufbau Ihres Agenten.

Wir beginnen die Eignungsprüfung nicht mit einer Liste von Produktfunktionen, sondern mit vier Merkmalen des vorhandenen Systems:

• Framework: Verwendet der Agent ein in der aktuellen Dokumentation behandeltes Entwicklungsmodell? Wenn nicht, ermitteln Sie zuerst, welche Adapter oder Änderungen am Anwendungseinstieg notwendig sind.
• Modellzugriff: Ist der Aufruf des Modells in Ihrer Anwendung klar abgegrenzt? Prüfen Sie, welche AWS-Identität den Zugriff ausführt und ob diese Identität im Zielbetrieb verfügbar ist.
• Werkzeuge: Kann der Agent externe APIs, Datenbanken oder lokale Programme aufrufen? Lokale Pfade, feste IP-Adressen, Entwicklungszugänge und interaktive Bestätigungen sind keine verlässlichen Cloud-Abhängigkeiten.
• Sitzungszustand: Speichert der Agent den Dialog nur im Prozessspeicher, in einer Sitzung oder in einem externen Datenspeicher? Eine Laufzeit, die einen Agenten ausführt, ersetzt nicht automatisch das Datenmodell für dauerhafte Geschäftszustände.

Ein überschaubarer Agent mit klarer Ein- und Ausgabe, nachvollziehbaren Tool-Aufrufen und expliziter Sitzungslogik ist ein guter Kandidat für einen Pilotbetrieb. Vorsicht ist angebracht, wenn der Prozess auf lokale Dateien, lang laufende Hintergrundaufgaben oder undokumentierte Zustände im Arbeitsspeicher angewiesen ist. In solchen Fällen sollten Sie zunächst die Abhängigkeiten entkoppeln und die Zuständigkeit für dauerhafte Daten festlegen.

Die Tabelle ist eine Entscheidungshilfe, keine Kompatibilitätszusage. AgentCore kann einen Teil der Betriebsarbeit übernehmen; Anpassungen am Agenten, an seiner Konfiguration oder an seiner Sicherheitsgrenze können trotzdem erforderlich sein. Bewerten Sie daher nicht nur, ob sich ein Prozess starten lässt, sondern auch, ob er sich kontrolliert stoppen, beobachten und aktualisieren lässt.

Voraussetzungen vor dem ersten Deployment

Vor dem Deployment schreiben wir die Laufzeitannahmen des lokalen Projekts auf. Das verhindert, dass ein Cloud-Fehler später als „Agentenproblem“ behandelt wird, obwohl beispielsweise eine fehlende Berechtigung oder eine nicht verfügbare Region die Ursache ist.

Erstellen Sie zunächst eine kleine Bereitstellungsnotiz mit diesen Punkten:

• Code-Einstieg: Welche Datei oder welcher Anwendungseinstieg wird gestartet? Welche Eingabe erwartet der Agent, und in welchem Format gibt er seine Antwort zurück?
• Abhängigkeiten: Sind alle Bibliotheken in der Projektkonfiguration festgehalten? Greift der Agent auf Dateien, Umgebungsvariablen oder Werkzeuge zu, die auf dem lokalen Rechner vorhanden sind, in der Laufzeit aber fehlen könnten?
• Laufzeitvertrag: Welche Anfragen gelten als gültig? Wie werden ungültige Eingaben, Tool-Fehler und Zeitüberschreitungen zurückgegeben?
• Aufrufidentität: Welche Identität startet den Runtime-Aufruf, und welche Identität verwendet der Agent innerhalb der Laufzeit für AWS-Ressourcen?
• Sitzungskennung: Wie ordnet die Anwendung wiederholte Aufrufe einer Sitzung zu? Wann wird eine Sitzung absichtlich neu begonnen?
• Region: Ist AgentCore in der gewählten AWS-Region verfügbar, und liegen abhängige Ressourcen dort oder sind sie über definierte Zugriffswege erreichbar?

Die Unterscheidung der Identitäten ist zentral. Die Person oder Anwendung, die eine Laufzeit aufruft, benötigt nicht automatisch dieselben Rechte wie der Agentenprozess. Die AWS-Anleitung zu Runtime-Berechtigungen behandelt die Berechtigungen für den Laufzeitbetrieb. Richten Sie diese Rolle nach den tatsächlich benötigten Zugriffen aus: Ein Agent, der ein Modell aufruft, braucht nicht allein deshalb weitreichende Rechte für Speicher, Netzwerkkonfiguration oder Ressourcenverwaltung.

Verwechseln Sie außerdem ein Beispiel aus einer Anleitung nicht mit einer allgemeinen Vorgabe. Kennzeichnungen, Umgebungsvariablen und Standardwerte können vom verwendeten Einstieg, Framework und aktuellen Werkzeugstand abhängen. Die aktuelle AWS-Dokumentation zu Regionen und Verfügbarkeit sollte vor der Auswahl des Zielorts geprüft werden. Regionale Verfügbarkeit ist eine konkrete Deployment-Bedingung, keine Annahme, die sich aus der Verfügbarkeit anderer AWS-Dienste ableiten lässt.

Datenschutz und Protokollierung gehören ebenfalls in die Vorbereitungsphase. Entscheiden Sie, ob Prompts oder Tool-Antworten personenbezogene oder vertrauliche Daten enthalten dürfen. Legen Sie fest, welche Werte vor dem Protokollieren entfernt oder unkenntlich gemacht werden. Für die Verantwortlichkeiten rund um personenbezogene Daten sollten Sie die eigene Datenschutzprüfung einbeziehen; die Datenschutzhinweise von ZekVPS ersetzen keine Prüfung Ihrer AWS-Anwendung oder Ihrer Rechtsgrundlage.

Vorbereitung des ersten Cloud-Aufrufs

Bevor Sie deployen, sollten lokal mindestens zwei Dinge nachvollziehbar funktionieren: ein normaler Agentenaufruf und ein erwartbarer Fehlerfall. Notieren Sie für beide die Eingabe, die erwartete Antwortstruktur und den Fall, in dem ein Tool nicht verfügbar ist. So erhalten Sie nach dem Cloud-Aufruf eine Vergleichsbasis, statt nur „es kam Text zurück“ zu prüfen.

Die AWS-Anleitungen stellen unterschiedliche Einstiege bereit. Wenn Sie die CLI verwenden, orientieren Sie sich an der aktuellen AgentCore-CLI-Einstiegsanleitung. Für einen Python-Agenten bietet AWS außerdem einen eigenen Code-Deployment-Ablauf. Wählen Sie den Pfad nach Ihrer tatsächlichen Anwendungssprache und Ihrem Projektaufbau. Kopieren Sie nicht Befehle aus einem anderen Beispiel, ohne die dort verwendeten Parameter und Voraussetzungen abzugleichen.

Ein belastbarer Ablauf sieht so aus:

1. Projektstand einfrieren. Sichern Sie den getesteten Quellstand und notieren Sie die verwendete Abhängigkeitsdatei. Wenn Sie die Anwendung vor und nach dem Deployment verändern, können Sie Fehlerursachen schwerer voneinander trennen.
2. Einstieg und Konfiguration prüfen. Kontrollieren Sie den in der gewählten AWS-Anleitung erwarteten Anwendungseinstieg. Halten Sie getrennt fest, welche Einstellungen zur Laufzeit gehören und welche Geheimnisse sicher bereitgestellt werden müssen. Geheimnisse gehören nicht in den Quellcode oder in kopierbare Testprotokolle.
3. Zielregion und Berechtigungen festlegen. Vergleichen Sie die benötigten AgentCore-Funktionen mit der offiziellen Regionsübersicht. Prüfen Sie die Aufruferidentität und die Laufzeitrolle separat. Speichern Sie die gewählte Region und die Namen der verwendeten Rollen in Ihrer Bereitstellungsnotiz.
4. Nach aktuellem Verfahren deployen. Führen Sie den zum Framework und zur Sprache passenden Dokumentationspfad aus. Bewahren Sie die Ausgabe des Deployments auf, insbesondere den erzeugten Laufzeitbezeichner, die Region und eventuelle Hinweise zu Änderungen oder Fehlern.
5. Einen kontrollierten Aufruf senden. Verwenden Sie zuerst eine nicht sensible Testeingabe. Notieren Sie Eingabe, Sitzungskennung, Antwort und Laufzeitprotokoll. Prüfen Sie, ob die Antwort dem lokalen Vertrag entspricht, nicht nur, ob der Aufruf technisch angenommen wurde.
6. Fehler gezielt nachstellen. Verwenden Sie einen Fall, in dem ein Tool absichtlich fehlschlägt oder eine Eingabe ungültig ist. Die Anwendung sollte den Fehler erwartbar behandeln, statt vertrauliche Details preiszugeben oder eine Erfolgsmeldung zu simulieren.

Bei Befehlen und Parametern zählt der aktuelle Dokumentationsstand. Die Starter-Anleitung beschreibt den vorgesehenen Ablauf; konkrete Bezeichnungen können sich mit Werkzeugen und Versionen ändern. Deshalb geben wir hier bewusst keine scheinbar universelle Befehlszeile vor. Übernehmen Sie jeden CLI-Befehl aus dem passenden AWS-Einstieg und prüfen Sie, ob die angezeigten Werte zu Ihrem Projekt passen. Ein kopierter Befehl ohne Region, Rolle oder korrekt gesetzten Anwendungseinstieg ist kein reproduzierbarer Deployment-Schritt.

Abnahme mit echten Anfragen

Ein grüner erster Aufruf bestätigt nur einen Teil der Integration. Für die Abnahme brauchen Sie eine kleine Testmatrix, die Fehler und Sitzungsgrenzen sichtbar macht. Wir verwenden mindestens diese Fälle; sie sind Testfälle, keine behaupteten Leistungswerte:

• Einzelanfrage: Gibt der Agent das erwartete Antwortformat zurück, und lässt sich der Aufruf einer konkreten Laufzeit zuordnen?
• Mehrstufiger Dialog: Bleibt notwendiger Kontext innerhalb derselben Sitzung erhalten? Wird er bei einer neuen Sitzung tatsächlich getrennt?
• Tool-Ausfall: Liefert der Agent bei einem nicht erreichbaren Werkzeug eine kontrollierte Fehlermeldung? Werden interne Details oder Geheimnisse verborgen?
• Wiederholung: Führt eine erneut gesendete Anfrage zu unerwünschten doppelten Aktionen, etwa einem zweiten Schreibvorgang in einem externen System?
• Leerlauf und Wiederaufnahme: Entspricht das Verhalten nach einer längeren Pause den Erwartungen Ihrer Anwendung? Welche Laufzeit- und Leerlaufeinstellungen gelten für Ihre Konfiguration?

Für Sitzungslifecycle und konfigurierbare Laufzeiteinstellungen ist die offizielle Lifecycle-Dokumentation die Referenz. Leiten Sie daraus nicht ab, dass jeder Agent seinen fachlichen Zustand dauerhaft speichert. Selbst wenn die Laufzeit Sitzungen verwaltet, muss die Anwendung entscheiden, ob wichtige Daten zusätzlich in einem eigenen Speicher abgelegt werden. Das betrifft beispielsweise Freigaben, Bestellstatus oder Aufgaben, die nach einem Neustart fortgesetzt werden sollen.

Ordnen Sie für jeden Testfall drei Nachweise zusammen: die Testeingabe, die sichtbare Antwort und den passenden Laufzeit- oder Anwendungslog. Die AWS-Dokumentation zu Telemetrie und Observability beschreibt die verfügbaren Beobachtungspfade. Prüfen Sie in Ihrer konkreten Einrichtung, welche Telemetrie aktiviert ist und wo sie eingesehen wird. Es gibt keinen guten Abnahmenachweis, wenn ein Teammitglied nur einen Screenshot einer gelungenen Antwort vorlegen kann, aber weder Sitzung noch Fehlerpfad nachvollziehbar sind.

Zur Einordnung von Startfehlern und fehlgeschlagenen Anfragen können Sie die offizielle Runtime-Fehlerbehebung heranziehen. Trennen Sie dabei Fehler nach ihrer Schicht: Aufrufberechtigung, Laufzeitstart, Agentenlogik, Toolzugriff oder Antwortverarbeitung. Diese Unterscheidung verkürzt die Fehlersuche, weil nicht bei jedem Problem zuerst der Prompt geändert wird.

Abnahme vor einem begrenzten Produktivstart

Ein produktiver Start sollte als begrenzte Freigabe geplant werden, nicht als bloße Wiederholung des erfolgreichen Tests. Legen Sie fest, welche Nutzer oder Anfragen zuerst zugelassen werden, wer die Logs beobachtet und wer bei einem Fehler den Verkehr stoppt. Bestimmen Sie außerdem vorher, welche Bedingungen einen Rollback auslösen. Das sind Teamentscheidungen; die Dokumentation kann technische Optionen erklären, aber nicht Ihre akzeptable Fehlerrate oder Ihr Datenschutzmodell festlegen.

Abnahme-Checkliste für den ersten begrenzten Start:

• [ ] Die Agenteneingabe und das Antwortformat sind für einen normalen Aufruf dokumentiert.
• [ ] Aufruferidentität und Runtime-Rolle sind getrennt geprüft; jede Rolle besitzt nur die dafür erforderlichen Rechte.
• [ ] Verwendete Region und Abhängigkeiten wurden anhand der aktuellen AWS-Dokumentation bestätigt.
• [ ] Geheimnisse stehen nicht im Quellcode, in Testeingaben oder in ungeschwärzten Logs.
• [ ] Neue Sitzung, mehrstufiger Dialog und Sitzungswechsel verhalten sich wie vorgesehen.
• [ ] Tool-Ausfall und wiederholte Anfrage wurden getestet; doppelte Nebenwirkungen sind ausgeschlossen oder abgefangen.
• [ ] Logs und Telemetrie lassen sich einem Testaufruf zuordnen, ohne unnötige personenbezogene Daten offenzulegen.
• [ ] Eine verantwortliche Person kann die aktuelle Version stoppen oder auf einen bekannten Stand zurücksetzen.
• [ ] Es gibt einen geprüften Weg, nicht mehr benötigte Laufzeitressourcen zu entfernen.

Bewerten Sie jeden Punkt als „bestanden“, „offen“ oder „nicht anwendbar“. Eine offene Berechtigungs- oder Datenschutzfrage sollte den Start blockieren. Ein noch nicht optimiertes Dashboard muss nicht zwingend blockieren, wenn die Testanfragen klar begrenzt sind und eine verantwortliche Person den Ablauf beobachtet. Die Entscheidung sollte in einem kurzen Abnahmeprotokoll stehen: getesteter Quellstand, Region, Laufzeitbezeichner, Testfälle, offene Risiken und Rücknahmeverantwortung.

Planen Sie auch die Aktualisierung und das Aufräumen. Eine neue Version ist erst dann kontrolliert ausgerollt, wenn klar ist, welche Laufzeit sie verwendet und wie Sie bei einem Fehler zur vorherigen Version zurückkehren. Nach abgebrochenen Tests sollten nicht mehr benötigte Ressourcen entfernt werden. Die Dokumentation zu Deployment und Lifecycle liefert technische Anhaltspunkte; Zuständigkeit und Aufbewahrungsdauer müssen Sie in Ihrem Team festlegen.

Für den Kostenvergleich sollten Sie nicht mit einem unbelegten Pauschalbetrag arbeiten. Erfassen Sie, welche Laufzeitaufrufe, Modellnutzung, Speicher- und Protokollierungsressourcen Ihr Test tatsächlich auslöst, und prüfen Sie die dazugehörigen Abrechnungsdaten in Ihrer AWS-Umgebung. Das Ergebnis ist für die Entscheidung hilfreicher als eine Schätzung, die weder zu Ihrer Region noch zu Ihren Anfragen passt. Skalieren Sie erst, wenn die Kostenstellen zugeordnet sind und ein Budgetverantwortlicher den nächsten Schritt freigibt.

Häufige Fragen zur Bereitstellung

Welche Vorbereitungen braucht ein AgentCore-Runtime-Start?

Halten Sie den Anwendungseinstiegspunkt, die installierbaren Abhängigkeiten und die erwarteten Ein- und Ausgabeformate fest. Prüfen Sie außerdem die Verfügbarkeit der Zielfunktionen in der gewählten Region, die aufrufende Identität und die Rechte des Agentenprozesses. Diese Rollen sind nicht automatisch identisch. Stimmen Sie Umgebungsvariablen, Geheimnisse, Sitzungskennung und Protokollierung ab, bevor Sie den ersten Cloud-Aufruf starten.

Wie lässt sich ein eigener KI-Agent mit AgentCore Runtime bereitstellen?

Nutzen Sie die aktuelle AWS-Anleitung, die zu Framework und Sprache Ihres Agenten passt, anstatt eine Befehlsfolge aus einem anderen Beispiel ungeprüft zu übernehmen. Konfigurieren Sie den Einstieg und die Laufzeit, deployen Sie nach dem dokumentierten Ablauf und notieren Sie Laufzeitbezeichner sowie Region. Rufen Sie anschließend die bereitgestellte Version mit einer kontrollierten Testeingabe auf und vergleichen Sie das Ergebnis mit Ihrem lokalen Test.

Wie prüfen Sie, ob der Agent nach dem Deployment korrekt arbeitet?

Prüfen Sie nicht nur einen erfolgreichen Einzelaufruf. Testen Sie einen mehrstufigen Dialog, einen absichtlich fehlschlagenden Tool-Aufruf und die Wiederholung einer Anfrage. Kontrollieren Sie Antwort, Sitzungszuordnung und mögliche doppelte Aktionen. Definieren Sie vor dem Test, was als bestanden gilt, und sichern Sie Logs sowie Eingaben als Abnahmenachweis. So wird sichtbar, ob Fehler kontrolliert behandelt werden.

Wo finden Sie Logs und den Sitzungszustand eines AgentCore-Agenten?

Der konkrete Ort der Telemetrie hängt von der eingerichteten Beobachtbarkeit ab. Prüfen Sie deshalb Ihre Konfiguration und die AWS-Anleitung zu Observability, statt einen festen Speicherort vorauszusetzen. Ein verwalteter Sitzungskontext ist zudem nicht automatisch ein dauerhaftes fachliches Datenspeichersystem. Legen Sie fest, welche Zustände Ihre Anwendung selbst sichert und welche Informationen Sie protokollieren dürfen.

Entscheidung zwischen verwalteter Laufzeit und bestehender Umgebung

AgentCore Runtime ist nicht automatisch die beste langfristige Lösung für jedes Team. Eine bereits betriebene Containerplattform kann vorhandene Deployments, Monitoring und Bereitschaftsdienste nutzen; ein Wechsel bringt dann neue Berechtigungen, eine zusätzliche Laufzeitabhängigkeit und erneute Abnahmearbeit mit sich. Umgekehrt kann eine verwaltete Laufzeit für einen begrenzten Test sinnvoll sein, wenn Sie keine eigene Plattform für einen ersten Cloud-Nachweis betreiben möchten. Entscheiden Sie nach tatsächlichem Betriebsaufwand, Kontrolle und den Kostenstellen Ihres Testlaufs.

Wenn für die Entwicklung zusätzlich eine macOS-Umgebung oder ein Apple-spezifischer Testrechner gebraucht wird, ist ein Mac keine Ersatzlaufzeit für AgentCore in AWS. Er kann aber für lokale Entwicklung und gezielte Kompatibilitätstests relevant sein. Ein eigener Mac verursacht Anschaffung und laufende Pflege; eine Mietumgebung vermeidet diese Investition, bietet jedoch keinen Ersatz für AWS-IAM, Cloud-Logs oder AgentCore-Sitzungstests. Für vorübergehende macOS-Arbeit können Sie die verfügbare Mac-mini-Mietoption in Japan prüfen. Nutzen Sie sie nur, wenn der Test tatsächlich macOS-Hardware verlangt.

Für den konkreten nächsten Schritt vergleichen wir daher nicht abstrakt „Cloud gegen Mac“, sondern den aktuellen Arbeitsablauf mit dem benötigten Test: AWS-Rollen, Sitzungen und Tool-Aufrufe müssen in AWS geprüft werden; lokale Entwicklung oder Apple-spezifische Prüfungen können eine separate macOS-Umgebung erfordern. Wenn Sie zunächst die Laufzeitabhängigkeiten Ihres Projekts klären möchten, finden Sie die verfügbaren Cloud- und Entwicklungsumgebungen von ZekVPS. Leiten Sie daraus erst dann eine Mietentscheidung ab, wenn klar ist, welche Aufgabe die Umgebung erfüllen soll.