# 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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-service-contract.html) : disposer d'un fichier .py de point d'entrée qui utilise les annotations `@app.entrypoint` du [SDK Amazon Bedrock AgentCore Python](https://github.com/aws/bedrock-agentcore-sdk-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 : + ** AWS Compte** avec informations d'identification configurées. Pour configurer vos AWS informations d'identification, consultez [la section Configuration et paramètres des fichiers d'identification dans la AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html). + [Uv](https://docs.astral.sh/uv/getting-started/installation/) **installé** et [Python 3.10\+](https://docs.astral.sh/uv/guides/install-python/) installé + ** AWS Autorisations** : pour créer et déployer un agent avec la AgentCore CLI, vous devez disposer des autorisations appropriées. Pour plus d'informations, consultez la section [Utiliser la AgentCore CLI](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html#runtime-permissions-cli). + **Accès au modèle** : Anthropic Claude Sonnet 4.0 [activé](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access-modify.html) dans la console Amazon Bedrock. Pour plus d'informations sur l'utilisation d'un modèle différent avec les Strands Agents, consultez la section *Fournisseurs de modèles* dans la documentation du [SDK Strands Agents](https://strandsagents.com/latest/documentation/docs/). ## É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](https://strandsagents.com/latest/) Agents + **@ aws/agentcore** - La AgentCore CLI Exécutez éventuellement `uv add aws-opentelemetry-distro` pour activer les traces d'[ AgentCore observabilité d'Amazon Bedrock](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-adot.html). 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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-cli.html#common-issues). 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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html) 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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-configure.html#observability-configure-builtin). Pour observer votre agent, consultez [Afficher les données d'observabilité de vos agents Amazon Bedrock AgentCore ](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-view.html). ## Étape 5 : Déployer vers AgentCore Runtime et invoquer Déployez votre agent à l'aide de l'une des méthodes suivantes : **Example** 1. Les étapes suivantes seront nécessaires pour déployer un agent sur AgentCore Runtime. Pour plus d'informations, consultez [Commencer avec la AgentCore CLI](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-cli.html). 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 agent`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" ``` 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. 1. 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 : ![AgentCore progression du déploiement indiquant les mises à jour de la CloudFormation pile](http://docs.aws.amazon.com/fr_fr/bedrock-agentcore/latest/devguide/images/tui/code-deploy-progress.png) Une fois le déploiement terminé, `agentcore invoke` utilisez-le pour tester votre agent. 1. Pour télécharger une roue compatible avec AgentCore Runtime, vous devez utiliser l'`--python-platform`option 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. **Note** . 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 `. Pour modifier les autorisations relatives aux fichiers dans Windows, voir [Définir, afficher, modifier ou supprimer des autorisations sur un objet](https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc731667(v=ws.10)) 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](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3/client/create_bucket.html) 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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-cli.html#invoke-programmatically) agent par programmation. 1. 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 : 1. Sur la page d'accueil des agents, sélectionnez **Host Agent** 1. 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 1. 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) 1. 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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html). 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 : **Example** 1. 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 [StopRuntimeSession](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_StopRuntimeSession.html)API. 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 ``` 1. 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='', 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='' ) 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!") ``` 1. ====== 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. **Topics** ### Chemin de recherche des dépendances et bibliothèques incluses dans l’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 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 ``` ### Bytecode Python et *pycache* dossiers 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. ### Packages de déploiement avec bibliothèques natives 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](https://pypi.org/)) 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 : 1. Recherchez le nom du package sur la [page principale du Python Package Index](https://pypi.org/). 1. Choisissez la version du package que vous souhaitez utiliser. 1. Choisissez **Télécharger les fichiers**. ### Utilisation des distributions sources 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](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html) dans le *Guide de l’utilisateur Amazon EC2*.