本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
針對 Amazon Bedrock AgentCore 執行期 V2 最佳化您的代理程式
Amazon Bedrock AgentCore 執行期 V2 會透過還原快照來啟動您的代理程式。這會變更您建構代理程式程式碼的方式。您的代理程式在啟動時執行的工作會在快照中擷取,並由每個還原的執行個體共用。改為在請求處理常式中產生請求之間必須不同或可能過期的任何值。本主題說明如何根據啟動工作和每個請求工作來建構代理程式,以便在每次還原後保持正確。如需平台版本 V2 的概觀,請參閱平台版本。
您的代理程式有兩個執行內容:
- 啟動
-
在 AgentCore 執行期擷取快照之前,在程序開始時執行一次的程式碼。AgentCore 執行期會在快照中擷取此程式碼,且每個執行個體都會繼承其結果。
- 請求處理
-
/invocations處理常式中的程式碼。此程式碼會在每個執行個體上的每個請求上執行。
使用一個規則來決定程式碼的所屬位置。如果在快照的生命週期內保持不變,請在啟動時計算值。如果每個請求各有不同或可能過期,請在處理常式中運算。AgentCore 執行期會為每個代理程式版本拍攝一個快照,並用到您建立或更新代理程式為止,因此快照的生命週期是該版本的生命週期。
啟動時初始化一次
在快照之前,在程序開始時執行昂貴、可重複使用的工作。例如,從部署套件匯入相依性、載入模型權重或讀取靜態組態。使用 AgentCore 開發套件,在呼叫 之前,在模組範圍內執行此工作app.run()。在app.run()執行之前,您的代理程式不會監聽連接埠 8080,因此/ping在啟動工作完成之前,不會成功,也不會拍攝任何快照。快照會依建構擷取完全初始化的代理程式,而您不需要將 設為閘道/ping。啟動後 120 秒內完成初始化。如果您的代理程式未及時正常運作,則執行時間會失敗其運作狀態檢查。如需 /ping和 /invocations端點的詳細資訊,請參閱了解 AgentCore 執行期服務合約。
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
如果您的代理程式執行自己的 HTTP 伺服器,而不是 AgentCore SDK,/ping則只有在初始化完成後,才從 報告運作狀態良好,以便快照擷取完全初始化的代理程式。
每個執行個體在啟動時只讀取相同且不會過期的資料。在您的處理常式中處理時間敏感值,例如短期憑證。
請勿在啟動時運算您在未重新部署的情況下變更的任何內容。例如,從 AgentCore Gateway 擷取的工具目錄看起來像理想的啟動值,因為它載入速度緩慢且昂貴,但在啟動時快取它會在快照時凍結代理程式的工具庫存。
保持每個請求狀態為新鮮
快照會擷取一次,並由每個還原的執行個體共用,因此您的代理程式在啟動時產生的任何值在執行個體之間都相同,並在快照時修正。處理快照無法在/invocations處理常式中攜帶的值。下表說明要在處理常式中運算的值,而不是在啟動時運算的值。
| 若要執行此作業 | 在處理常式中執行 | Reason |
|---|---|---|
|
產生隨機值、識別符或字符 |
在每次請求 |
|
|
讀取目前時間 |
為每個請求運算 |
啟動時擷取的時間戳記會在快照時修正。 |
|
測量經過的時間 |
在處理常式中取得參考時間戳記 |
|
|
使用登入資料或字符 |
過期時重新整理它們 |
啟動時載入的登入資料可能會在執行個體啟動之前過期。 |
|
識別執行個體或工作者 |
為每個請求產生 ID;請勿從主機衍生 ID |
每個還原的執行個體都會報告相同的主機名稱 ( |
在啟動時建置可重複使用的用戶端,並在每次呼叫時計算每個請求的值。
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.
使用快照安全的密碼編譯程式庫
當 AgentCore 執行期從快照還原執行個體時,從該快照建立的每個執行個體都會從快照時擷取的相同記憶體副本開始。這包括密碼編譯程式庫中亂數產生器的內部狀態,以及您的代理程式在初始化期間建立的任何金鑰、字符或識別符。除非在還原後重新整理該狀態,否則執行個體可以產生相同的「隨機」值。
目前限制
在 AgentCore 執行期中,還原後,目前不會重新擷取加密程式庫的快照安全組建。這同時適用於直接程式碼部署和容器部署。
解決方法
-
在處理請求時產生秘密、金鑰、字符和工作階段識別符,而不是您的代理程式啟動時。這可避免使用在 AgentCore 執行期取得從該快照還原的每個執行個體中的快照之前建立的任何值。
-
即使處理請求,也請直接從作業系統取得隨機值,例如 Python 的
secrets或os.urandom、Go 的crypto/rand或讀取/dev/urandom。不要使用 OpenSSL 等密碼編譯程式庫的隨機值,因為它們可以在執行個體之間重複。
聯網
- 在啟動時建置用戶端並預期透明重新連線
-
您在啟動時開啟的通訊端無法承受還原,但用戶端程式庫在其周圍快取的設定:服務模型剖析、端點解析、憑證解析和連線集區。在啟動時建構和練習您的用戶端,並預期還原後的第一個呼叫會以透明方式重新建立連線。
- 請勿使用主機名稱或 PID 做為唯一的執行個體識別符
-
每個還原的執行個體都從相同的快照開始,並報告相同的主機名稱和程序 ID。在每個請求中產生唯一識別符。
- 避免繫結至固定來源連接埠
-
還原之後,在快照時間保留的連線會重新建立,且固定來源連接埠可能會與該執行個體中的取代發生衝突。還原的執行個體是具有自己的網路命名空間的個別microVMs,因此衝突是在執行個體內,而不是在執行個體之間。
跨帳戶指標和配額
對於跨帳戶調用,一個帳戶中的委託人透過以資源為基礎的政策調用另一個帳戶擁有的代理程式執行期,CloudWatch 指標和調用的速率限制配額用量會歸因於資源擁有者的帳戶。資源擁有者是擁有代理程式執行期的帳戶。
您也可以在 Service Quotas