Los agentes hoy revisan el código, procesan reclamos y se ejecutan sin supervisión durante horas. Muchos también se encuentran detrás de experiencias interactivas donde una persona espera la primera respuesta. Amazon Bedrock AgentCore runtime proporciona a estos agentes un entorno completamente administrado y sin servidor: cada sesión se ejecuta en su propia microVM aislada, la plataforma se escala a cero cuando no hay trabajo y solo paga por los recursos que consumen sus sesiones.

AgentCore runtime con platformVersion establecido en “V2” cambia la forma en que comienzan las sesiones. En lugar de inicializar su contenedor para cada sesión, prepara su entorno una vez, crea una instantánea de él y restaura esa instantánea para cada nueva sesión. Los tiempos de inicio de sesión son más rápidos y consistentes. V2 también recupera la memoria que sus sesiones no utilizan, por lo que su factura sigue lo que su agente utiliza.

Para la mayoría de los agentes, cambiar a V2 es todo lo que se necesita. Algunos agentes necesitan reestructuración para obtener el beneficio completo, y para experiencias de chat y voz, incluso 2 segundos es demasiado lento. Esta publicación explica cómo V2 inicia una sesión, cómo medir el tiempo de inicio de sesión y cómo mantener el trabajo fuera de la primera solicitud, incluidos los ganchos de compilación, que AgentCore runtime ahora admite. Cubrimos cuatro patrones, desde cambios en el código de su agente hasta iniciar sesiones antes de que los usuarios las necesiten.

¿Qué patrón necesita?

Cómo V2 inicia una sesión

AgentCore runtime ejecuta cada sesión en una nueva microVM. En V1, AgentCore extrae la imagen del contenedor de Amazon Elastic Container Registry (Amazon ECR), inicia el contenedor y ejecuta su código de inicialización antes de que pueda procesar la primera solicitud. La extracción de la imagen domina, por lo que el inicio en frío crece con el tamaño de la imagen.

V2 realiza ese trabajo una sola vez. Cuando crea o actualiza un runtime, el runtime de AgentCore inicia su contenedor en una microVM fresca y espera el primer ping saludable (GET /ping), que debe llegar dentro de 120 segundos. Luego, limpia la caché de archivos del sistema operativo para mantener la instantánea pequeña, congela la microVM y almacena su memoria y disco como una instantánea.

Este es un cambio con respecto a V1: cada creación o actualización ahora lleva unos minutos mientras se construye la instantánea.

En esta publicación, init se refiere a todo lo que su agente hace antes de que /ping informe que está saludable. Con el SDK de Python de AgentCore, eso es todo antes de app.run(). Si ejecuta su propio servidor HTTP, en Node.js o en otro lenguaje, informe que está saludable solo después de que termine su inicialización.

Figura 1: Compilación, una vez por creación o actualización

Cuando llega una nueva sesión, AgentCore restaura la instantánea en una nueva microVM. Su proceso se reanuda exactamente donde se congeló, con sus importaciones, objetos y clientes en su lugar. Los archivos de su imagen se cargan de forma diferida: cada bloque se recupera la primera vez que una sesión lo lee.

Figura 2: Invocación, cada nueva sesión

Tres hechos se derivan de estos flujos, y el resto de esta publicación se basa en ellos:

• La memoria vuelve completa. Cualquier cosa que su proceso mantuviera en el momento de la instantánea, y cualquier cosa en un sistema de archivos con respaldo de RAM como /dev/shm, está disponible a velocidad de memoria desde el primer acceso.
• Las lecturas de archivos no se transfieren. La caché de archivos se limpia antes de la congelación, por lo que leer un archivo durante la inicialización no lo hace rápido en una sesión restaurada.
• Los archivos de la imagen se recuperan al leerlos por primera vez. La primera lectura de un bloque proviene del almacenamiento de la instantánea y luego se almacena en caché más cerca del host.

La siguiente tabla muestra lo que esto significa para el trabajo que realiza un agente típico, dependiendo de dónde lo realice:

