View a markdown version of this page

Utilice sus flujos de trabajo de Step Functions como herramientas para los agentes de IA - AWS Step Functions
Requisitos previosPaso 1: Crear una máquina de estadoPaso 2: Cree un rol de servicio para la puerta de enlacePaso 3: Cree una puerta de enlace y añada el objetivo del conector Step FunctionsPaso 4: Inicie una ejecución a través de la puerta de enlacePaso 5: Confirme el resultadoPaso 6: limpiarRecursos relacionados

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Utilice sus flujos de trabajo de Step Functions como herramientas para los agentes de IA

Puede permitir que los agentes de IA ejecuten sus flujos de trabajo de Step Functions exponiendo una máquina de estados como herramientas del Model Context Protocol (MCP) a través de Amazon Bedrock AgentCore Puerta de enlace. Un agente conectado a la puerta de enlace puede iniciar las ejecuciones, comprobar su estado y resultados, leer el historial de eventos y detener las ejecuciones. No es necesario que escriba una función de Lambda ni que defina las herramientas usted mismo. La puerta de enlace crea los esquemas de herramientas y llama a Step Functions para el agente.

Este patrón es útil cuando una tarea debe ejecutar siempre los mismos pasos en el mismo orden. El agente decide cuándo ejecutar el flujo de trabajo y qué entradas transferir. La máquina de estados decide qué pasos se ejecutan, por lo que el agente no puede omitirlos ni reordenarlos, y el historial de ejecución registra cada paso del flujo de trabajo.

Usted controla lo que puede hacer el agente de dos maneras. Las herramientas que inician o enumeran las ejecuciones están ancladas a la máquina de estados que elija y el agente no puede cambiarla. Las herramientas que actúan sobre una ejecución específica toman un nombre de recurso de Amazon (ARN) de ejecución del agente. El AWS Identity and Access Management la política sobre su función de servicio de puerta de enlace limita las ejecuciones a las que pueden acceder esas herramientas. En este tutorial, se aplica esa política a una sola máquina de estados.

En este tutorial, creará una máquina de estado estándar simple y una puerta de enlace con un conector Step Functions que apunta a ella. A continuación, realiza las mismas llamadas de MCP que hace un agente, utilizando awscurl, para que pueda ver cada solicitud y cada respuesta. Si ya tienes una máquina de estado estándar, puedes ir directamente a Paso 2: Cree un rol de servicio para la puerta de enlace y usa su ARN en lugar de AgentHelloWorld. Este tutorial utiliza un flujo de trabajo estándar porque ListExecutions, DescribeExecution, y GetExecutionHistory no funcionan con ejecuciones exprés. Los recursos que crees pueden generar cargos hasta que los elimines en Paso 6: limpiar.

importante

Los recursos de este tutorial pueden generar cargos por las transiciones de estado de Step Functions y Amazon Bedrock. AgentCore Llamadas a la herramienta Gateway. Para conocer las tarifas, consulte Precios de Step Functions y Amazon Bedrock AgentCore precios. Para evitar cargos continuos, elimina los recursos cuando termines, tal y como se describe en Paso 6: limpiar.

nota

El conector Step Functions expone diez operaciones. Este tutorial configura seis de ellas: StartExecution, ListExecutions, DescribeStateMachine, DescribeExecution, GetExecutionHistory, y StopExecution. Para ver la lista completa, incluidas las operaciones con los tokens de tareas y las diferencias entre los flujos de trabajo Standard y Express, consulte AWS Step funciona como objetivo del conector en el Amazon Bedrock AgentCore Guía para desarrolladores.

Requisitos previos

Antes de comenzar, asegúrese de que dispone de lo siguiente:

  • El AWS CLI versión 2, configurado con las credenciales de su cuenta. En los pasos 3 a 6, utilice el AWS CLI.

  • Un cliente que puede enviar solicitudes HTTP firmadas con la versión 4 de Signature a la puerta de enlace. En este tutorial se utiliza como curvo, que puede instalar con pip install awscurl. Cualquier cliente MCP que admita la versión 4 de Signature funciona de la misma manera.

  • Permiso para crear funciones de IAM, máquinas de estado de Step Functions y AgentCore las pasarelas de su cuenta y el bedrock-agentcore:InvokeGateway permiso en la puerta de enlace que creaste en el paso 3 para la identidad que la invoca en los pasos 4 y 5.

