# Despliegue directo de código para Python La implementación directa del código le permite llevar a su Python-based agente a Amazon Bedrock AgentCore Runtime simplemente empaquetando el código del agente y sus dependencias en un archivo zip. Su agente aún debe cumplir con [los requisitos de AgentCore tiempo de ejecución](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-service-contract.html): tener un archivo.py de punto de entrada que utilice la `@app.entrypoint` anotación del SDK de [ AgentCore Python de Amazon Bedrock](https://github.com/aws/bedrock-agentcore-sdk-python) o que `/invocations` implemente los puntos de enlace de los servidores POST `/ping` y GET. ## Requisitos previos Antes de comenzar, asegúrese de que dispone de lo siguiente: + ** AWS Cuenta con credenciales configuradas.** Para configurar sus AWS credenciales, consulte [Configuración y configuración del archivo de credenciales en la AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html). + [Uv](https://docs.astral.sh/uv/getting-started/installation/) **instalado** y [Python 3.10\+](https://docs.astral.sh/uv/guides/install-python/) instalado + ** AWS Permisos**: para crear e implementar un agente con la AgentCore CLI, debe tener los permisos adecuados. Para obtener más información, consulte [Uso de la AgentCore CLI](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html#runtime-permissions-cli). + **Acceso al modelo**: Anthropic Claude Sonnet 4.0 [habilitado](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access-modify.html) en la consola Amazon Bedrock. Para obtener información sobre el uso de un modelo diferente con los agentes de Strands, consulte la sección de *proveedores de modelos* de la documentación del SDK de [Strands Agents](https://strandsagents.com/latest/documentation/docs/). ## Paso 1: Configurar el proyecto e instalar las dependencias Inicialice su proyecto con los siguientes comandos: ``` uv init agentcore_runtime_direct_deploy --python 3.13 cd agentcore_runtime_direct_deploy ``` Añada los paquetes principales: ``` uv add bedrock-agentcore strands-agents ``` Instale la AgentCore CLI (necesaria para los pasos siguientes): ``` npm install -g @aws/agentcore ``` Descripciones de los paquetes: + **bedrock-agentcore**: el SDK de Amazon AgentCore Bedrock para crear agentes de IA + **[strands-agents: el SDK de Strands Agents](https://strandsagents.com/latest/)** + **@ aws/agentcore** - La AgentCore CLI Si lo desea, ejecute `uv add aws-opentelemetry-distro` para habilitar los [rastreos de AgentCore observabilidad de Amazon Bedrock](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-adot.html). Uv creará automáticamente un `pyproject.toml` archivo con las dependencias, `uv.lock` un archivo con el cierre de las dependencias y un directorio. `.venv` ## Paso 2: Crea tu proyecto de agente Usa el `agentcore create` comando para configurar un proyecto de agente básico con el marco que prefieras: ``` agentcore create ``` El comando le pedirá que: + Elija un marco (elija Strands Agents para este tutorial) + Proporcione un nombre de proyecto + Elige una plantilla (básica o de producción) + Elija el modelo, el proveedor y otras opciones Este comando genera: + Código de agente con el marco seleccionado + Un `pyproject.toml` archivo con las dependencias necesarias + Un archivo `agentcore/agentcore.json` de configuración + Archivos de infraestructura como código (IaC) si se selecciona la plantilla de producción ## Paso 3: Realice una prueba local Asegúrese de que el puerto 8080 esté libre antes de comenzar. Consulte *el puerto 8080 en uso (solo local)* en [Problemas y soluciones comunes](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-cli.html#common-issues). Abre una ventana de terminal e inicia tu agente con el siguiente comando: ``` agentcore dev --no-browser ``` Pon a prueba a tu agente abriendo otra ventana de terminal e introduce el siguiente comando: ``` curl -X POST http://localhost:8080/invocations \ -H "Content-Type: application/json" \ -d '{"prompt": "Hello!"}' ``` **Éxito:** deberías ver una respuesta como`{"result": "Hello! I’m here to help…​"}`. En la ventana de la terminal en la que se ejecuta el agente, ingresa `Ctrl+C` para detenerlo. ## Paso 4: Habilite la observabilidad para su agente [Amazon Bedrock AgentCore Observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html) le ayuda a rastrear, depurar y supervisar los agentes que aloja en Runtime. AgentCore En primer lugar, active la búsqueda de CloudWatch transacciones siguiendo las instrucciones de [Habilitar la observabilidad en tiempo de AgentCore ejecución de Amazon Bedrock](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-configure.html#observability-configure-builtin). Para observar a su agente, consulte [Ver datos de observabilidad de sus agentes de Amazon Bedrock AgentCore ](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-view.html). ## Paso 5: Implemente en AgentCore Runtime e invoque Implemente su agente mediante uno de los siguientes métodos: **Example** 1. Se requerirán los siguientes pasos para implementar un agente en AgentCore Runtime. Para obtener más información, consulte [Introducción a la AgentCore CLI](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-cli.html). Si Uv está disponible, la AgentCore CLI recomendará el despliegue directo del código. De lo contrario, se utilizará de forma predeterminada el tipo de despliegue de contenedor. Una vez que haya configurado el agente mediante`agentcore create`, utilice el `deploy` comando para crear un paquete de despliegue comprimido, cárguelo en el depósito especificado e implemente el agente. ``` agentcore deploy ``` ¡Vamos a pedirle al agente que cuente un chiste\! ``` agentcore invoke "Tell me a joke" ``` La primera implementación lleva tiempo instalar las dependencias, pero las actualizaciones posteriores del agente optimizan la instalación al reutilizar las dependencias comprimidas **Administración de la configuración** Puede modificar la configuración del agente en cualquier momento mediante los `agentcore add` comandos o editando directamente el archivo de `agentcore/agentcore.json` configuración. El archivo de configuración le permite actualizar los parámetros de despliegue, como la configuración de la VPC, las funciones de ejecución, los tiempos de espera de las sesiones y la configuración del autorizador de OAuth. 1. **Ejecute `agentcore` para abrir la TUI y, a continuación, seleccione implementar.** La pantalla de despliegue muestra el progreso en tiempo real a medida que valida el proyecto CloudFormation, sintetiza y aprovisiona los recursos: AWS ![AgentCore el progreso del despliegue muestra CloudFormation las actualizaciones de la pila](http://docs.aws.amazon.com/es_es/bedrock-agentcore/latest/devguide/images/tui/code-deploy-progress.png) Una vez completada la implementación, `agentcore invoke` úselo para probar su agente. 1. Para descargar una rueda que sea compatible con AgentCore Runtime, usa la `--python-platform` opción uv pip. AgentCore Runtime solo es compatible con la arquitectura del conjunto de instrucciones **arm64**. Ejecute el siguiente comando. Reemplace `--python 3.x` con la versión del tiempo de ejecución de Python que está utilizando. ``` uv pip install \ --python-platform aarch64-manylinux2014 \ --python-version 3.13 \ --target=deployment_package \ --only-binary=:all: \ -r pyproject.toml ``` Cree un archivo.zip con las bibliotecas instaladas en la raíz del proyecto. ``` cd deployment_package zip -r ../deployment_package.zip . ``` Añada el `main.py` archivo y los demás archivos del paquete a la raíz del archivo.zip. ``` cd .. zip deployment_package.zip main.py ``` Una vez creado el paquete de despliegue .zip, puede usarlo para crear un nuevo AgentCore Runtime o actualizar uno existente. Puede implementar su paquete .zip mediante la API AgentCore Runtime, la consola AgentCore Runtime y la interfaz de línea de AWS comandos. La AgentCore CLI se encargará de los pasos anteriores para crear .zip. **nota** . El tamaño máximo de un paquete de implementación.zip para AgentCore Runtime es de 250 MB (comprimido) y 750 MB (descomprimido). Tenga en cuenta que este límite se aplica al tamaño combinado de todos los archivos que cargue. El AgentCore Runtime necesita permiso para leer los archivos del paquete de despliegue. En la notación octal de permisos de Linux, AgentCore Runtime necesita 644 permisos para los archivos no ejecutables (rw-r—r--) y 755 permisos (rwxr-xr-x) para los directorios y los archivos ejecutables. En Linux y macOS, utilice el comando `chmod` para cambiar los permisos de los archivos y directorios del paquete de implementación. Por ejemplo, para conceder los permisos correctos a un archivo no ejecutable, ejecute el siguiente comando:. `chmod 644 ` Para cambiar los permisos de los archivos en Windows, consulte [Set, View, Change, or Remove Permissions on an Object](https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc731667(v=ws.10)) en la documentación de Microsoft Windows. \+.. Si no concedes a AgentCore Runtime los permisos que necesita para acceder a los directorios de tu paquete de implementación, AgentCore Runtime establece los permisos para esos directorios en 755 (rwxr-xr-x). Es necesario cargar en S3 un archivo ZIP que contenga las dependencias **arm64** de Linux como requisito previo para crear Agent Runtime. El siguiente código requiere que el bucket de S3 especificado ya exista. Siga la AWS documentación [aquí](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3/client/create_bucket.html) para crear un depósito con boto3. El siguiente código boto3 cargará el archivo.zip en un s3 y creará el tiempo de ejecución de 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']}") ``` [Para obtener más información sobre cómo invocar un agente mediante programación, consulte Invocar un agente mediante programación.](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-cli.html#invoke-programmatically) 1. Puede implementar su agente mediante la AgentCore consola Amazon Bedrock con soporte de tiempo de ejecución gestionado. La consola proporciona una interfaz intuitiva para cargar archivos ZIP y configurar los ajustes del agente. Para realizar el despliegue mediante la consola, cree primero el paquete de despliegue siguiendo los pasos de la pestaña *Custom zip \+ boto3* que aparece más arriba. **Cree un agente a través de la consola** Para crear tu agente: 1. En la página de inicio del agente, selecciona **Host Agent** 1. Elija su fuente seleccionada: + **Fuente S3**: carga desde un bucket de S3 + **Carga local**: cargue un archivo ZIP desde su ordenador + **Plantillas**: utilice plantillas de agente prediseñadas 1. Configure los ajustes de su agente: + Nombre completo del agente + Versión en tiempo de ejecución (se recomienda Python 3.13) + Punto de entrada (por ejemplo,`main.py`) + Función de ejecución (crear una nueva o utilizar la existente) 1. Elija **Crear agente** para desplegarlo **Cree un punto final** Elija **Crear punto final** para crear un nuevo punto final para su agente. El nombre del terminal y la versión asociada se rellenarán previamente. **Punto final de prueba** Seleccione un punto final y elija el **punto final de prueba** para ir al punto final de la Playground/Sandbox prueba. **Requisitos de la función de ejecución** Su agente necesita un rol de ejecución con los permisos adecuados. Para obtener información detallada sobre las funciones y los permisos de ejecución, consulte [Permisos AgentCore de ejecución](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html). La función de ejecución debe incluir los permisos básicos de tiempo de AgentCore ejecución de Amazon Bedrock, los permisos de acceso a S3 para el paquete de implementación y los permisos de CloudWatch Logs para la observabilidad. ## Paso 6: detener la sesión, actualizarla o limpiarla Detenga la sesión en tiempo de ejecución, actualice o limpie el agente mediante uno de los siguientes métodos: **Example** 1. Para actualizar AgentCore Runtime implementado anteriormente, ejecute: ``` agentcore deploy ``` Para detener una sesión en ejecución antes de la configuración `IdleRuntimeSessionTimeout` (el valor predeterminado es de 15 minutos) y ahorrar en posibles costes excesivos, utilice la operación de la [StopRuntimeSession](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_StopRuntimeSession.html)API. Actualmente, la AgentCore CLI no admite la detención directa de las sesiones. Para eliminar todos los recursos relacionados con un AgentCore entorno de ejecución, primero elimine todos los recursos y, a continuación, AWS impleméntelos para eliminarlos: ``` agentcore remove all agentcore deploy ``` 1. Si sigue el código boto3, se actualizará 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']}") ``` Para detener la sesión en ejecución antes de la sesión configurable `IdleRuntimeSessionTimeout` (el valor predeterminado es de 15 minutos) y ahorrar posibles costes excesivos, utilice el siguiente código boto3: ``` 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" ) ``` Al seguir el código boto3, se eliminarán el tiempo de AgentCore ejecución de Amazon Bedrock y el archivo de archivo.zip en 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. ====== Agente de actualización En la página de detalles del agente, selecciona **Actualizar alojamiento** para crear una nueva versión con el código o la configuración actualizados. **Actualice el punto final** Seleccione un punto final de la tabla de puntos finales y elija **Editar** para actualizar la descripción o la versión asociada. **Eliminar punto final** Seleccione un punto final y elija **Eliminar**. Deberás escribir «eliminar» para confirmar la eliminación. **Eliminar agente** En la lista de agentes o en la página de detalles, seleccione su agente y elija **Eliminar** para eliminar el agente y todos los recursos asociados. ## Python-specific conceptos para el despliegue directo de código Obtenga información sobre Python-specific los conceptos relacionados con la implementación directa de código con Amazon Bedrock AgentCore Runtime. **Topics** ### Ruta de búsqueda de dependencias y bibliotecas incluidas en tiempo de ejecución Cuando utilice una instrucción `import` en su código, el tiempo de ejecución de Python buscará en los directorios de su ruta de búsqueda hasta que encuentre el módulo o el paquete. De forma predeterminada, la primera ubicación en la que busca el motor de ejecución es el directorio en el que se descomprime y monta el paquete de implementación.zip (). `/var/task` Puede ver la ruta de búsqueda completa de su agente AgentCore Runtime añadiendo el siguiente fragmento de código. ``` import sys search_path = sys.path print(search_path) ``` También puede agregar dependencias en una carpeta independiente dentro del paquete .zip. Por ejemplo, puedes añadir una versión del SDK de Boto3 a una carpeta de tu paquete .zip llamada. `common` Cuando descomprima y monte el paquete .zip, esta carpeta se colocará dentro del directorio `/var/task`. Para usar una dependencia de una carpeta del paquete de despliegue .zip en su código, utilice una instrucción `import from`. Por ejemplo, para usar una versión de Boto3 de una carpeta denominada `common` en el paquete .zip, utilice la siguiente instrucción. ``` from common import boto3 ``` ### Bytecode de Python y *pycache* carpetas Le recomendamos que no incluya ` pycache ` carpetas en el paquete de despliegue de su agente. El código de bytes de Python que se compila en una máquina de compilación con una arquitectura o un sistema operativo diferentes puede no ser compatible con el AgentCore entorno de ejecución en tiempo de ejecución. ### Paquetes de implementación con bibliotecas nativas Si su función solo usa paquetes y módulos puros de Python, puede utilizar el comando `uv pip install` para instalar las dependencias en cualquier equipo de compilación local y crear el archivo .zip. Muchas bibliotecas de Python populares, incluidas NumPy Pandas, no son Python puro y contienen código escrito en C o C. Cuando agrega bibliotecas que contienen C/C código a su paquete de despliegue, debe compilarlo correctamente para que sea compatible con el entorno de ejecución en AgentCore tiempo de ejecución. La mayoría de los paquetes disponibles en el Python Package Index ([PyPI](https://pypi.org/)) están disponibles como «ruedas» (archivos.whl). Un archivo .whl es un tipo de archivo ZIP que contiene una distribución integrada con binarios precompilados para un sistema operativo y una arquitectura de conjunto de instrucciones en particular. Para que su paquete de implementación sea compatible con Amazon Bedrock AgentCore AgentCore Runtime, debe instalar la rueda para los sistemas operativos Linux y la arquitectura del conjunto de instrucciones **arm64**. Es posible que algunos paquetes solo estén disponibles como distribuciones de código fuente. Para estos paquetes, debe compilar y construir usted mismo los componentes de C/C \+\+. Para ver qué distribuciones están disponibles para el paquete que necesita, haga lo siguiente: 1. Busque el nombre del paquete en la [página principal del Índice de paquetes de Python](https://pypi.org/). 1. Elija la versión del paquete que desea utilizar. 1. Seleccione **Descargar archivos**. ### Uso de distribuciones de código fuente Si tu paquete solo está disponible como distribución de código fuente, tendrás que crear tú mismo las bibliotecas de C/C \+\+. Para que su paquete sea compatible con el entorno de AgentCore AgentCore ejecución Amazon Bedrock Runtime, debe compilarlo en un entorno que utilice el mismo sistema operativo Amazon Linux con el conjunto de instrucciones **arm64**. Para ello, cree su paquete en una instancia Linux de Amazon Elastic Compute Cloud (Amazon EC2). Para obtener más información sobre cómo lanzar y conectarse a una instancia Linux de Amazon EC2, consulte [Get started with Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html) en la *Guía del usuario de Amazon EC2*.