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
Avec le déploiement direct de code, vous regroupez le code de votre agent Python et ses dépendances dans une archive de fichiers .zip et vous le déployez sur AgentCore Durée d'exécution. Votre agent doit toujours suivre AgentCore Exigences en matière d'exécution : disposez d'un fichier .py de point d'entrée qui utilise soit le @app.entrypoint annotation de Bassin rocheux d'Amazon AgentCore Kit de développement logiciel Python ou implémente /invocations POST et /ping Points de terminaison du serveur GET.
Cette page contient un résumé AgentCore Chemin de la CLI et instructions détaillées pour empaqueter et déployer le fichier .zip manuellement avec uv, Boto3 ou AWS Console de gestion. Pour le flux de travail complet de la CLI, voir Commencez avec AgentCore Exécutez à l'aide du AgentCore CLI.
Conditions préalables
Avant de commencer, assurez-vous de disposer des éléments suivants :
Étape 1 : Préparez et testez votre agent Python
Votre projet doit contenir les fichiers que vous allez ajouter au package de déploiement :
my-agent/
├── main.py
└── pyproject.toml
Exécutez l'agent localement à l'aide de la commande correspondant à votre application. Pour un point d'entrée qui démarre son serveur depuis main.py, exécutez :
uv run main.py
Dans un autre terminal, testez /invocations point final :
curl -X POST http://localhost:8080/invocations \
-H "Content-Type: application/json" \
-d '{"prompt": "Hello!"}'
Succès : Vous devriez voir une réponse comme {"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.
Si vous le souhaitez, exécutez uv add aws-opentelemetry-distro pour activer Base rocheuse de l'Amazonie AgentCore traces d'observabilité.
Étape 2 : Activez l'observabilité pour votre agent
Bassin rocheux d'Amazon AgentCore Observabilité vous permet de suivre, de déboguer et de surveiller les agents que vous hébergez dans AgentCore Durée d'exécution. Activez d'abord CloudWatch Recherchez des transactions en suivant les instructions sur Activation d'Amazon Bedrock AgentCore observabilité de l'exécution . Pour observer votre agent, consultez Afficher les données d'observabilité de votre Amazon Bedrock AgentCore agents.
Étape 3 : empaqueter, déployer et invoquer
Packagez et déployez votre agent à l'aide de l'une des méthodes suivantes :
Exemple
- AgentCore CLI
-
-
Pour un CLI-managed CodeZip projet, le AgentCore L'interface de ligne de commande regroupe et déploie le projet pour vous. Pour déployer votre agent existant avec AgentCore CLI, créez un projet à partir du modèle minimal :
agentcore create --name DirectDeployProject --template agent-python-minimal
cd DirectDeployProject
Copiez votre main.py et pyproject.toml dans app/agent/, en remplacement des fichiers générés. Déployez ensuite le projet :
agentcore deploy
Si vous le souhaitez, exécutez agentcore build d'abord pour synthétiser et vérifier le projet sans le déployer.
Invoquez le Runtime déployé :
agentcore invoke --runtime agent \
--payload '{"prompt":"Hello!"}'
Vous pouvez également courir agentcore sans argument pour ouvrir l'interface utilisateur interactive du terminal, puis choisissez déployer pour suivre la progression du déploiement. Pour les tests locaux, voir Commencez avec AgentCore Exécutez à l'aide du AgentCore CLI.
- Boto3
-
-
Pour télécharger une roue compatible avec AgentCore Runtime, vous utilisez le pip UV --python-platform option. AgentCore Runtime ne prend en charge que bras 64 architecture. Exécutez la commande suivante et remplacez 3.13 dans --python-version avec votre version de Python.
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 Exécutez ou mettez à jour un logiciel existant. Vous pouvez déployer votre package .zip à l'aide du AgentCore L'API Runtime, AgentCore Console d'exécution, ou AWS Interface de ligne de commande.
Taille maximale d'un package de déploiement .zip pour AgentCore Le temps d'exécution est de 250 Mo (compressé) et 750 Mo (décompressé). Cette limite s'applique à la taille combinée de tous les fichiers que vous 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 L'exécution 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 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 Exécutez 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 Linux bras 64 les dépendances doivent être téléchargées vers S3 comme condition préalable à Create Agent Runtime. Le code ci-dessous nécessite que le compartiment S3 spécifié existe déjà. Pour créer un bucket, voir créer_seau dans la documentation Boto3. Le code boto3 suivant téléchargera l'archive de fichiers .zip sur un s3 et créera Amazon Bedrock AgentCore exécution.
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, consultez Invoquer des agents de streaming.
- AWS Management Console
-
Vous pouvez déployer votre agent à l'aide d'Amazon Bedrock AgentCore console avec support d'exécution géré.
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 Boto 3 onglet ci-dessus.
Création d'un agent via la console
Pour créer votre agent :
-
Sur la page d'accueil des agents, choisissez Agent hôte
-
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'agents 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 Créer un agent à déployer
Création d'un endpoint
Choisissez Création d'un endpoint 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 Point final du test pour accéder au Playground/Sandbox pour les tests.
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 AgentCore Autorisations d'exécution . Le rôle d'exécution doit inclure Amazon Bedrock de base AgentCore les autorisations d'exécution, les autorisations d'accès S3 pour votre package de déploiement, et CloudWatch Enregistre les autorisations à des fins d'observabilité.
Étape 4 : arrêt d'une 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
-
-
Déployez à nouveau le projet pour mettre à jour le Runtime :
agentcore deploy
Pour supprimer les ressources déployées du projet, supprimez les ressources du projet et déployez la configuration mise à jour :
agentcore remove all --yes
agentcore deploy --yes
Pour arrêter une session Runtime active, utilisez StopRuntimeSession Fonctionnement de l'API.
- Boto3
-
-
Le code boto3 suivant mettra à jour un AgentCore Durée d'exécution.
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 pour économiser sur d'é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 Amazon Bedrock AgentCore fichier d'exécution et 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!")
- AWS Management 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
En savoir plus sur Python-specific concepts relatifs à l'utilisation du déploiement direct de code avec Amazon Bedrock AgentCore Durée d'exécution.
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 voir le chemin de recherche complet pour votre AgentCore Agent d'exécution 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
pycache
dossiers du 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 AgentCore Environnement d'exécution.
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, notamment NumPy et Pandas, ne sont pas du pur Python et contiennent du code écrit en C ou C. Lorsque vous ajoutez des bibliothèques contenant C/C code de votre package de déploiement, vous devez créer votre package correctement pour le rendre compatible avec le AgentCore Environnement d'exécution.
La plupart des packages disponibles dans l'index des packages Python ( 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 installez la roue pour les systèmes d'exploitation Linux et bras 64 architecture du jeu d'instructions.
Certains packages peuvent uniquement être disponibles en tant que distributions sources. Pour ces packages, vous devez compiler et compiler le C/C++ composants vous-même.
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 compiler le C/C++ bibliothèques vous-même. Pour rendre votre package compatible avec Amazon Bedrock AgentCore Environnement d'exécution, vous devez le créer dans un environnement utilisant le même système d'exploitation Amazon Linux que bras 64 jeu d'instructions. 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.