Crea todos los recursos de este tutorial de la misma manera Región de AWS. La puerta de enlace llama a Step Functions en su propia región, por lo que no se puede acceder a una máquina de estados de otra región a través del conector.

Paso 1: Crear una máquina de estado

Cree una máquina de estados estándar para que el agente la ejecute. La siguiente definición tiene una única Pass estado que devuelve un resultado fijo. Asegúrese de que la consola esté configurada en la región en la que creará la puerta de enlace en el paso 3.

Para crear la máquina de estados (consola)

  1. Abra la consola de AWS Step Functions y elija Create state machine (Crear una máquina de estado).

  2. Elige En blancoy, a continuación, elija Seleccione.

  3. Elige Código y sustituya la definición por la siguiente.

    {
  "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. Elige Configurar. Para Nombre de la máquina estatal, introduzca AgentHelloWorld. Conserva Escriba tan Estándar.

  5. Elige Crear para crear la máquina de estados.

  6. Permita que Step Functions cree un rol de ejecución cuando se le solicite. Si utiliza el AWS CLI en su lugar, cree el rol usted mismo, tal y como se muestra en el procedimiento siguiente.

  7. En la página de detalles de la máquina de estados, anote la ARN, como se muestra en el siguiente ejemplo.

    arn:aws:states:region:123456789012:stateMachine:AgentHelloWorld

Para crear la misma máquina de estados con AWS CLI en su lugar, utilice el procedimiento siguiente. A diferencia de la consola, AWS CLI no crea un rol de ejecución para usted, así que cree uno primero. Esto Pass-only workflow no llama a ningún otro servicio, por lo que el rol no necesita una política de permisos.

Para crear la máquina de estados (AWS CLI)

  1. Cree un rol de ejecución que Step Functions pueda asumir. Sustituya la región y la ID de la cuenta por las suyas propias.

    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. Guarde la definición que se muestra en el procedimiento de la consola en un archivo llamado definition.jsony, a continuación, cree la máquina de estados.

    aws stepfunctions create-state-machine \
  --name AgentHelloWorld \
  --type STANDARD \
  --definition file://definition.json \
  --role-arn "arn:aws:iam::123456789012:role/AgentHelloWorldExecutionRole" \
  --region region

    La respuesta contiene el stateMachineArn. Anótelo para los pasos 2 y 3.

Paso 2: Cree un rol de servicio para la puerta de enlace

La puerta de enlace llama a Step Functions con una función de servicio. Asigne el rol a la máquina de estados que creó para que el agente no pueda intervenir en otros flujos de trabajo de su cuenta.

Para crear la función de servicio de puerta de enlace

  1. Abra el Consola de IAM y elige Roles, Crear rol.

  2. Para Tipo de entidad de confianza, elija Política de confianza personalizadae introduzca lo siguiente. Sustituya la región y el identificador de la cuenta por los suyos propios.

    {
  "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. Elige Siguiente, y luego Siguiente de nuevo sin adjuntar una política gestionada.

  4. En Nombre de rol, escriba AgentCoreGatewayToStepFunctions y luego elija Crear rol.

  5. Abra el rol, elija Agregue permisos, Crear una política en línea, elige JSONe introduzca la siguiente política. Sustituya la región y el identificador de la cuenta por los suyos propios.

    {
  "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. Asigne un nombre a la política StepFunctionsConnectorAccessy, a continuación, elija Crear política.

  7. Tenga en cuenta el ARN del rol, como se muestra en el siguiente ejemplo.

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

Los ARN de ejecución son un tipo de recurso diferente al de los ARN de las máquinas de estado, por lo que la política tiene dos sentencias.

Si más adelante expones las operaciones con el token de la tarea (SendTaskSuccess, SendTaskFailure, y SendTaskHeartbeat), debes concederlas el "*", porque IAM no admite permisos a nivel de recursos para estas acciones. Por lo tanto, el token de tarea es el único control sobre qué tareas puede completar el agente, por lo que debe tratar los tokens de tareas como secretos y enviar cada uno de ellos únicamente al agente que debe actuar en consecuencia.

Todos los objetivos de una puerta de enlace comparten su función de servicio. Si distintos flujos de trabajo necesitan diferentes límites de IAM, utilice una puerta de enlace distinta para cada uno.

Paso 3: Cree una puerta de enlace y añada el objetivo del conector Step Functions

Cree una puerta de enlace que acepte solicitudes firmadas con AWS credenciales y, a continuación, agregue un objetivo que utilice el states y lo conecta a su máquina de estado.

Para crear la puerta de enlace y el objetivo

  1. Cree la puerta de enlace con AWS CLI. Sustituya el ARN del rol por el del paso 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

    La respuesta incluye el gatewayId y gatewayUrl. Tenga en cuenta ambos.

  2. Espere hasta que el estado de la puerta de enlace sea READY. Este proceso puede tardar unos minutos. Reemplazar GATEWAY_ID con el gatewayId del paso anterior.

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

  3. Añada el objetivo del conector. El configurations la lista elige qué operaciones se convierten en herramientas. StartExecution, ListExecutions, y DescribeStateMachine están anclados a tu máquina de estado. DescribeExecution, GetExecutionHistory, y StopExecution toma un ARN de ejecución del agente. Reemplazar GATEWAY_ID con su ID de puerta de enlace.

    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. Espere hasta que el estado del objetivo sea READY. Este proceso puede tardar unos minutos. Reemplazar TARGET_ID con el targetId desde el create-gateway-target respuesta.

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

La puerta de enlace ahora expone seis herramientas de MCP: hello___StartExecution, hello___ListExecutions, hello___DescribeStateMachine, hello___DescribeExecution, hello___GetExecutionHistory, y hello___StopExecution. La puerta de enlace antepone el nombre del objetivo al nombre de cada herramienta.

Paso 4: Inicie una ejecución a través de la puerta de enlace

Un cliente MCP llama a la puerta de enlace con JSON-RPC solicitudes. Porque la puerta de enlace usa AWS_IAM para la autorización, las solicitudes deben firmarse con la versión 4 de Signature. Los siguientes ejemplos utilizan awscurl, que firma las solicitudes con su AWS CLI credenciales. Consulte Requisitos previos. En cada comando, sustituya GATEWAY_URL con el gatewayUrl desde el paso 3.

Para iniciar una ejecución

  1. Enumere las herramientas que ve el agente.

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

    La respuesta muestra las seis herramientas con sus esquemas de entrada. Observe que hello___StartExecution solo anuncia input: el anclado stateMachineArn está oculto para el agente y no se puede anular.

  2. Inicie una ejecución.

    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\"}" }
    }
  }'

    El resultado de la herramienta contiene la respuesta de Step Functions con el ARN de la nueva ejecución.

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

    Tenga en cuenta el executionArn para el siguiente paso.