Si conoce AWS Lambda SnapStart, esto le resultará familiar. La publicación de Marc Brooker sobre cómo SnapStart carga instantáneas y la publicación de estrategias de preparación de SnapStart son útiles como fondo.

Todo en la tabla asume que su agente puede mantener lo que necesita en su propio proceso. Eso no siempre es posible. Una CLI que se ejecuta como un proceso separado y sale, o un binario del navegador, se lee durante la inicialización y luego se va, así que una sesión restaurada lo recupera de la imagen nuevamente. Para estos casos, puede agregar un hook de compilación, cubierto en “Trabajar con hooks”. La Figura 3 muestra dónde se ejecuta.

Figura 3: Compilación e invocación con hooks

Mida antes de optimizar

La latencia en una aplicación agente no es un solo número. Una solicitud pasa tiempo en el runtime de AgentCore preparando una sesión para ejecutar su código, luego en su código: llamadas de modelo, llamadas de herramientas, subagentes y transmisión de la respuesta. Usted soluciona estos de diferentes maneras, así que comience encontrando cuál es el que domina.

AgentCore runtime publica tanto como métricas de Amazon CloudWatch en el espacio de nombres AWS/Bedrock-AgentCore. Latency es el tiempo hasta el primer byte. OverheadLatency es la parte que pertenece a la plataforma, como iniciar el microVM y restaurar la instantánea en una nueva sesión.

Init no aparece en estas métricas porque en V2 se ejecuta una vez, mientras se construye la instantánea, y no en cada sesión. Agrega a cuánto tiempo tarda una creación o actualización en alcanzar READY, no a la latencia de la solicitud. Para ver cuánto tiempo tarda, registrelo una vez antes de app.run(). La línea aparece en los registros de compilación de tu runtime:

import time
INIT_START = time.time()  # first line of your module
# imports, clients, data loading ...
print(f"init_ms={round((time.time() - INIT_START) * 1000)}")
app.run()

Cómo leer la división:

• Alto OverheadLatency en nuevas sesiones: el tiempo está en el inicio de la sesión. Utilice los patrones más adelante en esta publicación para iniciar sesiones antes de que los usuarios las necesiten.
• El tiempo de tu código es mucho mayor en la primera solicitud que en la segunda en la misma sesión: el trabajo que pertenece a init se está ejecutando en tu controlador. Agregue spans personalizados en AgentCore Observability (una capacidad de Amazon Bedrock AgentCore) alrededor de la configuración de herramientas, cargas de archivos y importaciones tardías para encontrarlo, luego muévalo a init.

Informe percentiles como P90 y P99, o medias recortadas como TM90, que promedian las solicitudes más rápidas del 90% y descartan la cola más lenta. Un promedio simple oculta las solicitudes lentas. OverheadLatency cubre solicitudes a sesiones en ejecución, así como nuevas, por lo que su distribución depende de cuántas de tus solicitudes inician una nueva sesión. Compare corridas con una mezcla similar.

Pruebe a la tasa de nuevas sesiones que espera en producción, no con un puñado de sesiones después de una implementación.

Para incluir el tiempo de red desde tu cliente, mida en el cliente también. Cronometre la llamada a invoke, haga que su controlador devuelva cuánto tiempo se ejecutó y reste. Ambas marcas de tiempo provienen de la misma máquina, por lo que las diferencias de reloj entre el cliente y el microVM no importan. Si transmite, los eventos muy pequeños pueden retrasarse hasta que se acumulen unos pocos cientos de bytes de salida, por lo que el tiempo hasta el primer evento puede leer más alto que el inicio de la sesión.

Mantenga el trabajo fuera de la primera solicitud

El consejo habitual para el arranque en frío es importar de forma diferida y mantener la inicialización pequeña. En V2, haz lo contrario: la inicialización se ejecuta una vez, cuando se crea la instantánea, y el trabajo diferido al controlador se paga con cada nueva sesión. Esto se aplica al trabajo estático: importaciones, clientes y datos de tu imagen. Los datos dinámicos no se pueden capturar en una instantánea. La siguiente sección cubre esto.

