翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # Step Functions を使用して Amazon Bedrock AgentCore ハーネスを呼び出す Step Functions を Amazon Bedrock AgentCore と統合して、ステートマシンからハーネスを呼び出すことができます。ハーネスは、モデル推論、ツールの使用、マルチターン会話を調整するマネージドランタイムです。Workflow Studio で **AgentCore InvokeHarness** を検索してこの状態を見つけ、ワークフローにドラッグします。 設定パネルから、**クイック作成ハーネス**を使用して新しいハーネスと実行ロールを作成するか、既存のハーネス 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)パターンはサポートされていません。 レスポンスは[、コンバース](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 リンクが表示され、ツールの使用を含むエージェントの推論が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 が、API アクション `startSyncExecution` などの camelCase である場合でも、`StateMachineArn` などの PascalCase でパラメータを指定します。 **レスポンスフィールド** + `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 errors](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 ポリシー 次のサンプルテンプレートは、 がステートマシン定義のリソースに基づいて IAM ポリシー AWS Step Functions を生成する方法を示しています。詳細については、「[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)」を参照してください。