本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 Step Functions 調用 Amazon Bedrock AgentCore 繫帶 您可以將 Step Functions 與 Amazon Bedrock AgentCore 整合，以從狀態機器叫用繫帶。繫帶是一種受管執行期，可協調模型推論、工具使用和多轉對話。在工作流程 Studio 中，搜尋 **AgentCore InvokeHarness** 以尋找此狀態，並將其拖曳到您的工作流程。 從組態面板中，您可以使用 **Quick Create Harness** 建立新的繫帶和執行角色，或選取現有的繫帶 ARN。當您使用現有的繫帶時，可以覆寫每次呼叫的組態 – 任務狀態定義中的值會覆寫繫帶預設值。如需可用的參數，請參閱《*Amazon Bedrock AgentCore API 參考*》中的 [InvokeHarness](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeHarness.html)。如需利用執行角色的詳細資訊，請參閱《*Amazon Bedrock AgentCore 開發人員指南*》中的[執行期許可](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html)。 **提示** 若要將可觀測性新增至代理程式資源，請啟用 CloudWatch 交易搜尋。如需詳細資訊，請參閱《*Amazon CloudWatch 使用者指南*》中的[將可觀測性新增至代理程式資源](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AgentCore-GettingStarted.html#add-observability-agentic-resources)。 若要了解如何在 Step Functions 中整合 AWS 服務，請參閱 [整合 服務](integrate-services.md)和 [在 Step Functions 中將參數傳遞至服務 API](connect-parameters.md)。 **Optimized AgentCore 繫帶整合的主要功能** 僅支援[請求回應](connect-to-resource.md#connect-default)整合模式。不支援 [執行任務 (.sync)](connect-to-resource.md#connect-sync)和 [使用任務字符等待回呼](connect-to-resource.md#connect-wait-token) 模式。 回應會轉換為 [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html#API_runtime_Converse_ResponseSyntax) 形狀的 JSON 結構。只會傳回最終助理訊息；會捨棄在多轉對話中稍早的轉彎。 字符用量指標 (`InputTokens`、`OutputTokens`、`TotalTokens`) 會彙總對話中的所有訊息。 只有文字內容包含在回應中。從 省略工具使用和推理區塊`Output.Message.Content`。 輸出大小受限於任務狀態輸出限制。如需目前值，請參閱 [與任務執行相關的配額](service-quotas.md#service-limits-task-executions)。 即使`TimeoutSeconds`值超過該限制，`InvokeHarness`任務狀態的執行時間上限為 15 分鐘 (900 秒）。任務狀態逾時後，繫帶會繼續執行，直到達到自己的設定逾時為止。為了避免意外成本，請確定您的繫帶逾時不超過 15 分鐘。 Step Functions 主控台執行詳細資訊檢視會在代理程式步驟旁顯示 CloudWatch 連結，提供代理程式推理的turn-by-turn檢視，包括工具使用。 ## 最佳化 Amazon Bedrock AgentCore APIs 支援下列 API： ### [InvokeHarness](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeHarness.html) 調用工具來執行 AI 代理程式，該代理程式可以使用工具、存取記憶體和執行多迴轉對話。 **支援的模式：**僅限請求回應。 如需完整的請求語法，請參閱《*Amazon Bedrock AgentCore API 參考*》中的 [InvokeHarness](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeHarness.html)。 **中的參數Step Functions以 PascalCase 表示** 即使原生服務 API 位於 camelCase 中，例如 API 動作 `startSyncExecution`，您可以在 PascalCase 中指定參數，例如：`StateMachineArn`。 **回應欄位** + `Output.Message` – 客服人員的最終助理訊息。包含 `Role`（一律為 `"assistant"`) 和 `Content`（文字區塊陣列）。只會傳回最後一個助理轉彎；會捨棄在多轉彎對話中稍早轉彎。 + `Output.Message.Content` – 內容區塊陣列。每個區塊都包含一個`Text`欄位，其中包含客服人員的回應文字。只包含文字內容；省略工具使用和推理區塊。 + `StopReason` – 為什麼代理程式停止。值：`end_turn`、`max_tokens`、`stop_sequence`、`tool_use`。 + `Usage` – 權杖消耗指標會跨所有回合彙總。包含 `InputTokens`、 `OutputTokens`和 `TotalTokens`。 + `Metrics.LatencyMs` – 調用延遲總計，以毫秒為單位，以所有回合彙總。 **回應語法** ``` { "Output": { "Message": { "Role": "{{string}}", "Content": [ { "Text": "{{string}}" } ] } }, "StopReason": "{{string}}", "Usage": { "InputTokens": {{long}}, "OutputTokens": {{long}}, "TotalTokens": {{long}} }, "Metrics": { "LatencyMs": {{long}} } } ``` **注意** 停止執行或任務狀態不會停止繫帶繼續執行。 ## Amazon Bedrock AgentCore 整合的任務狀態定義 下列範例示範如何定義叫用 Amazon Bedrock AgentCore 繫帶的任務狀態。 `RuntimeSessionId` 欄位可識別對話工作階段。跨調用使用相同的工作階段 ID 以繼續對話。 **注意** Step Functions 資源 URI 使用 `bedrockagentcore`（沒有連字號），而 Amazon Bedrock AgentCore 資源 ARNs 使用 `bedrock-agentcore`（使用連字號）。 **Example 具有模型覆寫和系統提示的基本調用** ``` { "Type": "Task", "Resource": "arn:aws:states:::bedrockagentcore:invokeHarness", "Arguments": { "HarnessArn": "arn:aws:bedrock-agentcore:{{us-east-1}}:{{123456789012}}:harness/{{my-agent-harness}}", "RuntimeSessionId": "{% $uuid() %}", "Messages": [ { "Content": [{ "Text": "{% $states.input.userMessage %}" }], "Role": "user" } ], "SystemPrompt": [{ "Text": "You are a helpful customer service agent." }], "Model": { "BedrockModelConfig": { "Temperature": 0.7, "ModelId": "global.anthropic.claude-sonnet-4-6" } }, "MaxIterations": 75, "TimeoutSeconds": 600 }, "End": true } ``` **Example 使用工具叫用 （瀏覽器）** ``` { "Type": "Task", "Resource": "arn:aws:states:::bedrockagentcore:invokeHarness", "Arguments": { "HarnessArn": "arn:aws:bedrock-agentcore:{{us-east-1}}:{{123456789012}}:harness/{{order-agent}}", "RuntimeSessionId": "{% $uuid() %}", "Messages": [ { "Content": [{ "Text": "What is the status of order #12345?" }], "Role": "user" } ], "Tools": [ { "Type": "agentcore_browser", "Name": "aws_browser_v1", "Config": { "AgentCoreBrowser": { "BrowserArn": "arn:aws:bedrock-agentcore:{{us-east-1}}:aws:browser/aws.browser.v1" } } } ], "MaxIterations": 10, "TimeoutSeconds": 300 }, "End": true } ``` **提示** 您可以在執行完整執行之前，使用 [TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html) API 個別測試此狀態。 ## 錯誤處理 `InvokeHarness` API 可能會因為各種錯誤而失敗，包括限流、驗證和存取遭拒的錯誤。如需完整清單，請參閱《*Amazon Bedrock AgentCore API 參考*》中的 [InvokeHarness 錯誤](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeHarness.html#API_InvokeHarness_Errors)。 下列範例顯示使用 `Retry`和 `Catch` 欄位處理錯誤的任務狀態： ``` { "Type": "Task", "Resource": "arn:aws:states:::bedrockagentcore:invokeHarness", "Arguments": { "HarnessArn": "arn:aws:bedrock-agentcore:{{us-east-1}}:{{123456789012}}:harness/{{my-harness}}", "Messages": [ { "Content": [{ "Text": "{% $states.input.userMessage %}" }], "Role": "user" } ] }, "Retry": [ { "ErrorEquals": ["BedrockAgentCore.ThrottlingException"], "IntervalSeconds": 2, "MaxAttempts": 3, "BackoffRate": 2.0 } ], "Catch": [ { "ErrorEquals": ["BedrockAgentCore.ResourceNotFoundException"], "Next": "HandleNotFound" }, { "ErrorEquals": ["States.ALL"], "Next": "HandleError" } ], "End": true } ``` ## 用於呼叫 Amazon Bedrock AgentCore 的 IAM 政策 下列範例範本顯示 如何根據狀態機器定義中的資源 AWS Step Functions 產生 IAM 政策。如需詳細資訊，請參閱[Step Functions 如何為整合服務產生 IAM 政策](service-integration-iam-templates.md)及[探索 Step Functions 中的服務整合模式](connect-to-resource.md)。 ### Amazon Bedrock AgentCore 整合的 IAM 政策範例 下列範例示範如何為 Step Functions 執行角色建立 IAM 政策，以與 Amazon Bedrock AgentCore 資源互動。 在下列政策範例中，將預留位置值取代為您自己的值。 + [叫用特定集合的 IAM 政策](#bedrockagentcore-policy-invoke-specific-harness) + [IAM 政策可叫用 帳戶中的所有繫帶](#bedrockagentcore-policy-invoke-all-harnesses) #### 叫用特定集合的 IAM 政策 下列範例政策允許 ARN 叫用特定的 Amazon Bedrock AgentCore 繫帶。 ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "InvokeSpecificHarness", "Effect": "Allow", "Action": [ "bedrock-agentcore:InvokeHarness", "bedrock-agentcore:InvokeAgentRuntime" ], "Resource": "arn:aws:bedrock-agentcore:{{region}}:{{accountId}}:harness/{{harnessName}}" } ] } ``` #### IAM 政策可叫用 帳戶中的所有繫帶 下列範例政策允許調用您帳戶中的任何 Amazon Bedrock AgentCore 繫帶。我們建議您盡可能縮小到特定的固定 ARN。 ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "InvokeAllHarnesses", "Effect": "Allow", "Action": [ "bedrock-agentcore:InvokeHarness", "bedrock-agentcore:InvokeAgentRuntime" ], "Resource": "arn:aws:bedrock-agentcore:{{region}}:{{accountId}}:harness/*" } ] } ``` **注意** 如果您的繫帶使用閘道、瀏覽器或程式碼解譯器等工具，這些許可會在*繫帶執行角色*上設定，而不是 Step Functions 執行角色。如需詳細資訊，請參閱《*Amazon Bedrock AgentCore 使用者指南*》中的[利用執行角色許可](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness-security.html)。