Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

# Ottimizza il tuo agente per Amazon Bedrock AgentCore Runtime V2
<a name="runtime-v2-optimize"></a>

Amazon Bedrock AgentCore Runtime V2 avvia il tuo agente ripristinando uno snapshot. Questo cambia il modo in cui strutturi il codice dell'agente. Il lavoro svolto dall'agente all'avvio viene acquisito nell'istantanea e condiviso da ogni istanza ripristinata. Produci invece qualsiasi valore che debba differire tra le richieste o che possa scadere nel tuo gestore delle richieste. Questo argomento descrive come strutturare l'agente in base al lavoro di avvio e al lavoro per richiesta in modo che rimanga corretto dopo ogni ripristino. [Per una panoramica della versione V2 della piattaforma, consulta Versioni della piattaforma.](runtime-how-it-works.md#runtime-platform-versions)

Il tuo agente ha due contesti di esecuzione:

Startup  
Codice che viene eseguito una sola volta all'avvio del processo, prima che AgentCore Runtime acquisisca l'istantanea. AgentCore Runtime acquisisce questo codice nello snapshot e ogni istanza ne eredita i risultati.

Gestione delle richieste  
Il codice nel tuo `/invocations` gestore. Questo codice viene eseguito su ogni richiesta su ogni istanza.

Usa una regola per decidere a che cosa appartiene il codice. Calcola un valore all'avvio se rimane lo stesso per tutta la durata dell'istantanea. Calcolalo nel tuo gestore se varia in base alla richiesta o può scadere. AgentCore Runtime acquisisce un'istantanea per versione dell'agente e la utilizza fino a quando non si crea o si aggiorna l'agente, quindi la durata dello snapshot corrisponde alla durata di quella versione.

## Inizializza una volta all'avvio
<a name="_initialize_once_at_startup"></a>

Eseguite operazioni costose e riutilizzabili all'avvio del processo, prima dell'istantanea. Ad esempio, importa dipendenze, carica i pesi dei modelli o leggi la configurazione statica dal tuo pacchetto di distribuzione. Con l' AgentCore SDK, esegui questo lavoro nell'ambito del modulo, prima di chiamare. `app.run()` Il tuo agente non ascolta sulla porta 8080 fino all'`app.run()`esecuzione, quindi no `/ping` può avere successo e non è possibile scattare alcuna istantanea fino al termine del processo di avvio. L'istantanea acquisisce un agente completamente inizializzato in fase di costruzione e non è necessario eseguire il gate. `/ping` Inizializzazione completa entro 120 secondi dall'avvio. Se l'agente non si integra in tempo, il runtime non supera il controllo di integrità. Per ulteriori informazioni sugli `/invocations` endpoint, consulta [Understand the AgentCore Runtime service contract](runtime-service-contract.md). `/ping`

```
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
```

Se l'agente utilizza il proprio server HTTP anziché l' AgentCore SDK, segnala lo stato di integrità `/ping` solo dopo il completamento dell'inizializzazione, in modo che lo snapshot acquisisca un agente completamente inizializzato.

Leggi solo i dati all'avvio che sono gli stessi per ogni istanza e non scadono. Gestisci i valori sensibili al fattore tempo, come le credenziali di breve durata, nel tuo gestore.

**Nota**  
All'avvio non calcolate nulla che modificate senza ridistribuirlo. Ad esempio, un catalogo di strumenti recuperato da AgentCore Gateway sembra un valore di avvio ideale perché è lento e costoso da caricare, ma la memorizzazione nella cache all'avvio blocca l'inventario degli strumenti dell'agente al momento dell'istantanea.

## Mantieni aggiornato lo stato per richiesta
<a name="_keep_per_request_state_fresh"></a>

L'istantanea viene acquisita una sola volta e condivisa da ogni istanza ripristinata, quindi qualsiasi valore generato dall'agente all'avvio è identico in tutte le istanze e corretto al momento dell'istantanea. Gestisci i valori che l'istantanea non può contenere nel tuo gestore. `/invocations` La tabella seguente descrive i valori da calcolare nel gestore anziché all'avvio.


