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
Con la implementación directa de código, empaquetas el código del agente de Python y sus dependencias en un archivo zip y lo despliegas en AgentCore Tiempo de ejecución. Tu agente aún tiene que seguirte AgentCore Requisitos de tiempo de ejecución : tienen un archivo de punto de entrada .py que utilice el @app.entrypoint anotación de Amazon Bedrock AgentCore SDK de Python o implementa /invocations POST y /ping Puntos finales de servidor GET.
Esta página incluye un resumen AgentCore Ruta de la CLI e instrucciones detalladas para empaquetar e implementar el archivo .zip manualmente con uv, Boto3 o el AWS Consola de administración. Para ver el flujo de trabajo completo de la CLI, consulte Comience con AgentCore Tiempo de ejecución con AgentCore CLI.
Requisitos previos
Antes de comenzar, asegúrese de que dispone de lo siguiente:
Paso 1: Prepara y prueba tu agente de Python
Tu proyecto debe contener los archivos que añadirás al paquete de despliegue:
my-agent/
├── main.py
└── pyproject.toml
Ejecute el agente localmente mediante el comando de su aplicación. Para un punto de entrada desde el que se inicia su servidor main.py, ejecute:
uv run main.py
En otro terminal, pruebe el /invocations punto final:
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, introduzca Ctrl+C para detener al agente.
Si lo desea, ejecute uv add aws-opentelemetry-distro para habilitar Amazon Bedrock AgentCore rastros de observabilidad.
Paso 2: Habilite la observabilidad para su agente
Amazon Bedrock AgentCore Observabilidad le ayuda a rastrear, depurar y supervisar los agentes que aloja AgentCore Tiempo de ejecución. Primero, habilita CloudWatch Busque transacciones siguiendo las instrucciones que se encuentran en Habilitar Amazon Bedrock AgentCore observabilidad en tiempo de ejecución . Para observar a su agente, consulte Consulte los datos de observabilidad de su Amazon Bedrock AgentCore agentes.
Paso 3: Empaquetar, implementar e invocar
Empaquete e implemente su agente mediante uno de los siguientes métodos:
ejemplo
- AgentCore CLI
-
-
Para un CLI-managed CodeZip proyecto, el AgentCore La CLI empaqueta e implementa el proyecto por usted. Para implementar su agente actual con el AgentCore CLI, cree un proyecto a partir de la plantilla mínima:
agentcore create --name DirectDeployProject --template agent-python-minimal
cd DirectDeployProject
Copia tu main.py y pyproject.toml en app/agent/, reemplazando los archivos generados. A continuación, despliegue el proyecto:
agentcore deploy
Si lo desea, ejecute agentcore build primero en sintetizar y comprobar el proyecto sin implementarlo.
Invoca el Runtime desplegado:
agentcore invoke --runtime agent \
--payload '{"prompt":"Hello!"}'
También puedes ejecutar agentcore sin argumentos para abrir la interfaz de usuario interactiva del terminal, luego elija desplegar para observar el progreso de la implementación. Para ver las pruebas locales, consulte Comience con AgentCore Tiempo de ejecución con AgentCore CLI.
- Boto3
-
-
Para descargar una rueda que sea compatible con AgentCore En tiempo de ejecución, se usa el uv pip --python-platform opción. AgentCore Runtime solo admite la arm64 arquitectura. Ejecute el siguiente comando y reemplace 3.13 en --python-version con tu versión de Python.
uv pip install \
--python-platform aarch64-manylinux2014 \
--python-version 3.13 \
--target=deployment_package \
--only-binary=:all: \
-r pyproject.toml
Crea 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 el archivo y otros 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 Ejecute o actualice uno existente. Puede implementar su paquete .zip mediante el AgentCore API de tiempo de ejecución, la AgentCore La consola Runtime o la AWS Interfaz de línea de comandos.
El tamaño máximo de un paquete de implementación .zip para AgentCore El tiempo de ejecución es de 250 MB (comprimido) y 750 MB (descomprimido). 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 su 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 conceder los permisos correctos a un archivo no ejecutable, ejecute 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 AgentCore Ejecute los permisos que necesita para acceder a los directorios de su paquete de implementación, AgentCore Runtime establece los permisos de esos directorios en 755 (rwxr-xr-x).
Un archivo ZIP que contiene Linux arm64 las dependencias deben cargarse a S3 como requisito previo para crear Agent Runtime. El siguiente código requiere que el bucket de S3 especificado ya exista. Para crear un bucket, consulte create_bucket en la documentación de Boto3. El siguiente código boto3 cargará el archivo .zip a un s3 y creará Amazon Bedrock AgentCore tiempo de ejecución.
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 Invoca agentes de streaming.
- AWS Management Console
-
Puede implementar su agente mediante Amazon Bedrock AgentCore consola con soporte de tiempo de ejecución gestionado.
Para realizar la implementación mediante la consola, primero cree el paquete de implementación siguiendo los pasos del Boto 3 pestaña de arriba.
Crea un agente a través de la consola
Para crear tu agente:
-
En la página de inicio de los agentes, elige Agente anfitrión
-
Elija su selección de fuente:
-
Fuente S3 - Subir desde el bucket S3
-
Carga local - Sube un archivo ZIP desde tu ordenador
-
Plantillas - Utilice plantillas de agentes 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 o utilizar la existente)
-
Elige Crear agente para implementar
Crear un punto final
Elige 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 Punto final de prueba para navegar hasta el Playground/Sandbox para realizar pruebas.
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 AgentCore Permisos de ejecución . La función de ejecución debe incluir Amazon Bedrock básico AgentCore los permisos de tiempo de ejecución, los permisos de acceso a S3 para su paquete de implementación y CloudWatch Registra los permisos para garantizar la observabilidad.
Paso 4: Detener una sesión, actualizarla o limpiarla
Detenga la sesión de ejecución, actualice o limpie el agente mediante uno de los siguientes métodos:
ejemplo
- AgentCore CLI
-
-
Vuelva a implementar el proyecto para actualizar el Runtime:
agentcore deploy
Para eliminar los recursos implementados del proyecto, elimínelos del proyecto e implemente la configuración actualizada:
agentcore remove all --yes
agentcore deploy --yes
Para detener una sesión de Runtime activa, usa el StopRuntimeSession Operación de API.
- Boto3
-
-
El siguiente código boto3 actualizará un AgentCore Tiempo de ejecución.
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 configurable IdleRuntimeSessionTimeout (el valor predeterminado es de 15 minutos) y ahorrar en cualquier posible coste adicional, 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"
)
El siguiente código boto3 eliminará Amazon Bedrock AgentCore runtime y 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!")
- AWS Management Console
-
Agente de actualización
En la página de detalles del agente, seleccione Actualiza el alojamiento para crear una nueva versión con el código o la configuración actualizados.
Actualizar 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 del código
Obtenga más información sobre Python-specific conceptos sobre el uso de la implementación directa de código con Amazon Bedrock AgentCore 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 está descomprimido y montado el paquete de implementación .zip ( /var/task ).
Puedes ver la ruta de búsqueda completa de tu AgentCore Para ejecutar el agente, agrega 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 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 populares de Python, entre las que se incluyen NumPy y Pandas, no son Python puro y contienen código escrito en C o C. Cuando agregas bibliotecas que contienen C/C código a tu paquete de despliegue, debes compilarlo correctamente para que sea compatible con el AgentCore Entorno de ejecución en tiempo de ejecución.
La mayoría de los paquetes están 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, instala la rueda para los sistemas operativos Linux y arm64 arquitectura del conjunto de instrucciones.
Es posible que algunos paquetes solo estén disponibles como distribuciones de código fuente. Para estos paquetes, es necesario compilar y construir el C/C++ componentes 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 el C/C++ bibliotecas tú mismo. Para que su paquete sea compatible con Amazon Bedrock AgentCore Entorno de ejecución en tiempo de ejecución, debe crearlo en un entorno que utilice el mismo sistema operativo Amazon Linux con arm64 conjunto de instrucciones. 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.