AWS Bedrock AgentCore: LangGraph-Agent in der Cloud bereitstellen

Die Entwicklung eines KI-Agenten mit LangGraph ist nur der erste Schritt. Doch wie gelingt der Übergang in eine skalierbare, serverlose Produktionsumgebung – ohne den gesamten Code neu schreiben zu müssen?

Die Lösung bietet AWS Bedrock AgentCore: eine serverlose Plattform, die speziell für den Betrieb von KI-Agenten entwickelt wurde. Sie ermöglicht es, bestehende Agenten-Implementierungen mit minimalem Aufwand in die Cloud zu migrieren. In dieser Anleitung erfahren Sie, wie Sie Ihren LangGraph-Agenten für AgentCore vorbereiten, lokal testen und schließlich in einer AWS-Umgebung bereitstellen – inklusive Session-Isolation und Observability.

Serverlose KI-Agenten mit AWS Bedrock AgentCore

AWS Bedrock AgentCore ist eine von AWS bereitgestellte Hosting-Lösung, die es Entwicklern ermöglicht, KI-Agenten ohne manuelle Infrastrukturverwaltung zu betreiben. Die Plattform unterstützt verschiedene Open-Source-Frameworks wie LangGraph, Strands, CrewAI oder LlamaIndex sowie große Sprachmodelle wie OpenAI’s GPT, Googles Gemini oder Anthropics Claude.

Ein zentraler Vorteil: Sie müssen den Agenten-Code nicht grundlegend anpassen. Stattdessen wird der bestehende LangGraph-Agent mit einem Wrapper umhüllt, der die Kompatibilität mit AgentCore sicherstellt. Weitere Features umfassen:

• Automatische Skalierung je nach Anfragenlast
• Persistente Speicherung von Agenten-Sitzungen
• Integrierte Protokollierung und Überwachung
• Sicherheitsmanagement durch AWS Identity and Access Management

Die Bereitstellung erfolgt über die AgentCore CLI, ein auf Node.js basierendes Tool, das Projekte initialisiert, lokale Entwicklungsserver ausführt und Deployments auf AWS mittels AWS CDK durchführt.

Voraussetzungen für den Einsatz von AgentCore

Bevor Sie mit der Einrichtung beginnen, stellen Sie sicher, dass folgende Komponenten installiert und konfiguriert sind:

• Python 3.12 oder neuer – erforderlich für die Ausführung des AgentCore SDKs
• uv oder pip – zur Verwaltung von Python-Abhängigkeiten
• Node.js 20+ – notwendig für die AgentCore CLI
• AWS CDK – global installiert via npm install -g aws-cdk
• AWS-Zugangsdaten – lokal konfiguriert mit aws configure
• Vorhandener LangGraph-Agent – mit einem kompilierten StateGraph-Objekt

Zusätzlich sollten Sie über ein AWS-Konto mit ausreichenden Berechtigungen für die Nutzung von Bedrock und CDK verfügen.

Schritt 1: AgentCore CLI installieren und einrichten

Der erste Schritt besteht darin, die AgentCore CLI zu installieren. Dieses Tool dient als zentraler Einstiegspunkt für alle weiteren Schritte – von der Projektinitialisierung bis zum Deployment.

Führen Sie folgenden Befehl aus, um die CLI global zu installieren:

npm install -g @aws/agentcore

Nach der Installation können Sie die Funktionsfähigkeit überprüfen:

agentcore --help

Sollten Fehler auftreten, stellen Sie sicher, dass Node.js korrekt installiert ist und Ihre Umgebungsvariablen entsprechend gesetzt sind.

Schritt 2: Abhängigkeiten für den Agenten hinzufügen

Um Ihren LangGraph-Agenten mit AgentCore kompatibel zu machen, benötigen Sie zwei zusätzliche Python-Pakete:

• `bedrock-agentcore` – stellt die Klasse BedrockAgentCoreApp bereit, die als Wrapper für Ihren Agenten dient
• `aws-opentelemetry-distro` – eine von AWS unterstützte Version der OpenTelemetry-Instrumentierung für Python

Fügen Sie diese Abhängigkeiten in Ihre Projektkonfiguration ein, beispielsweise in der pyproject.toml-Datei:

[project]
name = "my-agent"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "aws-opentelemetry-distro==0.17.0",
    "bedrock-agentcore>=1.6.3",
    "boto3>=1.42.0",
    "langgraph>=1.1.0",
    "langchain-core>=1.2.0",
    # ... weitere bestehende Abhängigkeiten
]

Installieren Sie die Pakete anschließend mit Ihrem bevorzugten Tool:

uv sync
# oder
pip install -e .

Schritt 3: Hauptdatei für AgentCore erstellen (main.py)