Los agentes que más notan son aquellos que leen archivos grandes desde su imagen en el momento de la solicitud: pesos para un modelo local pequeño, incrustaciones, conjuntos de datos, bibliotecas grandes, un binario de navegador para automatización o una cadena de herramientas de línea de comandos que un agente de codificación ejecuta como subprocessos. Leer muchos archivos pequeños, como compilar un proyecto de TypeScript, tiene el mismo efecto. Un agente que importa unas pocas bibliotecas y llama a un modelo alojado principalmente necesita obtener sus importaciones y clientes correctos.

Cómo reestructurar tu agente

Crea objetos durante la inicialización, no solo importaciones. Crear un objeto carga los módulos de los que depende y los mantiene en memoria activa. Inicializa herramientas locales que utilizan bibliotecas externas durante la inicialización también, no cuando el agente las llama por primera vez.

Crea tus clientes durante la inicialización. La resolución de puntos de conexión, la resolución de credenciales y los módulos del cliente regresan con la instantánea. Los sockets no, pero los clientes boto3 se reconectan limpiamente en la primera llamada. Algunos otros clientes de red intentan primero el socket obsoleto, lo que agrega cientos de milisegundos, así que cierra sus conexiones antes de la instantánea.

Mantén los datos estáticos en memoria, como las solicitudes, la materia frontal de habilidades, la configuración y los índices pequeños. Mantén los datos en un objeto, no solo una lectura de ellos:

INDEX = pathlib.Path("/opt/data/index.bin").read_bytes()  # during init: keep the bytes

Mantén las herramientas en ejecución en lugar de iniciarlas por solicitud. Un subprocesso lanzado en el controlador lee su binario y bibliotecas desde la imagen en cada nueva sesión. Un ayudante de larga duración iniciado durante la inicialización, como un servidor de lenguaje o un proceso de trabajo con sus importaciones realizadas, regresa como parte de la memoria del proceso. Habla con él a través de una tubería o socket.

Copia archivos que no puedas mantener en memoria a un disco con respaldo de RAM. Las cadenas de herramientas como tsc se ejecutan como programas separados que leen sus propios archivos. Cópialos a /dev/shm o una montura ramfs durante la inicialización para que sus lecturas provengan de la memoria.

Envía bytecode compilado. uv pip install no se compila de forma predeterminada, así que las importaciones tardías también se compilan desde el origen. Establece UV_COMPILE_BYTECODE=1 o usa pip install --compile.

El ejemplo a continuación crea el agente, su modelo y sus clientes durante la inicialización, por lo que cada sesión hereda de ellos:

import json, pathlib
import boto3
import pandas as pd  # import during init, including rarely used libraries
from strands import Agent
from strands.models import BedrockModel
from bedrock_agentcore.runtime import BedrockAgentCoreApp

MODEL_ID = "us.anthropic.claude-haiku-5-5"

# Init: runs once, before the snapshot. Every new session inherits these objects.
PROMPTS = json.loads(pathlib.Path("prompts.json").read_text())
ddb = boto3.client("dynamodb")
agent = Agent(model=BedrockModel(model_id=MODEL_ID), system_prompt=PROMPTS["system"])

app = BedrockAgentCoreApp()

@app.entrypoint
def invoke(payload):
    return agent(payload["prompt"])

app.run()  # /ping answers only after this line

La compensación: el tiempo hasta el primer byte en una nueva sesión es el tiempo para iniciar el microVM y restaurar la instantánea, más el tiempo que tarda su controlador. Mover el trabajo a init acorta el controlador, pero cualquier cosa que mantenga en memoria hace que la instantánea sea más grande. También paga por la memoria mantenida en cada sesión. Mida el inicio de sesión de extremo a extremo antes y después del cambio, para que sepa que ha reducido la latencia y no solo la ha movido del controlador a la restauración.

Tarjeta de referencia

Trabajando con ganchos

Un gancho de compilación se construye en init y no lo reemplaza. Haga lo que pueda en init y use el gancho para lo que init no puede cubrir. Exponga un punto final HTTP en su contenedor, y AgentCore runtime le envía una solicitud POST dos veces mientras construye su runtime:

