Richiama il AgentCore cablaggio Amazon Bedrock con Step Functions

Puoi integrare Step Functions con Amazon Bedrock AgentCore per richiamare un cablaggio dalla tua macchina a stati. Un harness è un runtime gestito che orchestra l'inferenza del modello, l'uso degli strumenti e le conversazioni a turni multipli. In Workflow Studio, cerca AgentCore InvokeHarnessquesto stato e trascinalo nel tuo flusso di lavoro.

Dal pannello di configurazione, è possibile creare un nuovo cablaggio e un nuovo ruolo di esecuzione utilizzando Quick Create Harness o selezionare un ARN del cablaggio esistente. Quando si utilizza un cablaggio esistente, è possibile sovrascrivere le configurazioni in base alla chiamata: i valori nella definizione dello stato del task hanno la precedenza sui valori predefiniti del cablaggio. Per i parametri disponibili, InvokeHarnessconsulta Amazon Bedrock AgentCore API Reference. Per ulteriori informazioni sui ruoli di esecuzione dell'harness, consulta le autorizzazioni di runtime nella Amazon Bedrock AgentCore Developer Guide.

Per ulteriori informazioni sull'integrazione con AWS i servizi in Step Functions, vedere Integrazione dei servizi ePassaggio di parametri a un'API di servizio in Step Functions.

API di AgentCore cablaggio Amazon Bedrock ottimizzate

Sono supportate le seguenti API:

InvokeHarness

Richiama un cablaggio per eseguire un agente AI in grado di utilizzare strumenti, accedere alla memoria ed eseguire conversazioni a più turni.

Modello supportato: solo Request Response.

Per la sintassi completa della richiesta, consulta InvokeHarnessAmazon Bedrock AgentCore API Reference.

Campi di risposta

Sintassi della risposta

{
  "Output": {
    "Message": {
      "Role": "string",
      "Content": [
        {
          "Text": "string"
        }
      ]
    }
  },
  "StopReason": "string",
  "Usage": {
    "InputTokens": long,
    "OutputTokens": long,
    "TotalTokens": long
  },
  "Metrics": {
    "LatencyMs": long
  }
}

Definizione dello stato delle attività per l'integrazione con Amazon Bedrock AgentCore

I seguenti esempi mostrano come definire uno stato Task che richiami un harness Amazon AgentCore Bedrock.

Il RuntimeSessionId campo identifica la sessione di conversazione. Usa lo stesso ID di sessione per tutte le chiamate per continuare una conversazione.

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

Gestione degli errori

L'InvokeHarnessAPI può fallire con una serie di errori, tra cui limitazione, convalida ed errori di accesso negato. Per un elenco completo, consulta InvokeHarnessgli errori nell'Amazon Bedrock AgentCore API Reference.

L'esempio seguente mostra uno stato di Task con Retry Catch campi per la gestione degli errori:

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

Politiche IAM per le chiamate ad Amazon Bedrock AgentCore

I seguenti modelli di esempio mostrano come AWS Step Functions generare le politiche IAM in base alle risorse nella definizione della macchina a stati. Per ulteriori informazioni, consultare In che modo Step Functions genera policy IAM per servizi integrati e Scopri i modelli di integrazione dei servizi in Step Functions.

Esempi di policy IAM per l'integrazione con Amazon Bedrock AgentCore

Gli esempi seguenti mostrano come puoi creare policy IAM per il tuo ruolo di esecuzione Step Functions per interagire con le AgentCore risorse di Amazon Bedrock.

Nei seguenti esempi di policy, sostituisci i valori segnaposto con i tuoi valori.

Politica IAM per richiamare un cablaggio specifico

La seguente policy di esempio consente di richiamare uno specifico AgentCore harness Amazon Bedrock tramite ARN.

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

Politica IAM per richiamare tutti i cablaggi in un account

La seguente politica di esempio consente di richiamare qualsiasi AgentCore cablaggio Amazon Bedrock nel tuo account. Si consiglia di limitarsi a un ARN di imbracatura specifico, quando possibile.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "InvokeAllHarnesses",
            "Effect": "Allow",
            "Action": [
                "bedrock-agentcore:InvokeHarness",
                "bedrock-agentcore:InvokeAgentRuntime"
            ],
            "Resource": "arn:aws:bedrock-agentcore:region:accountId:harness/*"
        }
    ]
}