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 ](runtime-instances-how-it-works.md#runtime-instances-capacity-provider) 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. ](runtime-instances-getting-started.md)
**nota**
Los nombres de los parámetros de estos ejemplos siguen el modelo del plano AgentCore de control. Para ver las formas autorizadas de solicitud y respuesta, consulte la referencia de la API de AgentCore control de [ Amazon Bedrock. ](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/Welcome.html)
## 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.
**Example**
1.
```
aws bedrock-agentcore-control create-capacity-provider \
--name "my_capacity_provider" \
--permissions-configuration '{
"capacityProviderOperatorRoleArn": "arn:aws:iam::111122223333:role/AgentCoreCapacityProviderOperatorRole"
}' \
--compute-configuration '{
"ec2Configuration": {
"launchTemplateSource": {
"launchParameters": {
"operatingSystem": "LINUX_X86_64",
"instanceRequirements": {
"allowedInstanceTypes": ["m5.large"]
}
}
},
"vpcConfiguration": {
"subnets": ["subnet-0123456789abcdef0"],
"securityGroups": ["sg-0123456789abcdef0"]
},
"lifecycleConfiguration": {
"maxLifetime": 3600
},
"volumes": [
{ "ebsConfiguration": { "name": "scratch", "sizeGiB": 50, "volumeType": "gp3" } }
]
}
}'
```
1. Ejemplo de Python en el que se usa boto3 para crear un proveedor de capacidad.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.create_capacity_provider(
name="my_capacity_provider",
permissionsConfiguration={
"capacityProviderOperatorRoleArn": "arn:aws:iam::111122223333:role/AgentCoreCapacityProviderOperatorRole"
},
computeConfiguration={
"ec2Configuration": {
"launchTemplateSource": {
"launchParameters": {
"operatingSystem": "LINUX_X86_64",
"instanceRequirements": {
"allowedInstanceTypes": ["m5.large"],
},
}
},
"vpcConfiguration": {
"subnets": ["subnet-0123456789abcdef0"],
"securityGroups": ["sg-0123456789abcdef0"],
},
"lifecycleConfiguration": {
"maxLifetime": 3600,
},
"volumes": [
{"ebsConfiguration": {"name": "scratch", "sizeGiB": 50, "volumeType": "gp3"}}
],
}
},
)
print(f"Capacity provider ARN: {response['capacityProviderArn']}")
```
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 `g4dn``g5`,`g6`,`g6e`, `gr6``g6f`, `gr6f``g7e`, y`inf2`. Si incluyes un tipo de instancia aceleradora de una familia no compatible, la solicitud fallará con un`ValidationException`. Para obtener más información, consulta Cómo [ usar tipos ](runtime-instances-how-it-works.md#runtime-instances-gpu) 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 mismo`CREATE_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 propio`lifecycleConfiguration.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.
**nota**
Ambos recursos utilizan un `lifecycleConfiguration` miembro, pero son estructuras diferentes. La versión del proveedor de capacidad toma `idleInstanceTimeout` `maxLifetime` y se aplica a la instancia. La versión del tiempo de ejecución del agente toma `idleRuntimeSessionTimeout` `maxLifetime` y se aplica a la sesión. Para obtener más información, consulte [ Configurar los ajustes ](runtime-lifecycle-settings.md) del AgentCore ciclo de vida de Amazon Bedrock.
No apruebe `networkConfiguration` cuando lo especifique`capacityProviderConfiguration`. El tiempo de ejecución de una instancia hereda su red de la del proveedor de capacidad`ec2Configuration.vpcConfiguration`, por lo que al especificar ambas se produce un error con un`ValidationException`.
**Example**
1.
```
aws bedrock-agentcore-control create-agent-runtime \
--agent-runtime-name "my_instances_agent" \
--role-arn "arn:aws:iam::111122223333:role/AgentRuntimeRole" \
--agent-runtime-artifact '{
"containerConfiguration": {
"containerUri": "111122223333.dkr.ecr.us-west-2.amazonaws.com/my-agent:latest"
}
}' \
--capacity-provider-configuration '{
"capacityProviderArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:capacity-provider/my_capacity_provider-a1b2c3d4e5"
}' \
--lifecycle-configuration '{
"idleRuntimeSessionTimeout": 300,
"maxLifetime": 1800
}' \
--filesystem-configurations '[
{
"capacityProviderVolume": { "volumeName": "scratch", "mountPath": "/mnt/scratch" }
}
]'
```
1. Ejemplo de Python en el que se usa boto3 para crear un tiempo de ejecución de agente en las instancias.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.create_agent_runtime(
agentRuntimeName="my_instances_agent",
roleArn="arn:aws:iam::111122223333:role/AgentRuntimeRole",
agentRuntimeArtifact={
"containerConfiguration": {
"containerUri": "111122223333.dkr.ecr.us-west-2.amazonaws.com/my-agent:latest"
}
},
capacityProviderConfiguration={
"capacityProviderArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:capacity-provider/my_capacity_provider-a1b2c3d4e5",
},
lifecycleConfiguration={
"idleRuntimeSessionTimeout": 300,
"maxLifetime": 1800,
},
filesystemConfigurations=[
{
"capacityProviderVolume": {"volumeName": "scratch", "mountPath": "/mnt/scratch"}
}
],
)
print(f"Agent runtime ARN: {response['agentRuntimeArn']}")
```
## 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.
**Example**
1.
```
echo '{"prompt": "Analyze the sales data and summarize the key trends."}' > payload.json
aws bedrock-agentcore invoke-agent-runtime \
--agent-runtime-arn "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/my_instances_agent-suffix" \
--runtime-session-id "project-xyz-0000000000000000000000000000" \
--qualifier "DEFAULT" \
--payload fileb://payload.json \
response.json
```
El `payload` parámetro es un blob binario y la AWS CLI espera que los blobs estén codificados en base64 de forma predeterminada. Al pasar JSON sin procesar en línea, por ejemplo, se produce un error en el lado del cliente y se produce un `Invalid base64` error antes de que la solicitud llegue al servicio. `--payload '{"prompt": "…"}'` El `fileb://` formulario que se usa aquí lee el archivo como binario independientemente de la `cli_binary_format` configuración, por lo que evita el paso de codificación.
La respuesta del agente es un blob de transmisión que la AWS CLI escribe en el archivo de salida que usted nombra como último argumento, en este ejemplo`response.json`. La salida estándar solo contiene los `statusCode` campos `runtimeSessionId``contentType`, y, por lo tanto, lea el archivo de salida para ver qué ha devuelto el agente.
AWS SDK
1. Ejemplo de Python en el que se usa boto3 para invocar el tiempo de ejecución de un agente en las instancias.
```
import boto3
import json
client = boto3.client("bedrock-agentcore", region_name="us-west-2")
response = client.invoke_agent_runtime(
agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/my_instances_agent-suffix",
runtimeSessionId="project-xyz-0000000000000000000000000000", # 33+ chars; reuse to keep the session
payload=json.dumps({"prompt": "Analyze the sales data and summarize the key trends."}).encode(),
qualifier="DEFAULT",
)
print("Agent response:", json.loads(response["response"].read()))
```
`runtimeSessionId`Debe 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](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/amazon-ec2-managed-instances.html), 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](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/amazon-ec2-managed-instances.html#managed-resource-visibility-settings).
## 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. ](runtime-instances-security.md)
```
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](runtime-instances-security.md).
## Limpiar: detener y eliminar sesiones
**aviso**
Para evitar que se sigan cobrando las instancias de Amazon EC2 y los volúmenes de Amazon EBS aprovisionados en su cuenta, elimine las sesiones y los proveedores de capacidad que ya no necesite cuando termine este tutorial.
Una sesión puede alojar varios tiempos de ejecución de agentes en la misma instancia, por lo que AgentCore ofrece dos operaciones distintas:
+ **Detener el tiempo de ejecución de un agente en una sesión**: `StopRuntimeSession` detiene el tiempo de ejecución de un solo agente dentro de una sesión, identificado por el ARN del tiempo de ejecución y el ID de la sesión. Los tiempos de ejecución de otros agentes que comparten la misma sesión e instancia no se ven afectados.
+ **Eliminar una sesión**: `DeleteCapacityProviderSession` elimina toda la sesión y desaprovisiona los recursos de EC2 creados en su cuenta (instancia, interfaz de red y cualquier volumen de EBS persistente), de modo que deja de incurrir en costos de infraestructura y almacenamiento.
Para detener el tiempo de ejecución de un agente específico en una sesión, llame a la [ StopRuntimeSession ](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_StopRuntimeSession.html) operación con el ARN del tiempo de ejecución y el ID de la sesión.
**Example**
1.
```
aws bedrock-agentcore stop-runtime-session \
--agent-runtime-arn "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/my_instances_agent-suffix" \
--runtime-session-id "project-xyz-0000000000000000000000000000"
```
1. Ejemplo de Python en el que se usa boto3 para detener una sesión en tiempo de ejecución.
```
import boto3
client = boto3.client("bedrock-agentcore", region_name="us-west-2")
client.stop_runtime_session(
agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/my_instances_agent-suffix",
runtimeSessionId="project-xyz-0000000000000000000000000000",
)
```
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]'
```
**Example**
1.
```
aws bedrock-agentcore delete-capacity-provider-session \
--capacity-provider-id "my_capacity_provider-a1b2c3d4e5" \
--session-id "project-xyz-0000000000000000000000000000"
```
1. Ejemplo de Python en el que se usa boto3 para eliminar una sesión de un proveedor de capacidad.
```
import boto3
client = boto3.client("bedrock-agentcore", region_name="us-west-2")
response = client.delete_capacity_provider_session(
capacityProviderId="my_capacity_provider-a1b2c3d4e5",
sessionId="project-xyz-0000000000000000000000000000",
)
print("Session status:", response["status"])
```
## 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.
**Example**
1.
```
aws bedrock-agentcore-control delete-capacity-provider \
--capacity-provider-id "my_capacity_provider-a1b2c3d4e5"
```
1. Ejemplo de Python en el que se usa boto3 para eliminar un proveedor de capacidad.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
client.delete_capacity_provider(
capacityProviderId="my_capacity_provider-a1b2c3d4e5",
)
```