1. Antes de la instantánea. En el microVM de compilación, después de que su agente informa que está sano y antes de la congelación. Cualquier cosa que su agente cargue aquí y mantenga en memoria es parte de la instantánea, por lo que cada sesión comienza con ella.
2. Después de una restauración de prueba. En un microVM separado que restaura la instantánea para comprobarla. Nada de esta llamada se captura en la instantánea. Úsela para leer los archivos que sus sesiones necesitarán, lo que da forma a lo que las sesiones restauradas recuperan primero.

El encabezado X-Amzn-Bedrock-AgentCore-Runtime-Warmup-Type le indica a su agente qué llamada está manejando: memory para la primera, disk para la segunda. Las dos llamadas comparten 120 segundos, por lo que la llamada disk obtiene el tiempo que la llamada memory deja. Devuelva una respuesta 2xx solo después de que se complete el trabajo. Cualquier otra respuesta, una conexión fallida o agotamiento de tiempo provoca que la creación o actualización falle, y AgentCore runtime no vuelve a intentarlo. Las secuencias build-logs- en el grupo de registros de su runtime muestran qué llamada falló y por qué.

Los ganchos están disponibles en runtimes V2. Configúrelos con hooksConfiguration cuando cree o actualice el runtime:

client = boto3.client("bedrock-agentcore-control")
client.create_agent_runtime(
    agentRuntimeName="my_agent",
    agentRuntimeArtifact={"containerConfiguration": {"containerUri": IMAGE_URI}},
    roleArn=ROLE_ARN,
    networkConfiguration={"networkMode": "PUBLIC"},
    platformVersion="V2",
    hooksConfiguration={
        "build": {
            "warmup": {
                "action": {"httpPost": {"path": "/warmup", "port": 8080}}
            }
        }
    },
)

El puerto es opcional y se establece de forma predeterminada en el puerto de servicio de su agente. Si lo establece, use un puerto desde 8000 hasta 12000 que no esté reservado por la plataforma. La ruta no puede coincidir con una ruta que AgentCore runtime ya utilice en ese puerto, como POST /invocations o GET /ping. UpdateAgentRuntime reemplaza toda la configuración del hook, así que incluya hooksConfiguration en cada actualización donde desee mantener el hook.

En el agente, maneje ambos tipos de llamadas en el mismo endpoint:

import asyncio
from fastapi import FastAPI, Request, Response

app = FastAPI()

# Files that each session reads when it starts.
STARTUP_FILES = ["/app/models/tokenizer.json", "/app/config/agent.json"]

def load_shared_state():
    # Load what every session needs into memory, such as heavy imports,
    # model weights, and caches.
    ...

def read_startup_files():
    # Read the files that a session reads when it starts, so that new
    # sessions can use them faster.
    for path in STARTUP_FILES:
        with open(path, "rb") as f:
            while f.read(1024 * 1024):
                pass

@app.get("/ping")
def ping():
    return {"status": "Healthy"}

@app.post("/warmup")
async def warmup(request: Request):
    # Header lookup in Starlette and FastAPI is case-insensitive.
    warmup_type = request.headers.get(
        "X-Amzn-Bedrock-AgentCore-Runtime-Warmup-Type", ""
    ).lower()
    # Run the work in a worker thread so that /ping keeps answering.
    if warmup_type == "memory":
        await asyncio.to_thread(load_shared_state)
    elif warmup_type == "disk":
        await asyncio.to_thread(read_startup_files)
    # Respond only after the work is done.
    return Response(status_code=200)

@app.post("/invocations")
async def invoke(request: Request):
    payload = await request.json()
    # Per-request work runs here on every session.
    return {"response": payload.get("prompt", "")}

Para la referencia de configuración completa, consulte Configurar hooks de ciclo de vida para AgentCore runtime. Para un ejemplo de código completo, consulte el código de ejemplo.

Peligros de la instantánea: qué debe permanecer en el controlador

Todo lo creado durante la inicialización se congela en la instantánea hasta su próxima implementación, y cada sesión comienza con la misma copia. Para la mayoría de los objetos, ese es el punto. Para los valores a continuación, es un error, y para los valores aleatorios, un problema de seguridad.

