Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
Déploiement direct de code pour Python
Le déploiement direct du code vous permet d'intégrer votre Python-based agent à Amazon Bedrock AgentCore Runtime simplement en empaquetant le code de l'agent et ses dépendances dans une archive de fichiers .zip. Votre agent doit toujours respecter les exigences AgentCore d'exécution : disposer d'un fichier .py de point d'entrée qui utilise l'@app.entrypointannotation du SDK Amazon Bedrock AgentCore Python ou implémente les points de terminaison des serveurs /invocations POST et GET. /ping
Conditions préalables
Avant de commencer, assurez-vous de disposer des éléments suivants :
Étape 1 : Installation de la AgentCore CLI
Installez la AgentCore CLI :
npm install -g @aws/agentcore
Étape 2 : Créez votre projet d'agent
Créez un AgentCore projet pour le didacticiel :
agentcore create \
--project-name DirectDeployProject \
--name DirectDeployAgent \
--language Python \
--framework Strands \
--model-provider Bedrock \
--memory none \
--build CodeZip
cd DirectDeployProject
Cette commande génère :
-
Code d'agent avec le framework que vous avez sélectionné
-
Un pyproject.toml fichier avec les dépendances nécessaires
-
Un fichier agentcore/agentcore.json de configuration
-
Un projet agentcore/cdk/ d'infrastructure
Les dépendances générées pyproject.toml incluent les dépendances AgentCore et Strands. Uv crée l'environnement virtuel et verrouille le fichier lors de la création du projet.
Si vous le souhaitez, exécutez cd app/DirectDeployAgent && uv add aws-opentelemetry-distro && cd ../.. pour activer les traces d' AgentCore observabilité d'Amazon Bedrock.
Étape 3 : Testez localement
Assurez-vous que le port 8080 est libre avant de démarrer. Consultez la section Résoudre les problèmes si le port est déjà utilisé.
Ouvrez une fenêtre de terminal et démarrez votre agent à l'aide de la commande suivante :
agentcore dev --no-browser
Testez votre agent en ouvrant une autre fenêtre de terminal et en saisissant la commande suivante :
curl -X POST http://localhost:8080/invocations \
-H "Content-Type: application/json" \
-d '{"prompt": "Hello!"}'
Succès : vous devriez voir une réponse du type{"result": "Hello! I’m here to help…"}. Dans la fenêtre du terminal qui exécute l'agent, entrez Ctrl+C pour arrêter l'agent.
Étape 4 : Activez l'observabilité pour votre agent
Amazon Bedrock AgentCore Observability vous permet de suivre, de déboguer et de surveiller les agents que vous hébergez dans Runtime. AgentCore Activez d'abord CloudWatch la recherche de transactions en suivant les instructions de la section Activation de l'observabilité de l' AgentCore environnement d'exécution d'Amazon Bedrock. Pour observer votre agent, voir Afficher les données d'observabilité de vos agents Amazon Bedrock AgentCore .
Étape 5 : Déployer sur AgentCore Runtime et invoquer
Déployez votre agent à l'aide de l'une des méthodes suivantes :
Exemple
- AgentCore CLI
-
-
Les étapes suivantes permettent de déployer le CodeZip projet créé à l'étape 2. Pour plus d'informations, consultez la section Commencer à utiliser l' AgentCore interface de ligne de commande. Uv est requis pour créer et empaqueter le projet Python.
Une fois que votre agent est configuréagentcore create, utilisez la deploy commande pour créer un package de déploiement zip, le télécharger dans le compartiment spécifié et déployer l'agent.
agentcore deploy
Invitons l'agent à raconter une blague !
agentcore invoke "Tell me a joke"
L'installation des dépendances prend du temps lors du premier déploiement, mais les mises à jour ultérieures de l'agent optimisent cette opération en réutilisant les dépendances compressées.
Gestion de la configuration
Vous pouvez modifier la configuration de votre agent à tout moment à l'aide agentcore add des commandes ou en éditant directement le fichier de agentcore/agentcore.json configuration.
Le fichier de configuration vous permet de mettre à jour les paramètres de déploiement tels que la configuration de votre VPC, les rôles d'exécution, les délais d'expiration des sessions et les paramètres d'autorisation OAuth.
- Interactive
-
-
Exécutez agentcore pour ouvrir le TUI, puis sélectionnez déployer. L'écran de déploiement affiche les progrès en temps réel pendant qu'il valide votre projet, synthétise CloudFormation et AWS provisionne les ressources :
Une fois le déploiement terminé, agentcore invoke utilisez-le pour tester votre agent.
- Custom zip + boto3
-
-
Pour télécharger une roue compatible avec AgentCore Runtime, utilisez l'--python-platformoption uv pip. AgentCore Runtime ne prend en charge que l'architecture du jeu d'instructions arm64, exécutez la commande suivante. Remplacez --python 3.x par la version d’exécution Python que vous utilisez.
uv pip install \
--python-platform aarch64-manylinux2014 \
--python-version 3.13 \
--target=deployment_package \
--only-binary=:all: \
-r pyproject.toml
Créez un fichier .zip contenant les bibliothèques installées à la racine du projet.
cd deployment_package
zip -r ../deployment_package.zip .
Ajoutez le main.py fichier et les autres fichiers de votre package à la racine du fichier .zip.
cd ..
zip deployment_package.zip main.py
Après avoir créé votre package de déploiement .zip, vous pouvez l'utiliser pour créer un nouveau AgentCore Runtime ou mettre à jour un package existant. Vous pouvez déployer votre package .zip à l'aide de l'API AgentCore Runtime, de la console AgentCore Runtime et de l'interface de ligne de AWS commande. La AgentCore CLI prendra en charge les étapes ci-dessus pour créer un fichier .zip.
. La taille maximale d'un package de déploiement .zip pour AgentCore Runtime est de 250 Mo (compressé) et 750 Mo (décompressé). Notez que cette limite s'applique à la taille combinée de tous les fichiers que vous téléchargez. Le AgentCore Runtime a besoin d'une autorisation pour lire les fichiers de votre package de déploiement. En notation octale des autorisations Linux, AgentCore Runtime a besoin de 644 autorisations pour les fichiers non exécutables (rw-r—r--) et de 755 autorisations (rwxr-xr-x) pour les répertoires et les fichiers exécutables. Sous Linux et macOS, utilisez la commande chmod pour modifier les autorisations de fichiers sur les fichiers et les répertoires de votre package de déploiement. Par exemple, pour attribuer les autorisations appropriées à un fichier non exécutable, exécutez la commande suivante,chmod 644 <filepath>. Pour modifier les autorisations relatives aux fichiers dans Windows, voir Définir, afficher, modifier ou supprimer des autorisations sur un objet dans la documentation Microsoft Windows. +.. Si vous n'accordez pas à AgentCore Runtime les autorisations dont il a besoin pour accéder aux répertoires de votre package de déploiement, AgentCore Runtime définit les autorisations pour ces répertoires sur 755 (rwxr-xr-x).
Une archive ZIP contenant les dépendances de Linux arm64 doit être téléchargée sur S3 comme condition préalable à Create Agent Runtime. Le code ci-dessous nécessite que le compartiment S3 spécifié existe déjà. Veuillez suivre la AWS documentation disponible ici pour créer un bucket à l'aide de boto3. Le code boto3 suivant téléchargera l'archive de fichiers .zip sur un s3 et créera l'environnement d'exécution Amazon Bedrock. 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']}")
Pour plus d'informations sur l'appel d'un agent par programmation, voir Invoquer un agent par programmation.
- console
-
-
Vous pouvez déployer votre agent à l'aide de la AgentCore console Amazon Bedrock avec support d'exécution géré. La console fournit une interface intuitive pour le téléchargement de fichiers ZIP et la configuration des paramètres de l'agent.
Pour déployer à l'aide de la console, créez d'abord votre package de déploiement en suivant les étapes décrites dans l'onglet Custom zip + boto3 ci-dessus.
Création d'un agent via la console
Pour créer votre agent :
-
Sur la page d'accueil des agents, choisissez Host Agent
-
Choisissez votre sélection de sources :
-
Source S3 - Téléchargement depuis un compartiment S3
-
Téléchargement local - Téléchargez un fichier ZIP depuis votre ordinateur
-
Modèles : utilisez des modèles d'agent prédéfinis
-
Configurez les paramètres de votre agent :
-
Nom de l'agent
-
Version d'exécution (Python 3.13 recommandé)
-
Point d'entrée (par exemple,main.py)
-
Rôle d'exécution (créer un nouveau rôle ou utiliser un rôle existant)
-
Choisissez Create Agent à déployer
Création d'un endpoint
Choisissez Créer un point de terminaison pour créer un nouveau point de terminaison pour votre agent. Le nom du terminal et la version associée seront pré-remplis.
Point final du test
Sélectionnez un point de terminaison et choisissez Test Endpoint Playground/Sandbox pour accéder à la zone de test.
Exigences relatives au rôle d'exécution
Votre agent a besoin d'un rôle d'exécution avec les autorisations appropriées. Pour des informations détaillées sur les rôles d'exécution et les autorisations, consultez la section Autorisations AgentCore d'exécution. Le rôle d'exécution doit inclure les autorisations d'exécution de base d'Amazon Bedrock, les autorisations AgentCore d'accès S3 pour votre package de déploiement et les autorisations de CloudWatch journalisation pour des raisons d'observabilité.
Étape 6 : arrêt de la session, mise à jour ou nettoyage
Arrêtez votre session d'exécution, mettez à jour ou nettoyez votre agent à l'aide de l'une des méthodes suivantes :
Exemple
- AgentCore CLI
-
-
Pour mettre à jour le AgentCore Runtime précédemment déployé, exécutez :
agentcore deploy
Pour arrêter une session en cours avant la configuration IdleRuntimeSessionTimeout (15 minutes par défaut) et économiser sur d'éventuels coûts exorbitants, utilisez l'opération StopRuntimeSession API. La AgentCore CLI ne prend actuellement pas en charge l'arrêt direct des sessions.
Pour supprimer toutes les ressources liées à un AgentCore environnement d'exécution, supprimez d'abord toutes les ressources, puis déployez pour supprimer AWS les ressources :
agentcore remove all
agentcore deploy
- boto3
-
-
Le code boto3 suivant mettra à jour un 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']}")
Pour arrêter la session en cours avant la configuration IdleRuntimeSessionTimeout (15 minutes par défaut) et économiser sur les éventuels coûts exorbitants, utilisez le code boto3 suivant :
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"
)
Le code boto3 suivant supprimera le AgentCore moteur d'exécution Amazon Bedrock et le fichier d'archive .zip dans 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 de mise à jour
Sur la page des détails de l'agent, choisissez Mettre à jour l'hébergement pour créer une nouvelle version avec un code ou une configuration mis à jour.
Mettre à jour le terminal
Sélectionnez un point de terminaison dans le tableau Endpoints et choisissez Modifier pour mettre à jour la description ou la version associée.
Supprimer le terminal
Sélectionnez un point de terminaison et choisissez Supprimer. Vous devrez taper « Supprimer » pour confirmer la suppression.
Supprimer l'agent
Dans la liste des agents ou sur la page de détails, sélectionnez votre agent et choisissez Supprimer pour supprimer l'agent et toutes les ressources associées.
Python-specific concepts pour le déploiement direct de code
Découvrez Python-specific les concepts liés au déploiement direct de code avec Amazon Bedrock AgentCore Runtime.
Lorsque vous utilisez une instruction import dans votre code, l’exécution Python recherche les répertoires dans son chemin de recherche jusqu’à ce qu’elle trouve le module ou le package. Par défaut, le premier emplacement recherché par l'exécution est le répertoire dans lequel votre package de déploiement .zip est décompressé et monté ()/var/task.
Vous pouvez consulter le chemin de recherche complet de votre agent AgentCore Runtime en ajoutant l'extrait de code suivant.
import sys
search_path = sys.path
print(search_path)
Vous pouvez également ajouter des dépendances dans un dossier distinct au sein de votre package .zip. Par exemple, vous pouvez ajouter une version du SDK Boto3 dans un dossier de votre package .zip appelé. common Lorsque votre package .zip est décompressé et monté, ce dossier est placé dans le répertoire /var/task. Pour utiliser dans votre code une dépendance provenant d’un dossier de votre package de déploiement .zip, utilisez une instruction import from. Par exemple, pour utiliser une version de Boto3 provenant d’un dossier nommé common dans votre package .zip, utilisez l’instruction suivante.
from common import boto3
Nous vous recommandons de ne pas inclure de
pycache
dossiers dans le package de déploiement de votre agent. Le bytecode Python compilé sur une machine de compilation avec une architecture ou un système d'exploitation différent peut ne pas être compatible avec l' AgentCore environnement d'exécution Runtime.
Si votre fonction utilise uniquement des packages et des modules Python purs, vous pouvez utiliser la commande uv pip install pour installer vos dépendances sur n’importe quelle machine de génération locale et créer votre fichier .zip. De nombreuses bibliothèques Python populaires, y compris NumPy Pandas, ne sont pas du Python pur et contiennent du code écrit en C ou C. Lorsque vous ajoutez des bibliothèques contenant du C/C code à votre package de déploiement, vous devez créer votre package correctement pour le rendre compatible avec l'environnement AgentCore d'exécution Runtime.
La plupart des packages disponibles dans le Python Package Index (PyPI) sont disponibles sous forme de « roues » (fichiers .whl). Un fichier .whl est un type de fichier ZIP qui contient une distribution intégrée avec des fichiers binaires précompilés pour un système d’exploitation et une architecture de l’ensemble des instructions particuliers. Pour rendre votre package de déploiement compatible avec Amazon Bedrock AgentCore Runtime, vous devez installer la roue pour les systèmes d'exploitation Linux et l'architecture du jeu d'instructions arm64.
Certains packages peuvent uniquement être disponibles en tant que distributions sources. Pour ces packages, vous devez compiler et compiler vous-même les composants C/C ++.
Pour connaître les distributions disponibles pour le package dont vous avez besoin, procédez comme suit :
Si votre package n'est disponible qu'en tant que distribution source, vous devez créer vous-même les bibliothèques C/C ++. Pour rendre votre package compatible avec l'environnement AgentCore d'exécution Amazon Bedrock Runtime, vous devez le créer dans un environnement utilisant le même système d'exploitation Amazon Linux avec le jeu d'instructions arm64. Pour ce faire, créez votre package dans une instance Amazon Elastic Compute Cloud (Amazon EC2) Linux.
Pour savoir comment lancer une instance Amazon EC2 Linux et s’y connecter, veuillez consulter Mise en route avec Amazon EC2 dans le Guide de l’utilisateur Amazon EC2.
