Step Functions を使用して Amazon Bedrock AgentCore ハーネスを呼び出す

Step Functions を Amazon Bedrock AgentCore と統合して、ステートマシンからハーネスを呼び出すことができます。ハーネスは、モデル推論、ツールの使用、マルチターン会話を調整するマネージドランタイムです。Workflow Studio で AgentCore InvokeHarness を検索してこの状態を見つけ、ワークフローにドラッグします。

設定パネルから、クイック作成ハーネスを使用して新しいハーネスと実行ロールを作成するか、既存のハーネス ARN を選択できます。既存のハーネスを使用する場合、呼び出しごとに設定を上書きできます。タスク状態定義の値はハーネスのデフォルトを上書きします。使用可能なパラメータについては、「Amazon Bedrock AgentCore API InvokeHarness」を参照してください。ハーネス実行ロールの詳細については、「Amazon Bedrock AgentCore デベロッパーガイド」の「ランタイムアクセス許可」を参照してください。

Step Functions での AWS サービスとの統合については、 サービスとの統合「」および「」を参照してくださいStep Functions でサービス API にパラメータを渡す。

最適化された Amazon Bedrock AgentCore ハーネス APIs

次の API がサポートされています。

InvokeHarness

ツールの使用、メモリへのアクセス、マルチターン会話の実行が可能な AI エージェントを実行するハーネスを呼び出します。

サポートされているパターン: リクエストレスポンスのみ。

完全なリクエスト構文については、「Amazon Bedrock AgentCore API InvokeHarness」を参照してください。

レスポンスフィールド

レスポンスの構文

{
  "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 を使用します。

{
  "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
}

{
  "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
}

エラー処理

InvokeHarness API は、スロットリング、検証、アクセス拒否エラーなど、さまざまなエラーで失敗する可能性があります。詳細なリストについては、「Amazon Bedrock AgentCore 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 ポリシーを生成する方法」および「Step Functions でサービス統合パターンを検出する」を参照してください。

Amazon Bedrock AgentCore 統合の IAM ポリシーの例

次の例は、Step Functions 実行ロールの IAM ポリシーを作成して Amazon Bedrock AgentCore リソースとやり取りする方法を示しています。

次のポリシー例では、プレースホルダー値を独自の値に置き換えます。

特定のハーネスを呼び出す 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/*"
        }
    ]
}