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](#agentcore-gateway-step-2) 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](#agentcore-gateway-step-6). **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](https://aws.amazon.com/step-functions/pricing/) y [Amazon Bedrock AgentCore precios](https://aws.amazon.com/bedrock/agentcore/pricing/). Para evitar cargos continuos, elimina los recursos cuando termines, tal y como se describe en [Paso 6: limpiar](#agentcore-gateway-step-6). **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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-target-connector-step-functions.html) 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](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html), 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](https://github.com/okigan/awscurl), 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](https://console.aws.amazon.com/states/) y elija **Create state machine (Crear una máquina de estado)**. 1. Elige **En blanco**y, a continuación, elija **Seleccione**. 1. 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 } } } ``` 1. Elige **Configurar**. Para **Nombre de la máquina estatal**, introduzca **AgentHelloWorld**. Conserva **Escriba** tan **Estándar**. 1. Elige **Crear** para crear la máquina de estados. 1. 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. 1. 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}}" } } } ] }' ``` 1. Guarde la definición que se muestra en el procedimiento de la consola en un archivo llamado `definition.json`y, 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](https://console.aws.amazon.com/iam/home) y elige **Roles**, **Crear rol**. 1. Para **Tipo de entidad de confianza**, elija **Política de confianza personalizada**e 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-*}}" } } } ] } ``` 1. Elige **Siguiente**, y luego **Siguiente** de nuevo sin adjuntar una política gestionada. 1. En **Nombre de rol**, escriba **AgentCoreGatewayToStepFunctions** y luego elija **Crear rol**. 1. Abra el rol, elija **Agregue permisos**, **Crear una política en línea**, elige **JSON**e 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:*}}" } ] } ``` 1. Asigne un nombre a la política **StepFunctionsConnectorAccess**y, a continuación, elija **Crear política**. 1. 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. 1. 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}}}} ``` 1. 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}}}} ``` 1. 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](#agentcore-gateway-prerequisites). 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. 1. 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. 1. 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}}" } } }' ``` 1. 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" } } }' ``` 1. (Opcional) Confirme la ejecución en [AWS Step Functions consola](https://console.aws.amazon.com/states/). Elige **AgentHelloWorld**y, 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 `StartExecution`y, 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}}}} ``` 1. En la consola de Step Functions, elimine el `AgentHelloWorld` máquina estatal. 1. 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). ## Recursos relacionados + [AWS Step funciona como objetivo del conector](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-target-connector-step-functions.html) en el *Amazon Bedrock AgentCore Guía para desarrolladores* — las diez operaciones, cuyos parámetros se pueden fijar, las restricciones de flujo de trabajo estándar y exprés y los esquemas de herramientas. + [Añada un objetivo de conector con AWS Step Functions](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-add-target-api-target-config.html#gateway-add-target-api-connector-step-functions) — configurado con Boto3, el AWS CLI, y el AgentCore La CLI y la política completa de funciones de servicio, incluidas las operaciones con fichas de tareas. + [Cree un agente que utilice su AgentCore puerta de enlace](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-agent-integration.html) — conecte un marco de agentes como Strands Agents o LangGraph a la puerta de enlace. + [Invoque el AgentCore arnés Amazon Bedrock con Step Functions](connect-bedrockagentcore.md) — en sentido inverso: llame a un agente desde un estado de Step Functions Task.