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.
Invoque el AgentCore arnés Amazon Bedrock con Step Functions
Puede integrar Step Functions con Amazon Bedrock AgentCore para invocar un arnés desde su máquina de estados. Un arnés es un tiempo de ejecución gestionado que organiza la inferencia del modelo, el uso de herramientas y las conversaciones en varios turnos. En Workflow Studio, busque este estado y arrástrelo AgentCore InvokeHarnessa su flujo de trabajo.
Desde el panel de configuración, puede crear un nuevo arnés y un rol de ejecución mediante Quick Create Harness o seleccionar un ARN de arnés existente. Cuando utiliza un arnés existente, puede anular las configuraciones por invocación: los valores de la definición del estado de la tarea anulan los valores predeterminados del arnés. Para ver los parámetros disponibles, consulte InvokeHarnessla referencia de la AgentCore API de Amazon Bedrock. Para obtener más información sobre las funciones de ejecución de arneses, consulte los permisos de ejecución en la Guía para AgentCore desarrolladores de Amazon Bedrock.
sugerencia
Para añadir observabilidad a los recursos de su agencia, active la búsqueda de transacciones. CloudWatch Para obtener más información, consulte Añadir observabilidad a los recursos de su agencia en la Guía del usuario de Amazon CloudWatch .
Para obtener más información sobre la integración con AWS los servicios de Step Functions, consulte Integración de los servicios de yCómo pasar parámetros a una API de servicio en Step Functions.
Características principales de la integración optimizada del AgentCore arnés
-
Solo se admite el patrón de Respuesta de la solicitud integración. Los Cómo esperar una devolución de llamada con el token de tarea patrones Ejecutar un trabajo (.sync) y no son compatibles.
-
La respuesta se transforma en una estructura JSON con forma de Converse. Solo se devuelve el mensaje final del asistente; los turnos anteriores en las conversaciones de varios turnos se descartan.
-
Las métricas de uso de los tokens (
InputTokensOutputTokens,,TotalTokens) se agregan a todos los mensajes de la conversación. -
En la respuesta solo se incluye el contenido de texto. Se omiten los bloques de uso de herramientas y razonamiento.
Output.Message.Content -
El tamaño de la salida está sujeto al límite de salida del estado de la tarea. Para conocer el valor actual, consulteCuotas relacionadas con ejecuciones de tarea.
-
El estado de la
InvokeHarnesstarea tiene un tiempo de ejecución máximo de 15 minutos (900 segundos), incluso si elTimeoutSecondsvalor supera ese límite. Cuando se agota el tiempo de espera del estado de la tarea, el arnés continúa ejecutándose hasta alcanzar su propio tiempo de espera configurado. Para evitar costes inesperados, asegúrese de que el tiempo de espera del arnés no supere los 15 minutos. -
La vista de detalles de ejecución de la consola Step Functions muestra un CloudWatch enlace junto al paso del agente, que proporciona una vista paso a paso del razonamiento del agente, incluido el uso de la herramienta.
APIs de aprovechamiento optimizadas de Amazon Bedrock AgentCore
Se admite la siguiente API:
InvokeHarness
Utiliza un arnés para ejecutar un agente de IA que puede usar herramientas, acceder a la memoria y ejecutar conversaciones en varios turnos.
Patrón compatible: solo solicitud de respuesta.
Para ver la sintaxis completa de la solicitud, consulte InvokeHarnessla referencia de la AgentCore API de Amazon Bedrock.
Parámetros en Step Functions se expresan en PascalCase
Incluso si la API del servicio nativo está en CamelCase, por ejemplo, la startSyncExecution acción de la API, se especifican parámetros PascalCase en, como:. StateMachineArn
Campos de respuesta
-
Output.Message— El último mensaje de asistente del agente. ContieneRole(siempre"assistant") yContent(una matriz de bloques de texto). Solo se devuelve el último turno del asistente; se descartan los turnos anteriores en las conversaciones de varios turnos. -
Output.Message.Content— Matriz de bloques de contenido. Cada bloque contiene unTextcampo con el texto de respuesta del agente. Solo se incluye el contenido de texto; se omiten los bloques de uso de herramientas y razonamiento. -
StopReason— Por qué se detuvo el agente. Valores:end_turn,max_tokens,stop_sequenceytool_use. -
Usage— Las métricas de consumo de fichas se agregaron en todos los turnos. ContieneInputTokens,OutputTokens, yTotalTokens. -
Metrics.LatencyMs— Latencia total de invocación en milisegundos, agregada en todos los turnos.
Sintaxis de la respuesta
{
"Output": {
"Message": {
"Role": "string",
"Content": [
{
"Text": "string"
}
]
}
},
"StopReason": "string",
"Usage": {
"InputTokens": long,
"OutputTokens": long,
"TotalTokens": long
},
"Metrics": {
"LatencyMs": long
}
}nota
Detener una ejecución o el estado de la tarea no impide que el arnés siga funcionando.
Definición del estado de la tarea para la integración de Amazon Bedrock AgentCore
Los siguientes ejemplos muestran cómo definir un estado de tarea que invoca un arnés de Amazon Bedrock AgentCore .
El RuntimeSessionId campo identifica la sesión de conversación. Usa el mismo ID de sesión en todas las invocaciones para continuar una conversación.
nota
El URI del recurso Step Functions usa bedrockagentcore (sin guión), mientras que los ARN de AgentCore recursos de Amazon Bedrock usan bedrock-agentcore (con guión).
ejemplo invocación básica con anulación del modelo y mensaje del sistema
{
"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
}ejemplo invocación con herramientas (navegador)
{
"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
}sugerencia
Puede probar este estado de forma individual mediante la TestStateAPI antes de ejecutar una ejecución completa.
Gestión de errores
La InvokeHarness API puede fallar debido a diversos errores, como errores de limitación, validación y acceso denegado. Para obtener una lista completa, consulte InvokeHarnesslos errores en la referencia de la AgentCore API de Amazon Bedrock.
El siguiente ejemplo muestra el estado de una tarea con Retry Catch campos para la gestión de errores:
{
"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
}Políticas de IAM para llamar a Amazon Bedrock AgentCore
En las siguientes plantillas de ejemplo, se muestra cómo se AWS Step Functions generan las políticas de IAM en función de los recursos de la definición de su máquina de estados. Para obtener más información, consulte Generación de políticas de IAM para servicios integrados por Steps Functions y Descubrimiento de los patrones de integración de servicios en Step Functions.
Ejemplos de políticas de IAM para la integración de Amazon Bedrock AgentCore
Los siguientes ejemplos muestran cómo puede crear políticas de IAM para que su función de ejecución de Step Functions interactúe con los recursos de Amazon Bedrock AgentCore.
En los siguientes ejemplos de políticas, sustituya los valores de los marcadores de posición por sus propios valores.
Política de IAM para invocar un arnés específico
El siguiente ejemplo de política permite invocar un AgentCore arnés Amazon Bedrock específico mediante el 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"
}
]
}Política de IAM para invocar todos los arneses de una cuenta
El siguiente ejemplo de política permite invocar cualquier AgentCore arnés de Amazon Bedrock de su cuenta. Recomendamos utilizar un ARN de arnés específico siempre que sea posible.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "InvokeAllHarnesses",
"Effect": "Allow",
"Action": [
"bedrock-agentcore:InvokeHarness",
"bedrock-agentcore:InvokeAgentRuntime"
],
"Resource": "arn:aws:bedrock-agentcore:region:accountId:harness/*"
}
]
}nota
Si su arnés utiliza herramientas como puertas de enlace, navegadores o intérpretes de código, esos permisos se configuran en el rol de ejecución del arnés, no en el rol de ejecución de Step Functions. Para obtener más información, consulte Aprovechar los permisos de las funciones de ejecución en la Guía del AgentCore usuario de Amazon Bedrock.