Cargue datos dinámicos en el controlador, una vez por sesión. Los catálogos de herramientas de AgentCore Gateway (una capacidad de Amazon Bedrock AgentCore), las banderas de características y las listas de precios cambian después de implementar. Cárguelos en el controlador y almacénelos a nivel de módulo, para que cada sesión los recupere una vez. Las sesiones pueden durar hasta 8 horas, así que déle una fecha de caducidad a la caché:

_tools, _loaded_at = None, 0.0

def get_tools():
    global _tools, _loaded_at
    if _tools is None or time.time() - _loaded_at > 300:  # wall clock: refresh after 5 minutes
        _tools, _loaded_at = load_gateway_tools(), time.time()
    return _tools

Llame a get_tools() desde el controlador y pase el resultado al agente que creó durante la inicialización.

Cree valores por sesión en el controlador.

Conoce los límites. Una sesión termina cuando su tiempo de inactividad expira (idleRuntimeSessionTimeout: 15 minutos por defecto, desde 60 segundos hasta 8 horas), cuando alcanza su tiempo de vida máximo (maxLifetime: 8 horas por defecto y como máximo), o cuando la detienes.

Sub-segundo: Inicia la sesión antes de que el usuario la necesite

Supongamos que tu nueva sesión tarda alrededor de 2 segundos en iniciarse, incluyendo todo el desglose de temporización cubierto en las secciones anteriores. Una sesión que ya está en ejecución responde en aproximadamente 200 ms. Para una experiencia de chat o voz, la forma de lograr un tiempo de respuesta sub-segundo es asegurarse de que la sesión haya iniciado antes de que llegue la primera solicitud del usuario. Hay dos formas de hacerlo.

Pre-calentamiento en la interacción del usuario

La mayoría de las aplicaciones interactivas reciben una señaligen antes del primer mensaje: el usuario abre la aplicación, una ventana de chat o una página de soporte. Úsala. Genera un ID de sesión, envía una solicitud de pre-calentamiento al agente en segundo plano y mantén el ID de sesión con la conversación. Para cuando el usuario haya escrito su primer mensaje, la sesión ya está en ejecución.

# Backend, when the user opens the chat (don't block the UI on it)
session_id = f"chat-{uuid.uuid4().hex}"  # session IDs need at least 33 characters
agentcore.invoke_agent_runtime(agentRuntimeArn=ARN, runtimeSessionId=session_id,
                               payload=json.dumps({"action": "prime"}).encode())
save_conversation(user_id, session_id)  # every later turn reuses this session ID

# Agent handler: answer the warm-up before any model call
@app.entrypoint
def invoke(payload):
    if payload.get("action") == "prime":
        return {"primed": True}
    return agent(payload["prompt"])

Este patrón no requiere infraestructura adicional y oculta completamente el inicio de la sesión siempre que los usuarios tardan más de aproximadamente 2 segundos en enviar su primer mensaje. Cuesta una sesión por cada usuario que se compromete pero nunca envía una solicitud. Un tiempo de inactividad corto mantiene eso pequeño.

Conclusión

En V2, AgentCore runtime mueve la mayor parte del trabajo de inicio de una sesión al momento de la implementación. Tu contenedor se inicia una vez, y cada nueva sesión restaura el resultado: la memoria vuelve completa, y los archivos se recuperan en la primera lectura.

Para mantener el tiempo de inicio de la sesión cerca de 2 segundos, realiza tu trabajo estático durante la inicialización, mantén los datos que la primera solicitud necesita en memoria, y mantén los valores dinámicos y por sesión en el controlador. Para los archivos que tu proceso no puede mantener, agrega un hook de compilación. Para obtener un tiempo de respuesta inferior a un segundo, inicia la sesión antes de que el usuario la necesite: en la interacción del usuario cuando recibes una señaligen.

Para empezar, establece platformVersion en V2 cuando crees o actualices un runtime, luego revisa Optimiza tu agente para AgentCore runtime V2. Para preguntas sobre tu carga de trabajo, comunícate con tu equipo de cuenta de AWS.

Acerca del autor