Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
Despliegue directo de código para Python
La implementación directa de código le permite llevar 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 los requisitos de AgentCore tiempo de ejecución: tener un archivo de punto de entrada .py que utilice la @app.entrypoint anotación del SDK de AgentCore Python de Amazon Bedrock o implemente los puntos de enlace del servidor POST y GET. /invocations /ping
Requisitos previos
Antes de comenzar, asegúrese de que dispone de lo siguiente:
Paso 1: Instale la CLI AgentCore
Instale la AgentCore CLI:
npm install -g @aws/agentcore
Paso 2: Cree su proyecto de agente
Crea un AgentCore proyecto para el tutorial:
agentcore create \
--project-name DirectDeployProject \
--name DirectDeployAgent \
--language Python \
--framework Strands \
--model-provider Bedrock \
--memory none \
--build CodeZip
cd DirectDeployProject
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
-
Un proyecto agentcore/cdk/ de infraestructura
Lo generado pyproject.toml incluye las dependencias de Strands AgentCore y Strands. Uv crea el entorno virtual y bloquea el archivo durante la creación del proyecto.
Si lo desea, ejecútelo cd app/DirectDeployAgent && uv add aws-opentelemetry-distro && cd ../.. para habilitar los rastreos de AgentCore observabilidad de Amazon Bedrock.
Paso 3: Realice una prueba local
Asegúrese de que el puerto 8080 esté libre antes de comenzar. Consulte Solucionar problemas si el puerto ya está en uso.
Abra una ventana de terminal e inicie el agente con el siguiente comando:
agentcore dev --no-browser
Pon a prueba tu agente abriendo otra ventana de terminal e introduciendo 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 del terminal en la que se ejecuta el agente, escribe Ctrl+C para detener el agente.
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, habilite CloudWatch la búsqueda de transacciones siguiendo las instrucciones que aparecen en Habilitar la observabilidad en tiempo de ejecución de Amazon Bedrock AgentCore . Para observar a su agente, consulte Ver los datos de observabilidad de sus agentes de Amazon Bedrock. AgentCore
Paso 5: Despliegue en AgentCore Runtime e invoque
Implemente su agente mediante uno de los siguientes métodos:
ejemplo
- AgentCore CLI
-
-
Los pasos siguientes implementan el CodeZip proyecto creado en el paso 2. Para obtener más información, consulte Introducción a la AgentCore CLI. Se requiere UV para crear y empaquetar el proyecto Python.
Una vez que hayas configurado tu agenteagentcore create, usa el deploy comando para crear un paquete de despliegue zip, subirlo al bucket especificado e implementar el agente.
agentcore deploy
¡Vamos a pedirle al agente que cuente un chiste!
agentcore invoke "Tell me a joke"
La primera implementación requiere tiempo para instalar las dependencias, pero las actualizaciones posteriores del agente lo optimizan 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 te permite actualizar los parámetros de implementación, 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
-
-
Ejecuta agentcore para abrir la TUI y, a continuación, selecciona implementar. La pantalla de implementación 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 utilícela para probar su agente.
- Custom zip + boto3
-
-
Para descargar una rueda que sea compatible con AgentCore Runtime, utiliza la --python-platform opción uv pip. AgentCore Runtime solo admite la arquitectura del conjunto de instrucciones arm64, ejecuta 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 .
Agregue 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
Después de crear el paquete de implementación .zip, puede usarlo para crear un nuevo AgentCore Runtime o actualizar uno existente. Puedes implementar tu 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 el archivo.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). Ten en cuenta que este límite se aplica al tamaño combinado de todos los archivos que subas. El AgentCore Runtime necesita permiso para leer los archivos de tu paquete de implementación. En la notación octal de los 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 dar a un archivo no ejecutable los permisos correctos, 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).
Como requisito previo para crear Agent Runtime, es necesario subir a S3 un archivo ZIP que contenga las dependencias de arm64 de Linux. El código siguiente requiere que el bucket de S3 especificado ya exista. Siga la AWS documentación que aparece aquí para crear un bucket con boto3. El siguiente código boto3 cargará el archivo.zip en un s3 y creará Amazon Bedrock Runtime. 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. Invoca un agente mediante programación
- console
-
-
Puede implementar su agente mediante la consola de Amazon Bedrock con soporte de tiempo de ejecución gestionado AgentCore . La consola proporciona una interfaz intuitiva para cargar archivos ZIP y configurar los ajustes del agente.
Para realizar la implementación con la consola, primero cree el paquete de implementación siguiendo los pasos de la pestaña zip + boto3 personalizada que aparece más arriba.
Cree un agente a través de la consola
Para crear tu agente:
-
En la página de inicio de los agentes, elija Host Agent
-
Elige tu selección de fuente:
-
Fuente de S3: se carga desde el bucket de S3
-
Carga local: sube un archivo ZIP desde tu 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 (p. ej.,main.py)
-
Función de ejecución (crear una nueva función o utilizar la existente)
-
Elija Crear agente para implementarlo
Cree un punto final
Seleccione Crear punto final para crear un nuevo punto final para su agente. El nombre del punto final y la versión asociada se rellenarán previamente.
Punto final de prueba
Seleccione un punto final y elija el punto final de la prueba para acceder al punto final Playground/Sandbox de la prueba.
Requisitos del rol 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. El rol 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 su paquete de implementación y los permisos de CloudWatch registro para garantizar la observabilidad.
Paso 6: Detener la sesión, actualizar o limpiar
Detenga la sesión de ejecución, actualice o limpie el agente mediante uno de los siguientes métodos:
ejemplo
- AgentCore CLI
-
-
Para actualizar el AgentCore Runtime previamente implementado, ejecute:
agentcore deploy
Para detener una sesión en ejecución antes de la configurable IdleRuntimeSessionTimeout (el valor predeterminado es de 15 minutos) y ahorrar cualquier posible coste adicional, utiliza la operación de la StopRuntimeSession API. Actualmente, la AgentCore CLI no admite la interrupción directa de las sesiones.
Para eliminar todos los recursos relacionados con un AgentCore tiempo de ejecución, primero elimine todos los recursos y, a continuación, AWS impleméntelos para eliminarlos:
agentcore remove all
agentcore deploy
- boto3
-
-
El siguiente código boto3 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 que la configurable IdleRuntimeSessionTimeout (el valor predeterminado es de 15 minutos) y ahorrar cualquier posible coste adicional, utiliza 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"
)
El siguiente código boto3 eliminará el archivo archivo.zip y el tiempo de ejecución de Amazon Bedrock AgentCore 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, seleccione 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, selecciona tu agente y elige Eliminar para eliminar el agente y todos los recursos asociados.
Python-specific conceptos para la implementación directa de código
Obtenga más información sobre Python-specific los conceptos relacionados con el uso de 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
Puedes ver la ruta de búsqueda completa de tu agente AgentCore de 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. Es posible que el código de bytes de Python compilado en una máquina de compilación con una arquitectura o un sistema operativo diferentes no sea compatible con el AgentCore entorno de ejecución Runtime.
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 populares de Python, incluidas NumPy las de Pandas, no son solo Python y contienen código escrito en C o C. Cuando añadas bibliotecas que contienen C/C código a tu paquete de despliegue, debes compilarlo correctamente para que sea compatible con el entorno de AgentCore ejecución de Runtime.
La mayoría de los paquetes disponibles en el índice de paquetes de Python (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 Runtime, instale 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 los componentes C/C ++ usted mismo.
Para ver qué distribuciones están disponibles para el paquete que necesita, haga lo siguiente:
Si su paquete solo está disponible como una distribución fuente, debe crear las bibliotecas C/C ++ usted mismo. Para que su paquete sea compatible con el entorno de AgentCore ejecución de 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.
