本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 使用 Step Functions 调用亚马逊 Bedrock AgentCore 安全带 你可以将 Step Functions 与 Amazon Bedrock AgentCore 集成，从状态机调用安全带。Harness 是一种托管运行时，用于协调模型推理、工具使用和多回合对话。在 Workflow Studio 中，搜索**AgentCore InvokeHarness**以找到此状态并将其拖到您的工作流程中。 在配置面板中，您可以使用 **Quick Create Harness 创建新的安全**带和执行角色，也可以选择现有的线束 ARN。使用现有线束时，可以按每次调用覆盖配置——任务状态定义中的值会覆盖线束默认值。有关可用参数，请参阅[InvokeHarness](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeHarness.html)《*亚马逊 Bedrock AgentCore API 参考*》。有关线束执行角色的更多信息，请参阅 *Amazon Bedrock AgentCore 开发者指南*中的[运行时权限](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html)。 **提示** 要为您的代理资源增加可观察性，请启用 CloudWatch 交易搜索。有关更多信息，请参阅 A *mazon 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)。 **经过优化的 AgentCore 安全带集成的主要特点** 仅支持[请求响应](connect-to-resource.md#connect-default)集成模式。不支持[运行作业 (.sync)](connect-to-resource.md#connect-sync)和[等待具有任务令牌的回调](connect-to-resource.md#connect-wait-token)模式。 响应被转换为[匡威](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)。 `InvokeHarness`任务状态的最大执行时间为 15 分钟（900 秒），即使该`TimeoutSeconds`值超过该限制也是如此。任务状态超时后，线束会继续执行，直到达到自己配置的超时时间。为避免意外成本，请确保安全带超时时间不超过 15 分钟。 Step Functions 控制台执行详细信息视图在代理步骤旁边显示一个 CloudWatch 链接，提供代理推理（包括工具使用情况）的逐向视图。 ## 优化的亚马逊 Bedrock AgentCore 安全带 API 支持以下 API： ### [InvokeHarness](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeHarness.html) 调用安全带来运行 AI 代理，该代理可以使用工具、访问内存和执行多回合对话。 **支持的模式：**仅限请求响应。 有关完整的请求语法，请参阅[InvokeHarness](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeHarness.html)《*Amazon Bedrock AgentCore API 参考*》。 **中的参数 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 Bedro AgentCore ck 工具的任务状态。 该`RuntimeSessionId`字段用于标识对话会话。在所有调用中使用相同的会话 ID 继续对话。 **注意** Step Functions 资源 URI 使用`bedrockagentcore`（没有连字符），而 Amazon Bedrock AgentCore 资源 ARN 使用`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 的 IAM 政策 AgentCore 以下示例模板展示了如何根据状态机定义中的资源 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)。