View a markdown version of this page

Verwenden Sie Ihre Step Functions-Workflows als Tools für KI-Agenten - AWS Step Functions

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.

Wichtig

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 und Amazon Bedrock AgentCore Preisgestaltung. Um laufende Gebühren zu vermeiden, löschen Sie die Ressourcen, wenn Sie fertig sind, wie unter beschrieben Schritt 6: Bereinigen.

Anmerkung

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:InvokeGateway Berechtigung 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
  1. Öffnen Sie die AWS Step Functions -Konsole und wählen Sie Create a state machine (Einen Zustandsautomaten erstellen).

  2. Wählen Sie Leer, und wählen Sie dann Wählen Sie.

  3. 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 } } }
  4. Wählen Sie Config. Für Geben Sie den Maschinennamen an, geben Sie ein AgentHelloWorld. Behalten Typ als Standard.

  5. Wählen Erstellen um die Zustandsmaschine zu erstellen.

  6. 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.

  7. 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)
  1. 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:region:123456789012:stateMachine:*" }, "StringEquals": { "aws:SourceAccount": "123456789012" } } } ] }'
  2. 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" \ --region region

    Die 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
  1. Öffnen Sie das IAM-Konsole und wähle Rollen, Rolle erstellen.

  2. 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-*" } } } ] }
  3. Wählen Sie Weiter, und dann Als Nächstes wieder ohne eine verwaltete Richtlinie anzuhängen.

  4. Geben Sie für Role name (Rollenname) den Namen AgentCoreGatewayToStepFunctions ein und klicken Sie auf Create role (Rolle erstellen).

  5. Ö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:region:123456789012:stateMachine:AgentHelloWorld" }, { "Sid": "ExecutionOperations", "Effect": "Allow", "Action": [ "states:DescribeExecution", "states:GetExecutionHistory", "states:StopExecution" ], "Resource": "arn:aws:states:region:123456789012:execution:AgentHelloWorld:*" } ] }
  6. Benennen Sie die Richtlinie StepFunctionsConnectorAccess, und wählen Sie dann Richtlinie erstellen.

  7. Notieren Sie sich den Rollen-ARN, wie im folgenden Beispiel gezeigt.

    arn:aws:iam::123456789012:role/AgentCoreGatewayToStepFunctions
Anmerkung

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
  1. 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" \ --region region

    Die Antwort beinhaltet die gatewayId und gatewayUrl. Beachten Sie beide.

  2. Warten Sie, bis der Gateway-Status lautet READY. Dies kann einige Minuten dauern. Ersetzen GATEWAY_ID mit dem gatewayId aus dem vorherigen Schritt.

    aws bedrock-agentcore-control get-gateway \ --gateway-identifier "GATEWAY_ID" \ --query status --output text --region region
  3. Fügen Sie das Connector-Ziel hinzu. Der configurations Die Liste wählt aus, welche Operationen zu Werkzeugen werden. StartExecution, ListExecutions, und DescribeStateMachine sind an Ihre Staatsmaschine geheftet. DescribeExecution, GetExecutionHistory, und StopExecution nimm eine Ausführungs-ARN vom Agenten. Ersetzen GATEWAY_ID mit 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:region:123456789012:stateMachine:AgentHelloWorld" } }, { "name": "ListExecutions", "parameterValues": { "stateMachineArn": "arn:aws:states:region:123456789012:stateMachine:AgentHelloWorld" } }, { "name": "DescribeStateMachine", "parameterValues": { "stateMachineArn": "arn:aws:states:region:123456789012:stateMachine:AgentHelloWorld" } }, { "name": "DescribeExecution" }, { "name": "GetExecutionHistory" }, { "name": "StopExecution" } ] } } }' \ --credential-provider-configurations '[{"credentialProviderType": "GATEWAY_IAM_ROLE"}]' \ --region region
  4. Warten Sie, bis der Zielstatus lautet READY. Dies kann einige Minuten dauern. Ersetzen TARGET_ID mit dem targetId von der create-gateway-target Antwort.

    aws bedrock-agentcore-control get-gateway-target \ --gateway-identifier "GATEWAY_ID" --target-id "TARGET_ID" \ --query status --output text --region region

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
  1. Listen Sie die Tools auf, die der Agent sieht.

    awscurl --service bedrock-agentcore --region region \ -X POST "GATEWAY_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___StartExecution macht nur Werbung input: das angeheftete stateMachineArn ist vor dem Agenten verborgen und kann nicht außer Kraft gesetzt werden.

  2. Startet eine Ausführung.

    awscurl --service bedrock-agentcore --region region \ -X POST "GATEWAY_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:region:123456789012:execution:AgentHelloWorld:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111\",\"startDate\":1.7597E9}" } ] } }

    Beachten Sie die executionArn fü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
  1. Beschreiben Sie die Ausführung. Standardmäßig enthält die Antwort nur Metadaten. Um die Eingabe und Ausgabe einzubeziehen, setzen Sie includedData zu ALL_DATA. Ersetzen EXECUTION_ARN mit dem executionArn ab Schritt 4.

    awscurl --service bedrock-agentcore --region region \ -X POST "GATEWAY_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 status ist SUCCEEDED und output ist "Hello from Step Functions". Wenn eine Ausführung fehlschlägt, status ist FAILED und die Antwort beinhaltet die error und cause Felder aus dem fehlerhaften Zustand.

  2. Lesen Sie den Ereignisverlauf, um jeden Schritt der Ausführung zu sehen.

    awscurl --service bedrock-agentcore --region region \ -X POST "GATEWAY_URL" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": { "name": "hello___GetExecutionHistory", "arguments": { "executionArn": "EXECUTION_ARN" } } }'
  3. Listet die letzten Ausführungen der angehefteten Zustandsmaschine auf, optional nach Status gefiltert.

    awscurl --service bedrock-agentcore --region region \ -X POST "GATEWAY_URL" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": { "name": "hello___ListExecutions", "arguments": { "statusFilter": "SUCCEEDED" } } }'
  4. (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.

Anmerkung

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
  1. 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" --region region aws bedrock-agentcore-control delete-gateway \ --gateway-identifier "GATEWAY_ID" --region region
  2. Löschen Sie in der Step Functions-Konsole das AgentHelloWorld Zustandsmaschine.

  3. Löschen Sie in der IAM-Konsole den AgentCoreGatewayToStepFunctions Rolle und die Ausführungsrolle der Zustandsmaschine (die Rolle, die Step Functions für Sie erstellt hat, oder AgentHelloWorldExecutionRole wenn Sie das verwendet haben AWS CLI).