AgentCore erwartet eine einzelne Python-Datei als Einstiegspunkt, die eine Instanz von BedrockAgentCoreApp enthält und eine Funktion mit dem @app.entrypoint-Dekorator definiert. Der bestehende LangGraph-Code bleibt dabei weitgehend unverändert – es wird lediglich eine dünne Schicht um den Agenten herum hinzugefügt.

Hier ein Beispiel für die Struktur der main.py-Datei:

from langchain_core.messages import HumanMessage
from bedrock_agentcore.runtime import BedrockAgentCoreApp
from graphs.my_agent_graph import build_my_agent  # Ihr bestehender Graph-Ersteller

# 1. AgentCore-Anwendung und Logger initialisieren
app = BedrockAgentCoreApp()
log = app.logger

# 2. Graph zum Zeitpunkt des Modulloads erstellen (Startzeitpunkt)
# AgentCore initialisiert das Modul einmalig und behandelt dann gleichzeitige Aufrufe.
# Fehler hier verhindern, dass ein defekter Agent in Produktion geht.
def create_agent():
    log.info("Agent wird initialisiert...")
    graph = build_my_agent()  # Gibt den kompilierten LangGraph StateGraph zurück
    log.info("Agent bereit")
    return graph

try:
    graph = create_agent()
except Exception as e:
    log.error(f"Kritischer Fehler während der Initialisierung: {e}")
    raise  # Sofortiger Abbruch, um defekte Agenten zu verhindern

# 3. Asynchrone Hilfsfunktion für die LangGraph-Streaming-Schleife
async def run_agent(user_input: str, session_id: str = "default-session") -> str:
    responses = []
    config = {"configurable": {"thread_id": session_id}}
    
    async for chunk in graph.astream(
        {"messages": [HumanMessage(content=user_input)]},
        config=config,
        stream_mode="values",
    ):
        messages = chunk.get("messages", [])
        if messages:
            last = messages[-1]
            if getattr(last, "type", None) == "ai":
                responses.append(last)
    
    if not responses:
        return "Keine Antwort"
    
    content = getattr(responses[-1], "content", "")
    return content if isinstance(content, str) else str(content)

# 4. Einstiegspunkt – wird bei jedem Aufruf durch AgentCore ausgeführt
@app.entrypoint
async def invoke(payload, context):
    try:
        log.info("Eingehender Aufruf erkannt")
        user_input = payload.get("prompt", "")
        session_id = payload.get("session_id", "default-session")
        
        if not user_input.strip():
            return {"error": "Aufforderung darf nicht leer sein"}
        
        response = await run_agent(user_input, session_id)
        return {"response": response}
    except Exception as e:
        log.error(f"Fehler: {e}")
        return {"error": str(e)}

# 5. Lokale Ausführung (nur für Entwicklungszwecke)
if __name__ == "__main__":
    app.run()

Wichtige Hinweise zur Implementierung

• `BedrockAgentCoreApp()` richtet den HTTP-Server, Health-Check-Endpunkte und strukturierte Protokollierung automatisch ein.
• Der Graph wird auf Modulebene initialisiert, sodass Fehler bereits beim Start erkannt werden – bevor der Agent produktiv geht.
• Die mit @app.entrypoint dekorierte Funktion verarbeitet eingehende Anfragen. Sie empfängt den Payload (als JSON) und den Kontext und gibt ein serialisierbares Dictionary zurück.
• Die session_id wird als thread_id an LangGraph übergeben, um Sitzungsisolation und persistente Speicherung mit MemorySaver zu ermöglichen.

Schritt 4: Projektstruktur mit AgentCore erstellen

Im nächsten Schritt generieren Sie die Projektstruktur. Wechseln Sie in ein neues Verzeichnis und führen Sie den Initialisierungs-Assistenten aus:

agentcore create

Der Assistent stellt Ihnen einige Fragen zur Konfiguration, darunter:

• Projektname
• Python-Version
• AWS-Region für das Deployment

Nach Abschluss des Assistenten wird eine grundlegende Projektstruktur erzeugt, die Sie an Ihre Anforderungen anpassen können. Die Datei main.py ist bereits enthalten und kann direkt mit Ihrem Agenten-Code erweitert werden.

Ausblick: Agenten in der Cloud betreiben

Mit AWS Bedrock AgentCore gelingt der Wechsel von der lokalen Entwicklung zur produktiven Cloud-Umgebung nahtlos. Die serverlose Architektur übernimmt dabei die Skalierung, während Sie sich auf die Logik Ihres Agenten konzentrieren können.

In zukünftigen Schritten lohnt es sich, die integrierten Überwachungstools zu nutzen und die Agenten-Performance kontinuierlich zu optimieren. AgentCore bietet hierfür eine solide Grundlage – von der Entwicklung bis zum Betrieb.