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: tener un archivo.py de punto de entrada que utilice la @app.entrypoint anotación del SDK de AgentCore Python de Amazon Bedrock 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:
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:
Si lo desea, ejecute uv add aws-opentelemetry-distro para habilitar los rastreos de AgentCore observabilidad de Amazon Bedrock.
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.
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 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. Para observar a su agente, consulte Ver datos de observabilidad de sus agentes de Amazon Bedrock AgentCore .
Paso 5: Implemente en AgentCore Runtime e invoque
Implemente su agente mediante uno de los siguientes métodos:
ejemplo
- AgentCore CLI
-
-
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. 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 medianteagentcore 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.
- Interactive
-
-
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
Una vez completada la implementación, agentcore invoke úselo para probar su agente.
- Custom zip + boto3
-
-
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.
. 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 <filepath> Para cambiar los permisos de los archivos en Windows, consulte Set, View, Change, or Remove Permissions on an Object 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í 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.
- console
-
-
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:
-
En la página de inicio del agente, selecciona Host Agent
-
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
-
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)
-
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. 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:
ejemplo
- AgentCore CLI
-
-
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 StopRuntimeSessionAPI. 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
- boto3
-
-
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='<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']}")
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='<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
-
-
====== 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.
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
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.
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) 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:
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 en la Guía del usuario de Amazon EC2.
