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
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.
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
/invocationsgestore. 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
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. /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.
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
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 |
|
|
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 |
|
|
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 ( |
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
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
secretso Go'scrypto/randoos.urandomReading./dev/urandomNon utilizzare valori casuali di una libreria crittografica come OpenSSL, perché possono ripetersi tra istanze.
Rete
- 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
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