| Per farlo | Fatelo nel gestore | Motivo | 
| --- | --- | --- | 
| Genera valori, identificatori o token casuali | Chiama `os.urandom()` o `uuid.uuid4()` su ogni richiesta `secrets` |  `os.urandom()`restituisce una nuova entropia solo ogni volta che la chiami dopo un ripristino. Un valore letto all'avvio viene copiato nell'istantanea ed è identico in ogni istanza, indipendentemente dalla qualità della fonte di entropia al momento della lettura. Allo stesso modo, il `random` modulo viene preimpostato all'avvio, quindi le istanze ripristinate ripetono la stessa sequenza. | 
| Leggi l'ora corrente | Calcolalo per ogni richiesta | Un timestamp acquisito all'avvio viene corretto al momento dell'istantanea. | 
| Misura il tempo trascorso | Inserisci il timestamp di riferimento nel tuo gestore |  `time.monotonic()`non procede nel corso di un ripristino, quindi una durata misurata in base a un riferimento di avvio è errata e non sembra sbagliata. | 
| Utilizza credenziali o token | Aggiornateli quando scadono | Le credenziali caricate all'avvio possono scadere prima dell'avvio di un'istanza. | 
| Identifica l'istanza o il lavoratore | Genera un id per richiesta; non derivarlo dall'host | Ogni istanza ripristinata riporta lo stesso hostname (`localhost`) e PID (`1`), quindi utilizzarli entrambi come id comprime le metriche, i flussi di log e blocca i proprietari in tutto il parco istanze. | 

Crea client riutilizzabili all'avvio e calcola i valori per richiesta per ogni chiamata.

```
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.
```

## Usa librerie crittografiche sicure per le istantanee
<a name="_use_snapshot_safe_cryptographic_libraries"></a>

Quando AgentCore Runtime ripristina le istanze da un'istantanea, ogni istanza creata da quell'istantanea inizia con una copia identica della memoria acquisita al momento dell'istantanea. Ciò include lo stato interno dei generatori di numeri casuali all'interno delle librerie crittografiche e qualsiasi chiave, token o identificatore creato dall'agente durante l'inizializzazione. A meno che tale stato non venga aggiornato dopo il ripristino, le istanze possono produrre gli stessi valori «casuali».

 **Limitazione attuale** 

In AgentCore Runtime, le build di librerie crittografiche sicure per le istantanee attualmente non vengono reseminate dopo un ripristino. Questo vale sia per le distribuzioni dirette di codice che per le distribuzioni di container.

 **Soluzioni alternative** 
+ Genera segreti, chiavi, token e identificatori di sessione durante la gestione di una richiesta, non all'avvio dell'agente. In questo modo si evita di utilizzare qualsiasi valore creato prima che AgentCore Runtime acquisisca l'istantanea in ogni istanza ripristinata da quell'istantanea.
+ Anche durante la gestione di una richiesta, ottieni valori casuali direttamente dal sistema operativo, ad esempio Python `secrets` o Go's `crypto/rand` o `os.urandom` Reading. `/dev/urandom` Non utilizzare valori casuali di una libreria crittografica come OpenSSL, perché possono ripetersi tra istanze.

## Rete
<a name="_networking"></a>

Crea client all'avvio e aspettati una riconnessione trasparente  
Il socket che apri all'avvio non sopravvive al ripristino, ma la configurazione che la libreria client memorizza nella cache (analisi del modello di servizio, risoluzione degli endpoint, risoluzione delle credenziali e pool di connessioni) sì. Costruite ed esercitate i vostri client all'avvio e aspettatevi che la prima chiamata dopo un ripristino ristabilisca la connessione in modo trasparente.

Non utilizzate il nome host o il PID come identificatore di istanza univoco  
Ogni istanza ripristinata parte dalla stessa istantanea e riporta lo stesso nome host e ID di processo. Genera un identificatore univoco in ogni richiesta.

Evita il collegamento a una porta sorgente fissa  
Dopo un ripristino, la connessione mantenuta al momento dell'istantanea viene ristabilita e una porta di origine fissa può entrare in collisione con quella sostitutiva all'interno dell'istanza. Le istanze ripristinate sono microVM separate con i propri namespace di rete, quindi il conflitto è all'interno di un'istanza, non tra di esse.

## Cross-account metriche e quote
<a name="_cross_account_metrics_and_quotas"></a>

Per una chiamata tra più account, in cui un responsabile di un account richiama un agente runtime di proprietà di un altro account tramite una politica basata sulle risorse, le CloudWatch metriche e il limite di velocità di utilizzo della quota per la chiamata vengono attribuiti all'account del proprietario della risorsa. Il proprietario della risorsa è l'account che possiede il runtime dell'agente.

Puoi anche visualizzare le metriche che contano ai fini della tua quota nella console [Service](https://console.aws.amazon.com/servicequotas/home/services/bedrock-agentcore/quotas) Quotas.