Paso 5: Confirme el resultado

Utilice las herramientas de nivel de ejecución para comprobar si la ejecución se ha realizado correctamente y para leer su resultado.

Para confirmar el resultado de la ejecución

  1. Describa la ejecución. De forma predeterminada, la respuesta solo contiene metadatos. Para incluir la entrada y la salida, defina includedData a ALL_DATA. Reemplazar EXECUTION_ARN con el executionArn desde el paso 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"
      }
    }
  }'

    Para esta máquina de estados, status es SUCCEEDED y output es "Hello from Step Functions". Si una ejecución falla, status es FAILED y la respuesta incluye error y cause campos del estado fallido.

  2. Lea el historial de eventos para ver cada paso de la ejecución.

    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. Enumere las ejecuciones recientes de la máquina de estado anclada y, si lo desea, puede filtrarlas por estado.

    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. (Opcional) Confirme la ejecución en AWS Step Functions consola. Elige AgentHelloWorldy, a continuación, elija la ejecución. Una ejecución iniciada por la puerta de enlace aparece como cualquier otra ejecución, con la función de servicio de la puerta de enlace como la persona que llama en AWS CloudTrail.

nota

Para detener una ejecución en ejecución, llama hello___StopExecution con el ARN de ejecución. Al llamarlo en una ejecución que ya ha finalizado, se realiza correctamente, pero no tiene ningún efecto. La respuesta devuelve la hora de finalización original de la ejecución. Para un flujo de trabajo de larga duración, un agente normalmente llama StartExecutiony, a continuación, sondea DescribeExecution hasta status ya no es RUNNING.

Paso 6: limpiar

Para evitar cargos continuos, elimina los recursos que creaste.

Eliminación

  1. Elimine el destino de la puerta de enlace y, a continuación, la puerta de enlace.

    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. En la consola de Step Functions, elimine el AgentHelloWorld máquina estatal.

  3. En la consola de IAM, elimine el AgentCoreGatewayToStepFunctions el rol y el rol de ejecución de la máquina de estado (el rol que Step Functions creó para usted), o AgentHelloWorldExecutionRole si utilizaste el AWS CLI).