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.

Comience a utilizar las instancias mediante el AWS CLI o SDK

En este tutorial se explica cómo alojar un agente en el tipo de procesamiento de la instancia con la interfaz de línea de AWS comandos (AWS CLI) y los SDK. En primer lugar, debe crear un proveedor de capacidad que defina la infraestructura de Amazon Elastic Compute Cloud (Amazon EC2) y, a continuación, crear un agente en tiempo de ejecución que la utilice y, por último, invocar al agente.

Para conocer los requisitos previos, consulte Cómo empezar con las instancias.

Paso 1: Crear un proveedor de capacidad

Utilice la CreateCapacityProvider operación para definir la infraestructura de EC2. La solicitud consta de una permissionsConfiguration (la función de IAM que se AgentCore utiliza para operar el proveedor de capacidad) y una computeConfiguration que describe las instancias de EC2 mediante una plantilla de lanzamiento. En el siguiente ejemplo, se crea un proveedor de capacidad de Linux con un único tipo de instancia permitido y un volumen de EBS persistente.

Para ejecutar cargas de trabajo de GPU, incluye un tipo de instancia de GPU compatible. allowedInstanceTypes AgentCore aprovisiona los controladores de GPU de la instancia, por lo que las imágenes de contenedor estándar funcionan sin agrupar los controladores. Las familias compatibles son g4dng5,g6,g6e, gr6g6f, gr6fg7e, yinf2. Si incluyes un tipo de instancia aceleradora de una familia no compatible, la solicitud fallará con unValidationException. Para obtener más información, consulta Cómo usar tipos de instancias de GPU.

Realice una encuesta GetCapacityProvider hasta que el estado esté READY antes de asociar el proveedor de capacidad a un tiempo de ejecución. Si el estado pasa a ser el mismoCREATE_FAILED, statusReason inspeccione statusCode y determine la causa.

Paso 2: Cree un agente en tiempo de ejecución en el proveedor de capacidad

Cree un tiempo de ejecución del agente con un capacityProviderConfiguration que haga referencia a su proveedor de capacidad. Para montar un volumen definido en el proveedor de capacidad en el sistema de archivos del agente, añada una capacityProviderVolume entrada filesystemConfigurations que haga referencia al volumen por su nombre. Las rutas de montaje deben estar ubicadas debajo /mnt de un único subdirectorio (por ejemplo,/mnt/scratch).

El tiempo de ejecución del agente tiene el suyo propiolifecycleConfiguration.maxLifetime, cuyo valor predeterminado es de 28800 segundos (8 horas). Este valor debe ser inferior o igual al establecido por maxLifetime el proveedor de capacidad. ec2Configuration.lifecycleConfiguration En el paso 1, el proveedor de capacidad establece ese valor en 3600 segundos (1 hora), por lo que el tiempo de ejecución predeterminado de 8 horas lo superaría y CreateAgentRuntime generaría un ValidationException error. Por lo tanto, en el siguiente ejemplo se establece un tiempo maxLifetime de ejecución de 1800 segundos, lo que está dentro del límite establecido por el proveedor de capacidad.

No apruebe networkConfiguration cuando lo especifiquecapacityProviderConfiguration. El tiempo de ejecución de una instancia hereda su red de la del proveedor de capacidadec2Configuration.vpcConfiguration, por lo que al especificar ambas se produce un error con unValidationException.

Paso 3: Invoca al agente

Invoca el tiempo de ejecución de la misma manera que lo harías con un VM-backed microtiempo de ejecución. Reutiliza lo mismo runtimeSessionId en todas las invocaciones para mantener la sesión en la misma instancia. Esto permite al agente acceder a los datos de las invocaciones anteriores. Para ubicar en un mismo lugar a los agentes colaboradores, utilícelos runtimeSessionId en varios tiempos de ejecución que compartan un proveedor de capacidad.

runtimeSessionIdDebe tener al menos 33 caracteres.

La primera invocación de una nueva sesión aprovisiona una instancia EC2 de su cuenta y lanza el agente, por lo que normalmente tarda más que las invocaciones posteriores. Las invocaciones posteriores a la misma sesión reutilizan la instancia en ejecución y regresan mucho más rápido.

AgentCore aprovisiona estas instancias como instancias administradas de Amazon EC2, que están ocultas DescribeInstances y que su consola EC2 puede ver de forma predeterminada. Una simple aws ec2 describe-instances llamada no las incluye en la lista. Para verlos, incluye los recursos gestionados:

aws ec2 describe-instances --include-managed-resources \
  --filters "Name=tag-key,Values=bedrock-agentcore:capacity-provider-id"

Para obtener más información sobre la administración de la visibilidad de las instancias, consulta la configuración de visibilidad de los recursos administrados.

Co-locate varios agentes en una instancia

Cuando los tiempos de ejecución de dos agentes hacen referencia al mismo proveedor de capacidad y usted los invoca con el mismo nombre runtimeSessionId, ambos agentes se ejecutan en la misma instancia de EC2. Allí, pueden compartir el volumen configurado en la configuración de su sistema de archivos. Los agentes colaboran leyendo y escribiendo archivos en ese volumen compartido; cada agente se invoca de forma independiente y no comparte el estado de ningún otro modo. Por ejemplo, un ejecutor de pruebas puede escribir los resultados en el volumen y, a continuación, un analizador de código invocado en la misma sesión puede leerlos. Para conocer el límite entre los agentes de una instancia compartida, consulta el modelo de seguridad y los permisos para las instancias en tiempo de ejecución.

import boto3
import json

client = boto3.client("bedrock-agentcore", region_name="us-west-2")
session_id = "collab-session-000000000000000000000"

# Agent A — created on capacity provider "my_capacity_provider"
client.invoke_agent_runtime(
    agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/test-runner-suffix",
    runtimeSessionId=session_id,
    payload=json.dumps({"prompt": "Run the test suite for project ABC"}).encode(),
    qualifier="DEFAULT",
)

# Agent B — a different runtime that shares the SAME capacity provider and session ID,
# so it runs on the same instance as Agent A and can read the files Agent A wrote to the shared volume.
client.invoke_agent_runtime(
    agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/code-analyzer-suffix",
    runtimeSessionId=session_id,
    payload=json.dumps({"prompt": "Analyze the code for project ABC"}).encode(),
    qualifier="DEFAULT",
)

Cada agente se ejecuta con sus propias credenciales de IAM derivadas de su función de ejecución en tiempo de ejecución, por lo que puedes conceder diferentes permisos a los agentes colaboradores aunque compartan la misma instancia. Sin embargo, dado que los agentes de la misma instancia no están aislados unos de otros, cualquier agente puede leer las credenciales de otro agente. Co-locate solo agentes en los que se confíe mutuamente. Para obtener más información, consulte el modelo de seguridad y los permisos para las instancias en tiempo de ejecución.

Limpiar: detener y eliminar sesiones

Una sesión puede alojar varios tiempos de ejecución de agentes en la misma instancia, por lo que AgentCore ofrece dos operaciones distintas:

Para detener el tiempo de ejecución de un agente específico en una sesión, llame a la StopRuntimeSession operación con el ARN del tiempo de ejecución y el ID de la sesión.

Para eliminar una sesión y desaprovisionar todos sus recursos (incluidos los volúmenes de EBS persistentes), llame DeleteCapacityProviderSession con el ID del proveedor de capacidad y el ID de la sesión. La operación es idempotente y asincrónica: retorna inmediatamente mientras AgentCore termina la instancia y elimina los volúmenes en segundo plano.

Los identificadores de sesión son valores que se proporcionan al invocar y no hay ninguna operación que muestre las sesiones de un proveedor de capacidad. Lleve un registro de los runtimeSessionId valores que utiliza para poder eliminar cada sesión posteriormente. Si ya no los tiene, puede buscar las instancias que aún se están ejecutando y, a continuación, eliminar el proveedor de capacidad para anular el aprovisionamiento de todas sus sesiones:

aws ec2 describe-instances --include-managed-resources \
  --filters "Name=tag-key,Values=bedrock-agentcore:capacity-provider-id" \
  --query 'Reservations[].Instances[?State.Name!=`terminated`].[InstanceId,State.Name]'

Eliminar un proveedor de capacidad

Cuando ya no necesite un proveedor de capacidad, elimínelo con la DeleteCapacityProvider operación. Al eliminar un proveedor de capacidad, se detienen y se eliminan todas sus sesiones asociadas y su almacenamiento persistente, por lo que también sirve para limpiar las sesiones cuyos ID ya no tienes. No es necesario eliminar primero las sesiones. Sin embargo, es necesario eliminar los tiempos de ejecución que hacen referencia al proveedor de capacidad: eliminar primero las versiones, los puntos finales o los tiempos de ejecución asociados, o la solicitud de eliminación fallará con un. ValidationException La operación es asincrónica; identifique el proveedor de capacidad por su ID.