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 regroupant le code de l'agent et ses dépendances dans une archive de fichier .zip. Votre agent doit toujours respecter les exigences AgentCore d'exécution : disposer d'un fichier .py de point d'entrée qui utilise les annotations @app.entrypoint 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 : Configuration du projet et installation des dépendances
Initialisez votre projet à l'aide des commandes suivantes :
uv init agentcore_runtime_direct_deploy --python 3.13
cd agentcore_runtime_direct_deploy
Ajoutez des packages de base :
uv add bedrock-agentcore strands-agents
Installez la AgentCore CLI (obligatoire pour les étapes suivantes) :
npm install -g @aws/agentcore
Descriptions des packages :
-
bedrock-agentcore - Le SDK Amazon Bedrock AgentCore pour créer des agents d'IA
-
strands-agents - Le SDK Strands Agents
-
@ aws/agentcore - La AgentCore CLI
Exécutez éventuellement uv add aws-opentelemetry-distro pour activer les traces d' AgentCore observabilité d'Amazon Bedrock.
Uv créera automatiquement un pyproject.toml fichier avec des dépendances, un uv.lock fichier avec une fermeture de dépendance et un .venv répertoire.
Étape 2 : Créez votre projet d'agent
Utilisez la agentcore create commande pour configurer un projet d'agent squelette avec le framework de votre choix :
agentcore create
La commande vous invitera à :
-
Choisissez un framework (choisissez Strands Agents pour ce tutoriel)
-
Entrez un nom de projet
-
Choisissez un modèle (de base ou de production)
-
Choisissez un fournisseur de modèles et d'autres options
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
-
Fichiers d'infrastructure sous forme de code (IaC) si le modèle de production est sélectionné
Étape 3 : Tester localement
Assurez-vous que le port 8080 est libre avant de démarrer. Voir Port 8080 en cours d'utilisation (local uniquement) dans Problèmes courants et solutions.
Ouvrez une fenêtre de terminal et lancez votre agent avec 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 Transaction Search en suivant les instructions de la section Activer l'observabilité du AgentCore runtime Amazon Bedrock. Pour observer votre agent, consultez Afficher les données d'observabilité de vos agents Amazon Bedrock AgentCore .
Étape 5 : Déployer vers AgentCore Runtime et invoquer
Déployez votre agent à l'aide de l'une des méthodes suivantes :
Exemple
- AgentCore CLI
-
-
Les étapes suivantes seront nécessaires pour déployer un agent sur AgentCore Runtime. Pour plus d'informations, consultez Commencer avec la AgentCore CLI. Si Uv est disponible, la AgentCore CLI recommandera le déploiement direct du code. Sinon, le type de déploiement du conteneur sera défini par défaut.
Une fois que vous avez configuré votre agentagentcore 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"
Le premier déploiement prend du temps pour installer les dépendances, mais les mises à jour ultérieures de l'agent optimisent cela en réutilisant les dépendances compressées
Gestion de configuration
Vous pouvez modifier la configuration de votre agent à tout moment à l'aide agentcore add des commandes ou en modifiant 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 de l'autorisateur OAuth.
- Interactive
-
-
Exécutez agentcore pour ouvrir le TUI, puis sélectionnez Déployer. L'écran de déploiement affiche la progression en temps réel au fur et à mesure qu'il valide votre projet, synthétise et CloudFormation 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, vous devez utiliser 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 avec 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 nouvel AgentCore environnement d'exécution ou mettre à jour un package existant. Vous pouvez déployer votre package .zip à l'aide de l'API AgentCore Runtime, de la console AgentCore d'exécution et de l'interface de ligne de AWS commande. La AgentCore CLI se chargera des étapes ci-dessus pour créer le fichier .zip.
. La taille maximale d'un package de déploiement .zip pour AgentCore Runtime est de 250 Mo (compressé) et de 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. Dans la 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 nécessaires 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 des dépendances 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 ici pour créer un bucket à l'aide de boto3. Le code boto3 suivant téléchargera une archive de fichiers .zip sur un s3 et créera un 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 effectuer un déploiement à 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, procédez comme suit :
-
Sur la page d'accueil des agents, sélectionnez Host Agent
-
Choisissez votre sélection de source :
-
Source S3 : téléchargement depuis le 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éation d'un nouveau rôle ou utilisation d'un rôle existant)
-
Choisissez Create Agent à déployer
Création d'un endpoint
Choisissez Create Endpoint pour créer un nouveau point de terminaison pour votre agent. Le nom du point de terminaison et la version associée seront préremplis.
Point final du test
Sélectionnez un point de terminaison et choisissez le point de terminaison de test Playground/Sandbox pour accéder au point de test.
Exigences relatives aux rôles d'exécution
Votre agent a besoin d'un rôle d'exécution doté des 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 AgentCore d'exécution Amazon Bedrock de base, les autorisations d'accès S3 pour votre package de déploiement et les autorisations CloudWatch Logs pour l'observabilité.
Étape 6 : arrêt de 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 supplémentaires, utilisez l'opération StopRuntimeSessionAPI. La AgentCore CLI ne prend actuellement pas en charge l'arrêt direct des sessions.
Pour supprimer toutes les ressources associées à un AgentCore Runtime, supprimez d'abord toutes les ressources, puis déployez-les pour les AWS démolir :
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 d'éventuels coûts supplémentaires, 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 runtime 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 de 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 des points de terminaison et choisissez Modifier pour mettre à jour la description ou la version associée.
Supprimer le point final
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 les Python-specific concepts liés à l'utilisation du 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 le moteur d'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 sur 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 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 construire 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 AgentCore d'exécution Amazon Bedrock Runtime, vous devez le créer dans un environnement qui utilise 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.
