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.
# Optimice su agente para Amazon Bedrock AgentCore Runtime V2
Amazon Bedrock AgentCore Runtime V2 inicia el agente restaurando una instantánea. Esto cambia la forma de estructurar el código de agente. El trabajo que realiza el agente al inicio se captura en la instantánea y se comparte en todas las instancias restauradas. En su lugar, introduzca cualquier valor que deba diferir de una solicitud a otra o que pueda caducar en su gestor de solicitudes. En este tema se describe cómo estructurar el agente en función del trabajo inicial y el trabajo por solicitud para que siga siendo correcto después de cada restauración. Para obtener una descripción general de la versión V2 de la plataforma, consulte [Versiones de plataforma](runtime-how-it-works.md#runtime-platform-versions).
Su agente tiene dos contextos de ejecución:
Startup
Código que se ejecuta una vez cuando se inicia el proceso, antes de que AgentCore Runtime tome la instantánea. AgentCore Runtime captura este código en la instantánea y cada instancia hereda sus resultados.
Gestión de solicitudes
El código de tu `/invocations` controlador. Este código se ejecuta en todas las solicitudes de todas las instancias.
Usa una regla para decidir a dónde pertenece el código. Calcule un valor al inicio si permanece igual durante la duración de la instantánea. Calcule en su controlador si varía según la solicitud o si puede caducar. AgentCore Runtime toma una instantánea por versión del agente y la usa hasta que se crea o actualiza el agente, por lo que la duración de la instantánea es la vida útil de esa versión.
## Inicialízalo una vez al inicio
Realice trabajos costosos y reutilizables a medida que se inicie el proceso, antes de la instantánea. Por ejemplo, importe las dependencias, cargue los pesos de los modelos o lea la configuración estática de su paquete de implementación. Con el AgentCore SDK, realice este trabajo en el ámbito del módulo, antes de llamar`app.run()`. Su agente no escucha en el puerto 8080 hasta que `app.run()` se ejecuta, por lo que no `/ping` puede funcionar correctamente y no se puede realizar ninguna instantánea hasta que finalice el trabajo de inicio. La instantánea captura un agente completamente inicializado desde el principio y no es necesario conectarlo. `/ping` Complete la inicialización dentro de los 120 segundos posteriores al inicio. Si el agente no recupera el estado correcto a tiempo, el motor de ejecución no pasará la comprobación de estado. Para obtener más información sobre los `/invocations` puntos finales `/ping` y, consulte [Comprender el contrato de servicio AgentCore de Runtime](runtime-service-contract.md).
```
import json, pathlib
from bedrock_agentcore.runtime import BedrockAgentCoreApp
# Runs once at import, before app.run() starts the server and before the
# snapshot. Every restored instance inherits these objects.
MODEL = load_model_weights()
SETTINGS = json.loads((pathlib.Path(__file__).parent / "agent.json").read_text())
app = BedrockAgentCoreApp()
@app.entrypoint
def invoke(payload):
# Per-request work runs here on every instance.
...
app.run() # starts listening on 8080; the snapshot is taken after this
```
Si su agente ejecuta su propio servidor HTTP en lugar del AgentCore SDK, notifique el estado correcto `/ping` solo después de que se complete la inicialización, de modo que la instantánea capture un agente completamente inicializado.
Al iniciar, lee solo los datos que sean iguales para todas las instancias y que no caduquen. Gestione los valores urgentes, como las credenciales de corta duración, en su controlador.
**nota**
Al iniciar, no computes nada que cambies sin volver a distribuirlo. Por ejemplo, un catálogo de herramientas obtenido de AgentCore Gateway parece un valor inicial ideal porque es lento y caro de cargar, pero si lo guarda en caché al inicio, se bloquea el inventario de herramientas del agente en el momento de realizar la instantánea.
## Mantenga actualizado el estado de cada solicitud
La instantánea se captura una vez y se comparte con todas las instancias restauradas, por lo que cualquier valor que el agente genere al iniciar es idéntico en todas las instancias y se fija en el momento de la instantánea. Controle los valores que la instantánea no pueda contener en su `/invocations` controlador. En la siguiente tabla se describen los valores que se deben calcular en el controlador y no al inicio.
| Para ello | Hazlo en el controlador | Motivo |
| --- | --- | --- |
| Genera valores, identificadores o fichas aleatorios | Llame `os.urandom()` o `uuid.uuid4()` en cada solicitud `secrets` | `os.urandom()`devuelve una entropía nueva solo cada vez que la llamas después de una restauración. Un valor leído al inicio se copia en la instantánea y es idéntico en todos los casos, por muy buena que fuera la fuente de entropía cuando se leyó. El `random` módulo también se inserta al inicio, por lo que las instancias restauradas repiten la misma secuencia. |
| Lee la hora actual | Calcúlala para cada solicitud | La marca de tiempo capturada al inicio se fija en el momento de la instantánea. |
| Mida el tiempo transcurrido | Tome la marca de tiempo de referencia en su controlador | `time.monotonic()`no avanza a lo largo de una restauración, por lo que una duración medida a partir de una referencia de inicio es incorrecta sin tener un aspecto incorrecto. |
| Usa credenciales o fichas | Actualícelos cuando caduquen | Las credenciales cargadas al inicio pueden caducar antes de que se inicie la instancia. |
| Identifique la instancia o el trabajador | Genera un identificador por solicitud; no lo obtengas del anfitrión | Todas las instancias restauradas muestran el mismo nombre de host (`localhost`) y el mismo PID (`1`), por lo que si se utiliza uno de ellos como identificador, se reducen las métricas, se registran los flujos y se bloquea a los propietarios de toda la flota. |
Crea clientes reutilizables al inicio y calcula los valores por solicitud en cada llamada.
```
import os, time
# Build reusable clients at startup, before the snapshot. Exercise them here too
# (for example, with a warm-up call) so the setup the client caches — endpoint and
# credential resolution, connection pool — is captured in the snapshot.
client = build_client()
warm_up(client)
@app.entrypoint
def invoke(payload):
creds = get_credentials() # refreshed when expired, not read at startup
request_id = os.urandom(16).hex() # unique per request
now = time.time() # current time, not snapshot time
# Handle the request.
```
## Utilice bibliotecas criptográficas seguras para instantáneas
Cuando AgentCore Runtime restaura las instancias de una instantánea, cada instancia creada a partir de esa instantánea comienza con una copia idéntica de la memoria capturada en el momento de la instantánea. Esto incluye el estado interno de los generadores de números aleatorios dentro de las bibliotecas criptográficas y cualquier clave, token o identificador que el agente haya creado durante la inicialización. A menos que ese estado se actualice después de la restauración, las instancias pueden producir los mismos valores «aleatorios».
**Limitación actual**
En AgentCore Runtime, las compilaciones de bibliotecas criptográficas seguras para instantáneas no se reinicializan actualmente después de una restauración. Esto se aplica tanto a las implementaciones de código directo como a las de contenedores.
**Soluciones alternativas**
+ Genera secretos, claves, símbolos e identificadores de sesión mientras gestionas una solicitud, no cuando tu agente la inicia. Esto evita el uso de valores creados antes de que AgentCore Runtime tome la instantánea en cada instancia restaurada a partir de esa instantánea.
+ Incluso mientras gestionas una solicitud, obtén valores aleatorios directamente del sistema operativo, por ejemplo, los de `secrets` Python`os.urandom`, Go o Reading`/dev/urandom`. `crypto/rand` No utilices valores aleatorios de una biblioteca criptográfica como OpenSSL, ya que pueden repetirse en todas las instancias.
## Red
Cree clientes al inicio y espere una reconexión transparente
El socket que se abre al inicio no sobrevive a una restauración, pero sí lo hace la configuración que la biblioteca de clientes almacena en caché (el análisis del modelo de servicio, la resolución de terminales, la resolución de credenciales y el conjunto de conexiones). Construya y ejercite sus clientes al inicio y espere a que la primera llamada tras una restauración restablezca la conexión de forma transparente.
No utilices el nombre de host ni el PID como identificador de instancia único
Todas las instancias restauradas parten de la misma instantánea y muestran el mismo nombre de host e ID de proceso. Genera un identificador único en cada solicitud.
Evite vincularse a un puerto de origen fijo
Tras una restauración, se restablece la conexión mantenida en el momento de la instantánea y un puerto de origen fijo puede colisionar con el puerto de reemplazo de la instancia. Las instancias restauradas son micromáquinas virtuales independientes con sus propios espacios de nombres de red, por lo que el conflicto se produce dentro de una instancia, no entre ellas.
## Cross-account métricas y cuotas
En el caso de una invocación multicuenta, en la que el principal de una cuenta invoca el tiempo de ejecución de un agente propiedad de otra cuenta mediante una política basada en los recursos, CloudWatch las métricas y la cuota límite de uso para la invocación se atribuyen a la cuenta del propietario del recurso. El propietario del recurso es la cuenta propietaria del tiempo de ejecución del agente.
También puede ver las métricas que se tienen en cuenta para su cuota en la consola [Service Quotas](https://console.aws.amazon.com/servicequotas/home/services/bedrock-agentcore/quotas).