本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # lifecycle hook 生命週期掛鉤會在繫帶代理程式迴圈中定義的時間點，將事件傳送至 AWS Lambda 函數、Amazon SNS 主題或 Amazon EventBridge 事件匯流排。使用勾點來驗證調用或工具呼叫、在另一個系統中記錄活動，或啟動非同步工作流程。 您可以使用 `CreateHarness`或 設定繫帶上的勾點`UpdateHarness`。勾點組態無法做為`InvokeHarness`覆寫使用。繫帶最多支援 20 個掛鉤，而且每個掛鉤名稱在繫帶中必須是唯一的。 ## 選擇生命週期事件 事件類型會決定勾點執行的時間、傳送至目標的內容，以及 Lambda `deny`決策的效果。 | 事件 | Context | Lambda `deny`決策的影響 | | --- | --- | --- | | `before_invocation` | 在繫帶還原工作階段狀態之前，目前`InvokeHarness`請求中`messages`提供的排序 。 | 在代理程式啟動之前停止調用。回應串流會發出 `stopReason` 設定為 `messageStop`的事件`hook_stopped`。 | | `before_tool_call` | 工具名稱、工具類型、工具使用 ID 和模型產生的工具輸入。 | 略過工具呼叫。代理程式迴圈會繼續。 | | `after_tool_call` | 當由工具執行的工具引發例外狀況時，工具名稱、工具類型、工具使用 ID、工具結果和錯誤字串。 | 保留完成的工具結果，然後停止調用。回應串流會發出 `stopReason` 設定為 `messageStop`的事件`hook_stopped`。 | | `after_invocation` | 調用停止原因和輸入和輸出字符計數。 | 報告回應串流中的決策。調用已完成，因此勾點無法撤回串流輸出。 | ### 搭配內嵌函數使用工具呼叫勾點 工具呼叫掛鉤也會針對`inline_function`工具執行。繫帶會在模型產生工具請求`before_tool_call`之後，以及在繫帶交出待定呼叫以進行用戶端執行之前叫用。使用完整的回應串流，然後僅在最後一個`messageStop`事件`stopReason`設定為 時處理內嵌呼叫`tool_use`。在勾點決策之前，模型產生的請求可能會出現在較早的串流事件中； `before_tool_call`控制執行，而不是串流中的可見性。 在稍後使用相同 的`InvokeHarness`請求`toolResult`中傳回相符項目`runtimeSessionId`。繫帶會繼續待定呼叫、`after_tool_call`使用用戶端提供的結果叫用，並在掛鉤允許結果時繼續代理程式迴圈。如需完整的回呼流程，請參閱[內嵌函數呼叫](harness-tools.md#harness-inline-functions)。 單一模型回應中的工具會保留循序執行順序。對於工具 A、內嵌函數 B 和工具 C，該工具會在遞交 B 之前執行 A，並在執行 C 之前等待 B 的結果。後續請求是新的調用，因此調用勾點會再次執行；`before_tool_call`對於待定內嵌函數，不會重複執行，並使用提交的結果`after_tool_call`執行一次。 您可以提交待定結果，並在內嵌結果之後立即提交任何結果，以提出一個後續請求。繫帶會依序處理其 `before_tool_call`和 掛`after_tool_call`鉤。如果您的用戶端需要在每次外部動作之前做出`allow`決策，請在每次遞交時傳回一個內嵌結果。稍後的請求可能會在掛鉤執行之前出現在串流中。 如果 `before_tool_call` 拒絕 B，則繫帶會略過 B 並繼續使用 C，而不將 B 交給用戶端。如果用戶端傳回其結果後`after_tool_call`拒絕 B，則繫帶會保留 B 的結果，並在 C 之前停止。 **驗證用戶端提供的結果** 內嵌函數`after_tool_call`的事件會確認繫帶已處理用戶端提供的結果。它不會證明用戶端已執行該結果所代表的外部動作。使用事件做為授權或稽核訊號之前，驗證發起人並驗證結果。 ## 選擇目標 勾點支援下列目標類型。 | Target | Delivery | 決策行為 | | --- | --- | --- | | AWS Lambda | 繫帶會與 同步叫用函數，`RequestResponse`並等待最多 `timeoutSeconds`。 | 函數必須傳回 `allow`或 `deny`。Lambda 是唯一可以變更客服人員迴圈行為的目標類型。 | | Amazon SNS | 繫帶會將勾點承載發佈為 SNS `Message`。發佈不會封鎖代理程式迴圈。 | 僅限通知。SNS 不會傳回勾點決策。 | | Amazon EventBridge | 繫帶會在 中傳送掛鉤承載`detail`，來源`bedrock-agentcore.harness`和詳細資訊類型為 `Harness Lifecycle Hook`。傳送 不會封鎖代理程式迴圈。 | 僅限通知。EventBridge 不會傳回勾點決策。 | 集合會排程 SNS 和 EventBridge 交付，無需等待回應。交付錯誤不會停止調用。對於 SNS FIFO 主題，繫帶會從繫帶 ARN 和工作階段 ID 衍生訊息群組 ID。這會保留該工作階段中的發佈順序。標準 SNS 主題和 EventBridge 不保證生命週期事件順序。 授予繫帶執行角色呼叫每個目標的許可。如需範例政策，請參閱[生命週期掛鉤目標](harness-security.md#harness-lifecycle-hook-permissions)。 ## 設定掛鉤 下列範例會在每次叫用前設定 Lambda 決策勾點、每次工具呼叫後設定 SNS 通知，以及每次叫用後設定 EventBridge 通知。在 中定義掛鉤`hooks.json`： ``` [ { "beforeInvocation": { "name": "validate_request", "target": { "lambda": { "arn": "arn:aws:lambda:us-west-2:123456789012:function:validate-harness-request", "timeoutSeconds": 5, "failureMode": "deny" } } } }, { "afterToolCall": { "name": "record_tool_result", "target": { "sns": { "arn": "arn:aws:sns:us-west-2:123456789012:harness-tool-events" } } } }, { "afterInvocation": { "name": "record_invocation", "target": { "eventBridge": { "arn": "arn:aws:events:us-west-2:123456789012:event-bus/harness-events" } } } } ] ``` **Example** 套用掛鉤： ``` aws bedrock-agentcore-control update-harness \ --harness-id "MyHarness-UuFdkQoXSL" \ --hooks file://hooks.json ``` 載入並套用相同的組態： ``` import json import boto3 client = boto3.client("bedrock-agentcore-control") with open("hooks.json", encoding="utf-8") as hooks_file: hooks = json.load(hooks_file) client.update_harness( harnessId="MyHarness-UuFdkQoXSL", hooks=hooks, ) ``` 當您傳遞`hooks`至 時`UpdateHarness`，提供的清單會取代現有的勾點組態。傳遞空清單以移除所有掛鉤。省略 `hooks`以保留現有的組態。 ## 傳回 Lambda 決策 Lambda 目標會直接接收勾點承載。它必須傳回`decision`值為 `allow`或 的 JSON 物件`deny`。它也可以傳回 `reason`。繫帶在`hookEvent`回應串流事件中包含此原因，並限制為 1，024 個字元。 當目標無法評估完整的勾點內容時，下列處理常式會拒絕`before_invocation`事件。將此邏輯取代為應用程式的規則。 ``` def lambda_handler(event, _context): hook_context = event["context"] if event["event"] == "before_invocation" and hook_context.get("truncated"): return { "decision": "deny", "reason": "The request context exceeded the evaluation limit.", } return {"decision": "allow"} ``` 對於 Lambda 目標， `timeoutSeconds` 預設為 60 秒，並接受 1 到 900 秒之間的值。 `failureMode`決定函數逾時、傳回錯誤或傳回無效回應時的決策： + `deny` – 套用拒絕決策。這是預設值。 + `allow` – 套用允許決策。 **設定長時間執行的勾點連線** 同步掛鉤可以保持`InvokeHarness`串流閒置，直到掛鉤傳回 或達到 `timeoutSeconds`。設定 SDK 讀取逾時，以超過預期的最長閒置期間。對於設定為 900 秒的勾點，下列範例使用 1，000 秒的讀取逾時來提供額外的邊界： ``` import boto3 from botocore.config import Config client = boto3.client( "bedrock-agentcore", config=Config( read_timeout=1000, tcp_keepalive=True, ), ) ``` 如果連線通過 NAT 閘道、介面 VPC 端點或 Network Load Balancer，也請將作業系統 TCP 保持連線閒置時間設定為少於 350 秒。在 Linux 上，這是 `TCP_KEEPIDLE`，由 設定`net.ipv4.tcp_keepalive_time`。`tcp_keepalive=True` 單獨設定可啟用 TCP 保持連線，但不會縮短作業系統的預設閒置時間。如需詳細資訊，請參閱[長時間執行或閒置連線上的連線逾時或重設](https://docs.aws.amazon.com/bedrock/latest/userguide/troubleshooting-api-error-codes.html)。 內容截斷不會啟用 `failureMode`。Lambda 函數會收到截斷的內容，且必須傳回決策。 當多個 Lambda 掛鉤使用相同的事件類型時，該繫帶會同時叫用它們。任何`deny`決策都會套用事件的拒絕行為。如果多個勾點拒絕事件，則設定清單中的第一個拒絕勾點會提供原因。 ## 處理勾點承載 每個目標都會收到下列常見欄位： ``` { "hookEventId": "1234abcd-12ab-34cd-56ef-1234567890ab", "name": "validate_request", "event": "before_invocation", "harnessArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:harness/MyHarness-UuFdkQoXSL", "sessionId": "12345678-1234-5678-9abc-123456789012", "context": { "messageCount": 1, "messages": [ { "role": "user", "content": [{"text": "Summarize this report."}] } ] } } ``` `context` 欄位取決於事件類型。 - ** `before_invocation` ** - **欄位:** `messageCount` / **說明:** 勾點內容截斷之前目前`InvokeHarness`請求中的訊息數量。 - **欄位:** `messages` / **說明:** 來自目前`InvokeHarness`請求的排序訊息。 - **欄位:** `truncated` / **說明:** 當內容超過 64 KiB `true`時，會顯示 並設為 。 - ** `before_tool_call` ** - **欄位:** `toolName` / **說明:** 面向模型的工具名稱。 - **欄位:** `toolType` / **說明:** 利用工具類型，例如 `builtin`、`agentcore_gateway`、 `remote_mcp`或 `inline_function`。 - **欄位:** `toolInput` / **說明:** 工具的模型產生輸入。 - **欄位:** `toolUseId` / **說明:** 將工具請求與其結果建立關聯的 ID。 - ** `after_tool_call` ** - **欄位:** `toolName` / **說明:** 面向模型的工具名稱。 - **欄位:** `toolType` / **說明:** 繫結工具類型。 - **欄位:** `toolResult` / **說明:** 繫帶觀察到的結果。對於內嵌函數，這是用戶端提供的結果。 - **欄位:** `toolUseId` / **說明:** 將工具請求與其結果建立關聯的 ID。 - **欄位:** `error` / **說明:** 工具執行時出現例外狀況的錯誤文字。未發生此類例外狀況時省略。 - ** `after_invocation` ** - **欄位:** `stopReason` / **說明:** 最終調用停止原因。 - **欄位:** `usage` / **說明:** 包含 `inputTokens`和 的物件`outputTokens`。 `before_invocation` 內容不包含掛鉤執行後從工作階段狀態還原的繫帶訊息。`after_tool_call` Lambda 拒絕決策不會移除已完成的工具結果。 ### 處理內容截斷 繫帶會將每個勾點`context`物件限制為 64 KiB。 對於 `before_invocation`，繫帶會保留符合限制的最新連續完整訊息序列。承載會保留`messageCount`並保留`messages`為清單。它也會`"truncated": true`新增至內容。如果最新訊息單獨超過限制，則 `messages` 為空白清單。 對於其他事件類型，繫帶會取代最大的內容欄位，直到內容符合為止。每個取代的欄位使用以下形式： ``` { "truncated": true, "preview": "" } ``` 使用 欄位之前，請檢查截斷標記。收到截斷標記`deny`時，可能會傳回需要完整內容的 Lambda 目標。SNS 或 EventBridge 取用者可以記錄事件，並從自己的記錄系統取得其他資料。 ## 從回應串流讀取勾點事件 `InvokeHarness` `hookEvent`會針對每個觸發的已設定掛鉤發出 。Lambda 事件包含套用的決策和選用原因： ``` { "hookEvent": { "hookEventId": "1234abcd-12ab-34cd-56ef-1234567890ab", "name": "validate_request", "type": "before_invocation", "decision": "allow", "reason": "Request accepted." } } ``` 對於 SNS 和 EventBridge 目標， `decision`和 `reason`不存在。他們的 `hookEvent` 確認繫帶已排程分派。它不會確認目標收到事件。 繼續讀取，直到事件串流關閉。當串流包含終端機 時`messageStop`，任何`type`設定為 `hookEvent`的 `after_invocation`都會跟隨它。有些錯誤路徑在沒有 `after_invocation`的情況下發出`messageStop`。 ## 相關主題 + [工具](harness-tools.md) – 設定工具和內嵌函數 + 可[觀測性和成本控制 – ](harness-operations.md)監控繫帶叫用 + [安全性和存取控制](harness-security.md) – 設定繫帶執行角色和控制工具存取 + [API 文件](harness-get-started.md#api-documentation)