Direkte Codebereitstellung für Python
Die direkte Codebereitstellung ermöglicht es Ihnen, Ihren Python-based Agenten zu Amazon Bedrock AgentCore Runtime zu bringen, indem Sie den Agentencode und seine Abhängigkeiten einfach in einem ZIP-Dateiarchiv verpacken. Ihr Agent muss weiterhin die AgentCore Runtime-Anforderungen erfüllen: über eine Einstiegspunkt-.py-Datei verfügen, die entweder die @app.entrypoint Anmerkung aus dem Amazon Bedrock AgentCore Python SDK verwendet oder /invocations POST- und /ping GET-Serverendpunkte implementiert.
Voraussetzungen
Stellen Sie vor Beginn sicher, dass Sie über Folgendes verfügen:
Schritt 1: Projekt einrichten und Abhängigkeiten installieren
Initialisieren Sie Ihr Projekt mit den folgenden Befehlen:
uv init agentcore_runtime_direct_deploy --python 3.13
cd agentcore_runtime_direct_deploy
Fügen Sie Kernpakete hinzu:
uv add bedrock-agentcore strands-agents
Installieren Sie die AgentCore CLI (für die folgenden Schritte erforderlich):
npm install -g @aws/agentcore
Beschreibungen der Package:
-
bedrock-agentcore — Das Amazon Bedrock AgentCore SDK zum Erstellen von KI-Agenten
-
strands-agents — Das Strands Agents SDK
-
@ aws/agentcore - Die AgentCore CLI
Führen Sie optional aus, uv add aws-opentelemetry-distro um Amazon Bedrock AgentCore Observability Traces zu aktivieren.
Uv erstellt automatisch eine pyproject.toml Datei mit Abhängigkeiten, eine uv.lock Datei mit Schließung der Abhängigkeiten und .venv ein Verzeichnis.
Schritt 2: Erstellen Sie Ihr Agentenprojekt
Verwenden Sie den agentcore create Befehl, um ein Skeleton-Agent-Projekt mit dem Framework Ihrer Wahl einzurichten:
agentcore create
Der Befehl fordert Sie auf zu:
-
Wählen Sie ein Framework (wählen Sie Strands Agents für dieses Tutorial)
-
Geben Sie einen Projektnamen an
-
Wählen Sie eine Vorlage (Basis- oder Produktionsvorlage)
-
Wählen Sie den Modellanbieter und andere Optionen
Dieser Befehl generiert:
-
Agentencode mit dem von Ihnen ausgewählten Framework
-
Eine pyproject.toml Datei mit den erforderlichen Abhängigkeiten
-
Eine agentcore/agentcore.json Konfigurationsdatei
-
Infrastructure-as-Code-Dateien (IaC), wenn die Produktionsvorlage ausgewählt ist
Schritt 3: Lokal testen
Stellen Sie vor dem Start sicher, dass Port 8080 frei ist. Weitere Informationen finden Sie unter Verwendeter Port 8080 (nur lokal) unter Häufig auftretende Probleme und Lösungen.
Öffnen Sie ein Terminalfenster und starten Sie Ihren Agenten mit dem folgenden Befehl:
agentcore dev --no-browser
Testen Sie Ihren Agenten, indem Sie ein anderes Terminalfenster öffnen und den folgenden Befehl eingeben:
curl -X POST http://localhost:8080/invocations \
-H "Content-Type: application/json" \
-d '{"prompt": "Hello!"}'
Erfolgreich: Sie sollten eine Antwort wie sehen{"result": "Hello! I’m here to help…"}. Geben Sie im Terminalfenster, in dem der Agent ausgeführt wird, die Eingabetaste ein, Ctrl+C um den Agenten zu beenden.
Schritt 4: Aktivieren Sie Observability für Ihren Agenten
Amazon Bedrock AgentCore Observability hilft Ihnen dabei, Agenten, die Sie in Runtime hosten, zu verfolgen, zu debuggen und zu überwachen. AgentCore Aktivieren Sie zunächst die CloudWatch Transaktionssuche, indem Sie den Anweisungen unter Amazon Bedrock AgentCore Runtime Observability aktivieren folgen. Informationen zur Beobachtung Ihres Agenten finden Sie unter Beobachtbarkeitsdaten für Ihre Amazon AgentCore Bedrock-Agenten anzeigen.
Schritt 5: In AgentCore Runtime bereitstellen und aufrufen
Stellen Sie Ihren Agenten mit einer der folgenden Methoden bereit:
Beispiel
- AgentCore CLI
-
-
Die folgenden Schritte sind erforderlich, um einen Agenten in AgentCore Runtime bereitzustellen. Weitere Informationen finden Sie unter Erste Schritte mit der AgentCore CLI. Wenn Uv verfügbar ist, empfiehlt die AgentCore CLI die direkte Codebereitstellung. Andernfalls wird standardmäßig der Container-Bereitstellungstyp verwendet.
Sobald Sie Ihren Agenten eingerichtet habenagentcore create, verwenden Sie den deploy Befehl, um ein ZIP-Bereitstellungspaket zu erstellen, es in den angegebenen Bucket hochzuladen und den Agenten bereitzustellen.
agentcore deploy
Lassen Sie uns den Agenten bitten, einen Witz zu erzählen!
agentcore invoke "Tell me a joke"
Die Installation der Abhängigkeiten bei der ersten Bereitstellung nimmt einige Zeit in Anspruch, aber nachfolgende Updates des Agenten optimieren dies, indem sie komprimierte Abhängigkeiten wiederverwenden
Verwaltung der Konfiguration
Sie können Ihre Agentenkonfiguration jederzeit mithilfe der agentcore add Befehle oder durch direkte Bearbeitung der agentcore/agentcore.json Konfigurationsdatei ändern.
Mit der Konfigurationsdatei können Sie Bereitstellungsparameter wie Ihre VPC-Konfiguration, Ausführungsrollen, Sitzungs-Timeouts und OAuth-Autorisierungseinstellungen aktualisieren.
- Interactive
-
-
Führen Sie agentcore den Befehl aus, um die TUI zu öffnen, und wählen Sie dann Bereitstellen aus. Auf dem Bereitstellungsbildschirm wird der Fortschritt in Echtzeit angezeigt, während Ihr Projekt validiert, Ressourcen synthetisiert CloudFormation und bereitgestellt werden: AWS
Verwenden Sie ihn nach Abschluss der Bereitstellung, agentcore invoke um Ihren Agenten zu testen.
- Custom zip + boto3
-
-
Um ein mit AgentCore Runtime kompatibles Rad herunterzuladen, verwenden Sie die --python-platform Option uv pip. AgentCore Runtime unterstützt nur die arm64-Befehlssatzarchitektur. Führen Sie den folgenden Befehl aus. Ersetzen Sie „--python 3.x“ durch die Version der verwendeten Python-Laufzeit.
uv pip install \
--python-platform aarch64-manylinux2014 \
--python-version 3.13 \
--target=deployment_package \
--only-binary=:all: \
-r pyproject.toml
Erstellen Sie eine ZIP-Datei mit den installierten Bibliotheken im Stammverzeichnis des Projekts.
cd deployment_package
zip -r ../deployment_package.zip .
Fügen Sie die main.py Datei und andere Dateien in Ihrem Paket dem Stammverzeichnis der ZIP-Datei hinzu.
cd ..
zip deployment_package.zip main.py
Nachdem Sie Ihr .zip-Bereitstellungspaket erstellt haben, können Sie es verwenden, um eine neue AgentCore Runtime zu erstellen oder eine bestehende zu aktualisieren. Sie können Ihr .zip-Paket mithilfe der AgentCore Runtime-API, der AgentCore Runtime-Konsole und der AWS Befehlszeilenschnittstelle bereitstellen. Die AgentCore CLI kümmert sich um die obigen Schritte zur Erstellung von .zip.
. Die maximale Größe für ein ZIP-Bereitstellungspaket für AgentCore Runtime beträgt 250 MB (gezippt) und 750 MB (entpackt). Beachten Sie, dass dieses Limit für die Gesamtgröße aller Dateien gilt, die Sie hochladen. Die AgentCore Runtime benötigt die Berechtigung, die Dateien in Ihrem Bereitstellungspaket zu lesen. In der Oktalschreibweise der Linux-Berechtigungen benötigt AgentCore Runtime 644 Berechtigungen für nicht ausführbare Dateien (rw-r—r--) und 755 Berechtigungen (rwxr-xr-x) für Verzeichnisse und ausführbare Dateien. Verwenden Sie unter Linux und MacOS den chmod-Befehl, um Dateiberechtigungen für Dateien und Verzeichnisse in Ihrem Bereitstellungspaket zu ändern. Um beispielsweise einer nicht ausführbaren Datei die richtigen Berechtigungen zu erteilen, führen Sie den folgenden Befehl aus:. chmod 644 <filepath> Informationen zum Ändern von Dateiberechtigungen in Windows finden Sie unter Festlegen, Anzeigen, Ändern oder Entfernen von Berechtigungen für ein Objekt in der Microsoft-Windows-Dokumentation. +.. Wenn Sie AgentCore Runtime nicht die erforderlichen Berechtigungen für den Zugriff auf Verzeichnisse in Ihrem Bereitstellungspaket gewähren, setzt AgentCore Runtime die Berechtigungen für diese Verzeichnisse auf 755 (rwxr-xr-x).
Als Voraussetzung für Create Agent Runtime muss ein ZIP-Archiv mit Linux-Arm64-Abhängigkeiten auf S3 hochgeladen werden. Für den folgenden Code muss der angegebene S3-Bucket bereits vorhanden sein. Bitte folgen Sie der AWS Dokumentation hier, um einen Bucket mit boto3 zu erstellen. Mit dem folgenden Boto3-Code wird ein ZIP-Dateiarchiv auf eine S3-Datei hochgeladen und die Amazon Bedrock-Laufzeit erstellt. AgentCore
import boto3
account_id = "your aws account id"
agent_name = "strands_10_23"
s3_client = boto3.client('s3', region_name='us-west-2')
print("Uploading deployment.zip to S3...")
s3_client.upload_file(
'deployment_package.zip', # archive on file system
f"bedrock-agentcore-code-{account_id}-us-west-2", # bucket name
f"{agent_name}/deployment_package.zip", # prefix
ExtraArgs={'ExpectedBucketOwner': account_id} # ownership check
)
print("Upload completed successfully!")
print(f"S3 Location: s3://bedrock-agentcore-code-{account_id}-us-west-2/{agent_name}/deployment_package.zip")
agentcore_client = boto3.client('bedrock-agentcore-control', region_name='us-west-2')
response = agentcore_client.create_agent_runtime(
agentRuntimeName=agent_name,
agentRuntimeArtifact={
'codeConfiguration': {
'code': {
's3': {
'bucket': f"bedrock-agentcore-code-{account_id}-us-west-2",
'prefix': f"{agent_name}/deployment_package.zip"
}
},
'runtime': 'PYTHON_3_13',
'entryPoint': ['opentelemetry-instrument', 'main.py']
} # if not adding otel dependency, remove opentelemetry-instrument from entrypoint array
},
networkConfiguration={"networkMode": "PUBLIC"},
roleArn=f"arn:aws:iam::{account_id}:role/AmazonBedrockAgentCoreSDKRuntime-us-west-2",
lifecycleConfiguration={
'idleRuntimeSessionTimeout': 300, # 5 min, configurable
'maxLifetime': 1800 # 30 minutes, configurable
},
)
print(f"Agent Runtime created successfully!")
print(f"Agent Runtime ARN: {response['agentRuntimeArn']}")
print(f"Status: {response['status']}")
Weitere Informationen zum programmgesteuerten Aufrufen eines Agenten finden Sie unter Programmgesteuertes Aufrufen eines Agenten.
- console
-
-
Sie können Ihren Agenten mithilfe der Amazon AgentCore Bedrock-Konsole mit verwalteter Runtime-Unterstützung bereitstellen. Die Konsole bietet eine intuitive Oberfläche zum Hochladen von ZIP-Dateien und zum Konfigurieren der Agenteneinstellungen.
Um die Installation mithilfe der Konsole durchzuführen, erstellen Sie zunächst Ihr Bereitstellungspaket. Folgen Sie dabei den Schritten auf der Registerkarte Benutzerdefiniertes ZIP-Format + boto3 oben.
Erstellen Sie den Agenten über die Konsole
So erstellen Sie Ihren Agenten:
-
Wählen Sie auf der Agenten-Startseite die Option Host Agent
-
Wählen Sie Ihre Quellenauswahl:
-
S3-Quelle — Aus dem S3-Bucket hochladen
-
Lokaler Upload — Laden Sie die ZIP-Datei von Ihrem Computer hoch
-
Vorlagen — Verwenden Sie vorgefertigte Agentenvorlagen
-
Konfigurieren Sie Ihre Agenteneinstellungen:
-
Agent name (Name des Kundendienstmitarbeiters)
-
Runtime-Version (Python 3.13 empfohlen)
-
Einstiegspunkt (z. B.main.py)
-
Ausführungsrolle (neue erstellen oder bestehende verwenden)
-
Wählen Sie Create Agent für die Bereitstellung
Endpunkt erstellen
Wählen Sie Create Endpoint aus, um einen neuen Endpunkt für Ihren Agenten zu erstellen. Der Endpunktname und die zugehörige Version werden vorab ausgefüllt.
Endpunkt testen
Wählen Sie einen Endpunkt aus und klicken Sie auf Testendpunkt, um Playground/Sandbox zum Testen zu gelangen.
Anforderungen an die Ausführungsrolle
Ihr Agent benötigt eine Ausführungsrolle mit entsprechenden Berechtigungen. Ausführliche Informationen zu Ausführungsrollen und Berechtigungen finden Sie unter AgentCore Laufzeitberechtigungen. Die Ausführungsrolle muss grundlegende Amazon AgentCore Bedrock-Laufzeitberechtigungen, S3-Zugriffsberechtigungen für Ihr Bereitstellungspaket und CloudWatch Logs-Berechtigungen für die Beobachtbarkeit enthalten.
Schritt 6: Sitzung beenden, aktualisieren oder bereinigen
Beenden Sie Ihre Runtime-Sitzung, aktualisieren oder bereinigen Sie Ihren Agenten mit einer der folgenden Methoden:
Beispiel
- AgentCore CLI
-
-
Um die zuvor bereitgestellte AgentCore Runtime zu aktualisieren, führen Sie Folgendes aus:
agentcore deploy
Verwenden Sie den API-Vorgang, um eine laufende Sitzung vor dem konfigurierbaren Zeitpunkt IdleRuntimeSessionTimeout (standardmäßig 15 Minuten) zu beenden und mögliche zusätzliche Kosten zu vermeiden. StopRuntimeSession Die AgentCore CLI unterstützt derzeit nicht das direkte Beenden von Sitzungen.
Um alle Ressourcen zu löschen, die sich auf eine AgentCore Runtime beziehen, entfernen Sie zunächst alle Ressourcen und stellen sie dann bereit, um AWS Ressourcen abzubauen:
agentcore remove all
agentcore deploy
- boto3
-
-
Der folgende Boto3-Code aktualisiert eine AgentCore Runtime.
import boto3
account_id = "your aws account id"
agent_name = "strands_10_23"
s3_client = boto3.client('s3', region_name='us-west-2')
print("Uploading deployment.zip to S3...")
s3_client.upload_file(
'deployment_package.zip', # archive on file system
f"bedrock-agentcore-code-{account_id}-us-west-2", # bucket name
f"{agent_name}/deployment_package.zip", # prefix
ExtraArgs={'ExpectedBucketOwner': account_id} # ownership check
)
print("Upload completed successfully!")
print(f"S3 Location: s3://bedrock-agentcore-code-{account_id}-us-west-2/{agent_name}/deployment_package.zip")
bedrock_agentcore_client = boto3.client('bedrock-agentcore-control', region_name='us-west-2')
response = bedrock_agentcore_client.update_agent_runtime(
agentRuntimeId='<your-agent-id>',
agentRuntimeArtifact={
'codeConfiguration': {
'code': {
's3': {
'bucket': f"bedrock-agentcore-code-{account_id}-us-west-2",
'prefix': f"{agent_name}/deployment_package.zip"
}
},
'runtime': 'PYTHON_3_13',
'entryPoint': ['opentelemetry-instrument', 'main.py']
} # if not adding otel dependency, remove opentelemetry-instrument from entrypoint array
},
networkConfiguration={"networkMode": "PUBLIC"},
roleArn=f"arn:aws:iam::{account_id}:role/AmazonBedrockAgentCoreSDKRuntime-us-west-2"
)
print(f"Agent Runtime updated successfully!")
print(f"Agent Runtime ARN: {response['agentRuntimeArn']}")
print(f"Status: {response['status']}")
Verwenden Sie den folgenden Boto3-Code, um die laufende Sitzung vor der konfigurierbaren Sitzung IdleRuntimeSessionTimeout (standardmäßig 15 Minuten) zu beenden und mögliche Kosten zu vermeiden:
import boto3
agent_core_client = boto3.client('bedrock-agentcore', region_name='us-west-2')
response = agent_core_client.stop_runtime_session(
agentRuntimeArn='arn:aws:bedrock-agentcore:us-west-2:account-id:runtime/agent-name-suffix',
runtimeSessionId='your-session-id',
qualifier="DEFAULT"
)
Der folgende Boto3-Code löscht die Amazon AgentCore Bedrock-Laufzeit und die ZIP-Archivdatei in S3.
import boto3
account_id = "your aws account id"
agent_name = "strands_10_23"
bedrock_agentcore_client = boto3.client('bedrock-agentcore-control', region_name='us-west-2')
print("Deleting Agent from Amazon Bedrock AgentCore Runtime!")
response = bedrock_agentcore_client.delete_agent_runtime(
agentRuntimeId='<agent-id>'
)
print(f"Agent Runtime delete successfully!")
print(f"Status: {response['status']}")
s3_client = boto3.client('s3', region_name='us-west-2')
print("Deleting deployment archive from S3...")
s3_client.delete_object(
Bucket=f"bedrock-agentcore-code-{account_id}-us-west-2",
Key=f"{agent_name}/deployment_package.zip",
ExpectedBucketOwner=account_id
)
print("Archive deleted successfully from S3!")
- console
-
-
====== Agent aktualisieren
Wählen Sie auf der Seite mit den Agent-Details die Option Hosting aktualisieren, um eine neue Version mit aktualisiertem Code oder aktualisierter Konfiguration zu erstellen.
Endpunkt aktualisieren
Wählen Sie einen Endpunkt aus der Tabelle Endpoints aus und klicken Sie auf Bearbeiten, um die Beschreibung oder die zugehörige Version zu aktualisieren.
Endpunkt löschen
Wählen Sie einen Endpunkt aus und klicken Sie auf Löschen. Sie müssen „Löschen“ eingeben, um den Löschvorgang zu bestätigen.
Agent löschen
Wählen Sie in der Agentenliste oder auf der Detailseite Ihren Agenten aus und klicken Sie auf Löschen, um den Agenten und alle zugehörigen Ressourcen zu entfernen.
Python-specific Konzepte für die direkte Codebereitstellung
Erfahren Sie mehr über Python-specific Konzepte bei der direkten Codebereitstellung mit Amazon Bedrock AgentCore Runtime.
Wenn Sie in Ihrem Code eine import-Anweisung verwenden, durchsucht die Python-Laufzeit die Verzeichnisse in ihrem Suchpfad, bis sie das Modul oder Paket findet. Standardmäßig ist der erste Ort, nach dem die Runtime sucht, das Verzeichnis, in das Ihr .zip-Bereitstellungspaket dekomprimiert und gemountet wird (). /var/task
Sie können den vollständigen Suchpfad für Ihren AgentCore Runtime-Agenten anzeigen, indem Sie den folgenden Codeausschnitt hinzufügen.
import sys
search_path = sys.path
print(search_path)
Fügen Sie Abhängigkeiten alternativ auch in einem separaten Ordner in Ihrem ZIP-Paket hinzu. Sie könnten beispielsweise eine Version des Boto3-SDK zu einem Ordner in Ihrem ZIP-Paket mit dem Namen hinzufügen. common Wird Ihr ZIP-Paket entpackt und bereitgestellt, wird dieser Ordner im Verzeichnis „/var/task“ abgelegt. Mit einer import from-Anweisung verwenden Sie eine Abhängigkeit aus einem Ordner Ihres ZIP-Bereitstellungspakets in Ihrem Code. Verwenden Sie mithilfe folgender Anweisung beispielsweise eine Version von Boto3 aus einem Ordner, der in Ihrem ZIP-Paket „common“ heißt.
from common import boto3
Wir empfehlen, dass Sie keine
pycache
Ordner in das Bereitstellungspaket Ihres Agenten aufnehmen. Python-Bytecode, der auf einer Build-Maschine mit einer anderen Architektur oder einem anderen Betriebssystem kompiliert wurde, ist möglicherweise nicht mit der AgentCore Runtime-Ausführungsumgebung kompatibel.
Verwendet Ihre Funktion nur reine Python-Pakete und -Module, können Sie mit dem uv pip install-Befehl Ihre Abhängigkeiten auf einem beliebigen lokalen Build-Computer installieren und Ihre ZIP-Datei erstellen. Viele beliebte Python-Bibliotheken, einschließlich NumPy Pandas, sind kein reines Python und enthalten in C oder C geschriebenen Code. Wenn Sie Ihrem Bereitstellungspaket Bibliotheken mit C/C Code hinzufügen, müssen Sie Ihr Paket korrekt erstellen, damit es mit der AgentCore Runtime-Ausführungsumgebung kompatibel ist.
Die meisten im Python Package Index (PyPI) verfügbaren Pakete sind als „Räder“ (.whl-Dateien) verfügbar. Eine WHL-Datei ist eine Art von ZIP-Datei, die eine erstellte Distribution mit vorkompilierten Binärdateien für ein bestimmtes Betriebssystem und eine bestimmte Befehlssatzarchitektur enthält. Um Ihr Bereitstellungspaket mit Amazon Bedrock AgentCore AgentCore Runtime kompatibel zu machen, installieren Sie das Wheel für Linux-Betriebssysteme und die arm64-Befehlssatzarchitektur.
Einige Pakete sind möglicherweise nur als Quelldistributionen verfügbar. Für diese Pakete müssen Sie die C/C ++-Komponenten selbst kompilieren und erstellen.
Gehen Sie wie folgt vor, um anzuzeigen, welche Distributionen für Ihr erforderliches Paket verfügbar sind:
-
Suchen Sie auf der Hauptseite des Python-Paketindex nach dem Namen des Pakets.
-
Wählen Sie die Paketversion aus, die Sie verwenden möchten.
-
Wählen Sie Dateien zum Herunterladen aus.
Wenn Ihr Paket nur als Quelldistribution verfügbar ist, müssen Sie die C/C ++-Bibliotheken selbst erstellen. Um Ihr Paket mit der Amazon Bedrock AgentCore AgentCore Runtime-Ausführungsumgebung kompatibel zu machen, müssen Sie es in einer Umgebung erstellen, die dasselbe Amazon Linux-Betriebssystem mit arm64-Befehlssatz verwendet. Erstellen Sie dafür Ihr Paket in einer Linux-Instance von Amazon Elastic Compute Cloud (Amazon EC2).
Weitere Informationen zum Starten und Herstellen einer Verbindung mit einer Amazon-EC2-Linux-Instance finden Sie unter Erste Schritte mit Amazon EC2 im Amazon-EC2-Benutzerhandbuch.
