Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.
Verwenden Sie Ihre Step Functions-Workflows als Tools für KI-Agenten
Sie können KI-Agenten Ihre Step Functions-Workflows ausführen lassen, indem Sie eine Zustandsmaschine über Amazon Bedrock als MCP-Tools (Model Context Protocol) bereitstellen AgentCore Gateway. Ein mit dem Gateway verbundener Agent kann Ausführungen starten, deren Status und Ausgabe überprüfen, den Ereignisverlauf lesen und Ausführungen beenden. Sie müssen keine Lambda-Funktion schreiben oder die Tools selbst definieren. Das Gateway erstellt die Toolschemas und ruft Step Functions für den Agenten auf.
Dieses Muster ist nützlich, wenn eine Aufgabe jedes Mal dieselben Schritte in derselben Reihenfolge ausführen muss. Der Agent entscheidet, wann der Workflow ausgeführt werden soll und welche Eingaben übergeben werden sollen. Die Zustandsmaschine entscheidet, welche Schritte ausgeführt werden, sodass der Agent sie nicht überspringen oder neu anordnen kann, und der Ausführungsverlauf zeichnet jeden Schritt des Workflows auf.
Sie steuern auf zwei Arten, was der Agent tun kann. Tools, die Ausführungen starten oder auflisten, sind an die von Ihnen gewählte Zustandsmaschine angeheftet, und der Agent kann sie nicht ändern. Tools, die auf eine bestimmte Ausführung reagieren, erhalten vom Agenten einen Amazon Resource Name (ARN) für die Ausführung. Der AWS Identity and Access Management Die Richtlinie für Ihre Gateway-Servicerolle begrenzt, auf welche Ausführungen diese Tools zugreifen können. In diesem Tutorial wird diese Richtlinie auf eine einzelne Zustandsmaschine beschränkt.
In diesem Tutorial erstellen Sie eine einfache Standard-State-Machine und ein Gateway mit einem Step Functions-Connector-Ziel, das darauf verweist. Anschließend tätigen Sie dieselben MCP-Aufrufe wie ein Agent, und verwenden awscurl, sodass Sie jede Anfrage und Antwort sehen können. Wenn Sie bereits eine Standard-State-Machine haben, können Sie zu Schritt 2: Erstellen Sie eine Servicerolle für das Gateway und verwende seinen ARN anstelle von AgentHelloWorld. Dieses Tutorial verwendet einen Standard-Arbeitsablauf, weil ListExecutions, DescribeExecution, und GetExecutionHistory funktioniert nicht mit Express-Ausführungen. Für die Ressourcen, die Sie erstellen, können Gebühren anfallen, bis Sie sie löschen Schritt 6: Bereinigen.
Für die Ressourcen in diesem Tutorial können Gebühren für Step Functions, State Transitions und Amazon Bedrock anfallen AgentCore Aufrufe des Gateway-Tools. Tarife finden Sie unter Preise für Step Functions
Der Step Functions-Connector stellt zehn Operationen zur Verfügung. In diesem Tutorial werden sechs davon konfiguriert: StartExecution, ListExecutions, DescribeStateMachine, DescribeExecution, GetExecutionHistory, und StopExecution. Die vollständige Liste, einschließlich der Task-Token-Operationen und der Unterschiede zwischen Standard- und Express-Workflows, finden Sie unter AWS Step fungiert als Connector-Ziel in der Amazon Bedrock AgentCore Leitfaden für Entwickler.
Voraussetzungen
Stellen Sie vor dem Beginn sicher, dass Sie über Folgendes verfügen:
-
Das AWS CLI Version 2, konfiguriert mit Anmeldeinformationen für Ihr Konto. In den Schritten 3 bis 6 verwenden Sie den AWS CLI.
-
Ein Client, der mit Signature Version 4 signierte HTTP-Anfragen an das Gateway senden kann. Dieses Tutorial verwendet awscurl
, die du mit installieren kannst pip install awscurl. Jeder MCP-Client, der Signature Version 4 unterstützt, funktioniert auf die gleiche Weise. -
Erlaubnis zum Erstellen von IAM-Rollen, Step Functions-Zustandsautomaten und AgentCore Gateways in Ihrem Konto und
bedrock-agentcore:InvokeGatewayBerechtigung auf dem Gateway, das Sie in Schritt 3 für die Identität erstellen, die es in den Schritten 4 und 5 aufruft.
Erstellen Sie alle Ressourcen in diesem Tutorial auf dieselbe Weise AWS-Region. Das Gateway ruft Step Functions in seiner eigenen Region auf, sodass eine Zustandsmaschine in einer anderen Region über den Connector nicht erreichbar ist.
Schritt 1: Erstellen Sie eine Zustandsmaschine
Erstellen Sie eine Standardstatusmaschine, auf der der Agent ausgeführt werden kann. Die folgende Definition hat eine einzige Pass Zustand, der ein festes Ergebnis zurückgibt. Stellen Sie sicher, dass die Konsole auf die Region eingestellt ist, in der Sie das Gateway in Schritt 3 erstellen werden.
Um die Zustandsmaschine (Konsole) zu erstellen
-
Öffnen Sie die AWS Step Functions -Konsole
und wählen Sie Create a state machine (Einen Zustandsautomaten erstellen). -
Wählen Sie Leer, und wählen Sie dann Wählen Sie.
-
Wählen Kodieren und ersetzen Sie die Definition durch die folgende.
{ "Comment": "A workflow that an AI agent starts through AgentCore Gateway", "StartAt": "Hello", "States": { "Hello": { "Type": "Pass", "Result": "Hello from Step Functions", "End": true } } } -
Wählen Sie Config. Für Geben Sie den Maschinennamen an, geben Sie ein
AgentHelloWorld. Behalten Typ als Standard. -
Wählen Erstellen um die Zustandsmaschine zu erstellen.
-
Erlauben Sie Step Functions, eine Ausführungsrolle zu erstellen, wenn Sie dazu aufgefordert werden. Wenn Sie das verwenden AWS CLI Erstellen Sie die Rolle stattdessen selbst, wie im folgenden Verfahren gezeigt.
-
Beachten Sie auf der Seite mit den State-Machine-Details die ARN, wie im folgenden Beispiel gezeigt.
arn:aws:states:region:123456789012:stateMachine:AgentHelloWorld
Um dieselbe Zustandsmaschine zu erstellen mit dem AWS CLI Verwenden Sie stattdessen das folgende Verfahren. Im Gegensatz zur Konsole ist der AWS CLI erstellt keine Ausführungsrolle für Sie, also erstellen Sie zuerst eine. Das Pass-only-Workflow ruft keine anderen Dienste auf, sodass für die Rolle keine Berechtigungsrichtlinie erforderlich ist.
Um die Zustandsmaschine zu erstellen (AWS CLI)
-
Erstellen Sie eine Ausführungsrolle, die Step Functions übernehmen kann. Ersetzen Sie die Region und die Konto-ID durch Ihre eigene.
aws iam create-role \ --role-name AgentHelloWorldExecutionRole \ --assume-role-policy-document '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "states.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "ArnLike": { "aws:SourceArn": "arn:aws:states:" }, "StringEquals": { "aws:SourceAccount": "region:123456789012:stateMachine:*123456789012" } } } ] }' -
Speichern Sie die in der Konsolenprozedur gezeigte Definition in einer Datei mit dem Namen
definition.json, und erstellen Sie dann die Zustandsmaschine.aws stepfunctions create-state-machine \ --name AgentHelloWorld \ --type STANDARD \ --definition file://definition.json \ --role-arn "arn:aws:iam::123456789012:role/AgentHelloWorldExecutionRole" \ --regionregionDie Antwort enthält
stateMachineArn. Notieren Sie es sich für die Schritte 2 und 3.
Schritt 2: Erstellen Sie eine Servicerolle für das Gateway
Das Gateway ruft Step Functions mit einer Servicerolle auf. Beschränken Sie die Rolle auf die von Ihnen erstellte Zustandsmaschine, sodass der Agent nicht auf andere Workflows in Ihrem Konto reagieren kann.
So erstellen Sie die Gateway-Servicerolle
-
Öffnen Sie das IAM-Konsole
und wähle Rollen, Rolle erstellen. -
Für Vertrauenswürdiger Entitätstyp, wählen Benutzerdefinierte Vertrauensrichtlinie, und geben Sie Folgendes ein. Ersetzen Sie die Region und die Konto-ID durch Ihre eigene.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "bedrock-agentcore.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "aws:SourceAccount": "123456789012" }, "ArnLike": { "aws:SourceArn": "arn:aws:bedrock-agentcore:" } } } ] }region:123456789012:gateway/step-functions-gateway-* -
Wählen Sie Weiter, und dann Als Nächstes wieder ohne eine verwaltete Richtlinie anzuhängen.
-
Geben Sie für Role name (Rollenname) den Namen
AgentCoreGatewayToStepFunctionsein und klicken Sie auf Create role (Rolle erstellen). -
Öffnen Sie die Rolle und wählen Sie Fügen Sie Berechtigungen hinzu, Inline-Richtlinie erstellen, wählen Sie JSON, und geben Sie die folgende Richtlinie ein. Ersetzen Sie die Region und die Konto-ID durch Ihre eigene.
{ "Version": "2012-10-17", "Statement": [ { "Sid": "StateMachineOperations", "Effect": "Allow", "Action": [ "states:StartExecution", "states:ListExecutions", "states:DescribeStateMachine" ], "Resource": "arn:aws:states:" }, { "Sid": "ExecutionOperations", "Effect": "Allow", "Action": [ "states:DescribeExecution", "states:GetExecutionHistory", "states:StopExecution" ], "Resource": "region:123456789012:stateMachine:AgentHelloWorldarn:aws:states:" } ] }region:123456789012:execution:AgentHelloWorld:* -
Benennen Sie die Richtlinie
StepFunctionsConnectorAccess, und wählen Sie dann Richtlinie erstellen. -
Notieren Sie sich den Rollen-ARN, wie im folgenden Beispiel gezeigt.
arn:aws:iam::123456789012:role/AgentCoreGatewayToStepFunctions
Ausführungs-ARNs sind ein anderer Ressourcentyp als State-Machine-ARNs, weshalb die Richtlinie zwei Anweisungen enthält.
Wenn Sie die Task-Token-Operationen später verfügbar machen (SendTaskSuccess, SendTaskFailure, und SendTaskHeartbeat), müssen Sie ihnen gewähren "*", weil IAM für diese Aktionen keine Berechtigungen auf Ressourcenebene unterstützt. Das Task-Token ist dann die einzige Kontrolle darüber, welche Aufgaben der Agent ausführen kann. Behandeln Sie Task-Token also als geheim und senden Sie jedes nur an den Agenten, der darauf reagieren soll.
Alle Ziele auf einem Gateway teilen sich ihre Servicerolle. Wenn verschiedene Workflows unterschiedliche IAM-Grenzen benötigen, verwenden Sie für jeden ein eigenes Gateway.
Schritt 3: Erstellen Sie ein Gateway und fügen Sie das Step Functions-Connector-Ziel hinzu
Erstellen Sie ein Gateway, das Anfragen akzeptiert, die mit signiert sind AWS Anmeldeinformationen, und fügen Sie dann ein Ziel hinzu, das das verwendet states verbinden und ihn an Ihre State Machine anschließen.
Um das Gateway und das Ziel zu erstellen
-
Erstellen Sie das Gateway mit dem AWS CLI. Ersetzen Sie den Rollen-ARN durch den aus Schritt 2.
aws bedrock-agentcore-control create-gateway \ --name "step-functions-gateway" \ --protocol-type MCP \ --authorizer-type AWS_IAM \ --role-arn "arn:aws:iam::123456789012:role/AgentCoreGatewayToStepFunctions" \ --regionregionDie Antwort beinhaltet die
gatewayIdundgatewayUrl. Beachten Sie beide. -
Warten Sie, bis der Gateway-Status lautet
READY. Dies kann einige Minuten dauern. ErsetzenGATEWAY_IDmit demgatewayIdaus dem vorherigen Schritt.aws bedrock-agentcore-control get-gateway \ --gateway-identifier "GATEWAY_ID" \ --query status --output text --regionregion -
Fügen Sie das Connector-Ziel hinzu. Der
configurationsDie Liste wählt aus, welche Operationen zu Werkzeugen werden.StartExecution,ListExecutions, undDescribeStateMachinesind an Ihre Staatsmaschine geheftet.DescribeExecution,GetExecutionHistory, undStopExecutionnimm eine Ausführungs-ARN vom Agenten. ErsetzenGATEWAY_IDmit Ihrer Gateway-ID.aws bedrock-agentcore-control create-gateway-target \ --gateway-identifier "GATEWAY_ID" \ --name "hello" \ --target-configuration '{ "mcp": { "connector": { "source": { "connectorId": "states" }, "configurations": [ { "name": "StartExecution", "parameterValues": { "stateMachineArn": "arn:aws:states:" } }, { "name": "ListExecutions", "parameterValues": { "stateMachineArn": "region:123456789012:stateMachine:AgentHelloWorldarn:aws:states:" } }, { "name": "DescribeStateMachine", "parameterValues": { "stateMachineArn": "region:123456789012:stateMachine:AgentHelloWorldarn:aws:states:" } }, { "name": "DescribeExecution" }, { "name": "GetExecutionHistory" }, { "name": "StopExecution" } ] } } }' \ --credential-provider-configurations '[{"credentialProviderType": "GATEWAY_IAM_ROLE"}]' \ --regionregion:123456789012:stateMachine:AgentHelloWorldregion -
Warten Sie, bis der Zielstatus lautet
READY. Dies kann einige Minuten dauern. ErsetzenTARGET_IDmit demtargetIdvon dercreate-gateway-targetAntwort.aws bedrock-agentcore-control get-gateway-target \ --gateway-identifier "GATEWAY_ID" --target-id "TARGET_ID" \ --query status --output text --regionregion
Das Gateway stellt jetzt sechs MCP-Tools zur Verfügung: hello___StartExecution, hello___ListExecutions, hello___DescribeStateMachine, hello___DescribeExecution, hello___GetExecutionHistory, und hello___StopExecution. Das Gateway stellt jedem Toolnamen den Zielnamen voran.
Schritt 4: Starten Sie eine Ausführung über das Gateway
Ein MCP-Client ruft das Gateway mit JSON-RPC Anfragen. Weil das Gateway verwendet AWS_IAM Autorisierung, Anfragen müssen mit Signature Version 4 signiert werden. Die folgenden Beispiele verwenden awscurl, das Anfragen mit Ihrem signiert AWS CLI Anmeldeinformationen. Siehe Voraussetzungen. Ersetzen Sie in jedem Befehl GATEWAY_URL mit dem gatewayUrl ab Schritt 3.
Um eine Ausführung zu starten
-
Listen Sie die Tools auf, die der Agent sieht.
awscurl --service bedrock-agentcore --region\ -X POST "regionGATEWAY_URL" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'In der Antwort werden die sechs Tools mit ihren Eingabeschemas aufgeführt. Beachten Sie das
hello___StartExecutionmacht nur Werbunginput: das angeheftetestateMachineArnist vor dem Agenten verborgen und kann nicht außer Kraft gesetzt werden. -
Startet eine Ausführung.
awscurl --service bedrock-agentcore --region\ -X POST "regionGATEWAY_URL" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "hello___StartExecution", "arguments": { "input": "{\"who\": \"agent\"}" } } }'Das Tool-Ergebnis enthält die Antwort von Step Functions mit dem ARN der neuen Ausführung.
{ "jsonrpc": "2.0", "id": 2, "result": { "isError": false, "content": [ { "type": "text", "text": "{\"executionArn\":\"arn:aws:states:\",\"startDate\":1.7597E9}" } ] } }region:123456789012:execution:AgentHelloWorld:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111Beachten Sie die
executionArnfür den nächsten Schritt.
Schritt 5: Bestätigen Sie das Ergebnis
Verwenden Sie die Tools auf Ausführungsebene, um zu überprüfen, ob die Ausführung erfolgreich war, und um die Ausgabe zu lesen.
Um das Ausführungsergebnis zu bestätigen
-
Beschreiben Sie die Ausführung. Standardmäßig enthält die Antwort nur Metadaten. Um die Eingabe und Ausgabe einzubeziehen, setzen Sie
includedDatazuALL_DATA. ErsetzenEXECUTION_ARNmit demexecutionArnab Schritt 4.awscurl --service bedrock-agentcore --region\ -X POST "regionGATEWAY_URL" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "hello___DescribeExecution", "arguments": { "executionArn": "EXECUTION_ARN", "includedData": "ALL_DATA" } } }'Für diese Zustandsmaschine
statusistSUCCEEDEDundoutputist"Hello from Step Functions". Wenn eine Ausführung fehlschlägt,statusistFAILEDund die Antwort beinhaltet dieerrorundcauseFelder aus dem fehlerhaften Zustand. -
Lesen Sie den Ereignisverlauf, um jeden Schritt der Ausführung zu sehen.
awscurl --service bedrock-agentcore --region\ -X POST "regionGATEWAY_URL" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": { "name": "hello___GetExecutionHistory", "arguments": { "executionArn": "EXECUTION_ARN" } } }' -
Listet die letzten Ausführungen der angehefteten Zustandsmaschine auf, optional nach Status gefiltert.
awscurl --service bedrock-agentcore --region\ -X POST "regionGATEWAY_URL" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": { "name": "hello___ListExecutions", "arguments": { "statusFilter": "SUCCEEDED" } } }' -
(Optional) Bestätigen Sie die Ausführung im AWS Step Functions Konsole
. Wählen AgentHelloWorld, und wähle dann die Ausführung. Eine vom Gateway gestartete Ausführung sieht wie jede andere Ausführung aus, wobei das Gateway die Rolle des Aufrufers einnimmt AWS CloudTrail.
Um eine laufende Ausführung zu beenden, rufen Sie hello___StopExecution mit dem Ausführungs-ARN. Der Aufruf bei einer bereits abgeschlossenen Ausführung ist erfolgreich, hat aber keine Wirkung. Die Antwort gibt die ursprüngliche Endzeit der Ausführung zurück. Bei einem Workflow mit langer Laufzeit ruft ein Agent in der Regel an StartExecutionund dann Umfragen DescribeExecution bis status ist nicht mehr RUNNING.
Schritt 6: Bereinigen
Löschen Sie die Ressourcen, die Sie erstellt haben, um laufende Gebühren zu vermeiden.
So räumen Sie auf
-
Löschen Sie das Gateway-Ziel und dann das Gateway.
aws bedrock-agentcore-control delete-gateway-target \ --gateway-identifier "GATEWAY_ID" --target-id "TARGET_ID" --regionaws bedrock-agentcore-control delete-gateway \ --gateway-identifier "regionGATEWAY_ID" --regionregion -
Löschen Sie in der Step Functions-Konsole das
AgentHelloWorldZustandsmaschine. -
Löschen Sie in der IAM-Konsole den
AgentCoreGatewayToStepFunctionsRolle und die Ausführungsrolle der Zustandsmaschine (die Rolle, die Step Functions für Sie erstellt hat, oderAgentHelloWorldExecutionRolewenn Sie das verwendet haben AWS CLI).
Zugehörige Ressourcen
-
AWS Step fungiert als Connector-Ziel in der Amazon Bedrock AgentCore Leitfaden für Entwickler — alle zehn Operationen, welche Parameter angeheftet werden können, Standard- und Express-Workflow-Einschränkungen und Werkzeugschemas.
-
Fügen Sie ein Connector-Ziel hinzu mit AWS Step-Funktionen — Einrichtung mit Boto3, dem AWS CLI, und der AgentCore CLI und die vollständige Servicerollenrichtlinie, einschließlich Task-Token-Operationen.
-
Erstellen Sie einen Agenten, der Ihren verwendet AgentCore Tor — verbinde ein Agenten-Framework wie Strands Agents oder LangGraph zum Gateway.
-
Amazon Bedrock AgentCore Harness mit Step Functions aufrufen — die umgekehrte Richtung: Rufen Sie einen Agenten aus einem Step Functions Task-Status an.