As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Invoque o Amazon Bedrock AgentCore Harness com Step Functions Você pode integrar o Step Functions com o Amazon Bedrock AgentCore para invocar um arnês de sua máquina de estado. Um arnês é um tempo de execução gerenciado que orquestra a inferência de modelos, o uso de ferramentas e conversas em vários turnos. No Workflow Studio, pesquise **AgentCore InvokeHarness**para encontrar esse estado e arraste-o para o seu fluxo de trabalho. No painel de configuração, você pode criar um novo arnês e uma função de execução usando o **Quick Create Harness** ou selecionar um ARN de chicote existente. Ao usar um equipamento existente, você pode substituir as configurações por invocação — os valores na definição do estado da tarefa substituem os padrões do equipamento. Para ver os parâmetros disponíveis, consulte [InvokeHarness](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeHarness.html)a *Referência da AgentCore API Amazon Bedrock*. Para obter mais informações sobre como aproveitar as funções de execução, consulte [Permissões de tempo de execução](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html) no *Amazon Bedrock AgentCore Developer Guide*. **dica** Para adicionar observabilidade aos seus recursos de agente, ative a Pesquisa de CloudWatch transações. Para obter mais informações, consulte [Adicionar observabilidade aos seus recursos de agente no Guia CloudWatch ](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AgentCore-GettingStarted.html#add-observability-agentic-resources) *do usuário da Amazon*. Para saber mais sobre a integração com AWS serviços no Step Functions, consulte [Integração de produtos da ](integrate-services.md) e. [Transmitir parâmetros a uma API de serviço no Step Functions](connect-parameters.md) **Principais recursos da integração otimizada do AgentCore chicote** Somente o padrão de [Resposta de solicitação](connect-to-resource.md#connect-default) integração é suportado. Os [Aguardar um retorno de chamada com um token de tarefa](connect-to-resource.md#connect-wait-token) padrões [Executar um trabalho (.sync)](connect-to-resource.md#connect-sync) e não são suportados. A resposta é transformada em uma estrutura JSON em forma de [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html#API_runtime_Converse_ResponseSyntax). Somente a mensagem final do assistente é retornada; turnos anteriores em conversas de vários turnos são descartados. As métricas de uso do token (`InputTokens``OutputTokens`,,`TotalTokens`) são agregadas em todas as mensagens na conversa. Somente conteúdo de texto é incluído na resposta. O uso de ferramentas e os blocos de raciocínio são omitidos de. `Output.Message.Content` O tamanho da saída está sujeito ao limite de saída do estado da tarefa. Para o valor atual, consulte[Cotas relacionadas a execuções de tarefas](service-quotas.md#service-limits-task-executions). O estado `InvokeHarness` Tarefa tem um tempo máximo de execução de 15 minutos (900 segundos), mesmo que o `TimeoutSeconds` valor exceda esse limite. Após o tempo limite do estado da tarefa, o chicote continua em execução até atingir seu próprio tempo limite configurado. Para evitar custos inesperados, certifique-se de que o tempo limite do cinto não exceda 15 minutos. A visualização de detalhes da execução do console Step Functions exibe um CloudWatch link ao lado da etapa do agente, fornecendo uma visão detalhada do raciocínio do agente, incluindo o uso de ferramentas. ## O Amazon Bedrock otimizou as APIs de AgentCore aproveitamento A seguinte API é compatível: ### [InvokeHarness](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeHarness.html) Invoca um equipamento para executar um agente de IA que pode usar ferramentas, acessar a memória e executar conversas em vários turnos. **Padrão suportado:** somente Solicitar resposta. Para ver a sintaxe completa da solicitação, consulte [InvokeHarness](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeHarness.html)a *Amazon Bedrock AgentCore API* Reference. **Parâmetros em Step Functions são expressos em PascalCase** Mesmo que a API de serviço nativa esteja no CamelCase, por exemplo, a `startSyncExecution` ação da API, você especifica parâmetros PascalCase em, como:. `StateMachineArn` **Campos de resposta** + `Output.Message`— A mensagem final do assistente do agente. Contém `Role` (sempre`"assistant"`) e `Content` (uma matriz de blocos de texto). Somente o último turno do assistente é retornado; os turnos anteriores em conversas com vários turnos são descartados. + `Output.Message.Content`— Conjunto de blocos de conteúdo. Cada bloco contém um `Text` campo com o texto da resposta do agente. Somente conteúdo de texto é incluído; o uso de ferramentas e os blocos de raciocínio são omitidos. + `StopReason`— Por que o agente parou. Valores: `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`. + `Usage`— Métricas de consumo de tokens agregadas em todos os turnos. Contém `InputTokens``OutputTokens`, `TotalTokens` e. + `Metrics.LatencyMs`— Latência total de invocação em milissegundos, agregada em todos os turnos. **Sintaxe da resposta** ``` { "Output": { "Message": { "Role": "{{string}}", "Content": [ { "Text": "{{string}}" } ] } }, "StopReason": "{{string}}", "Usage": { "InputTokens": {{long}}, "OutputTokens": {{long}}, "TotalTokens": {{long}} }, "Metrics": { "LatencyMs": {{long}} } } ``` **nota** Interromper uma execução ou o estado da Tarefa não impede que o equipamento continue em execução. ## Definição do estado da tarefa para integração com o Amazon Bedrock AgentCore Os exemplos a seguir mostram como definir um estado de tarefa que invoca um arnês Amazon Bedrock AgentCore . O `RuntimeSessionId` campo identifica a sessão de conversação. Use o mesmo ID de sessão em todas as invocações para continuar uma conversa. **nota** O URI do recurso Step Functions usa `bedrockagentcore` (sem hífen), enquanto os ARNs do AgentCore recurso Amazon Bedrock usam `bedrock-agentcore` (com hífen). **Example invocação básica com substituição de modelo e prompt do 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 } ``` **Example invocação com ferramentas (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 } ``` **dica** Você pode testar esse estado individualmente usando a [TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html)API antes de executar uma execução completa. ## Tratamento de erros A `InvokeHarness` API pode falhar com uma variedade de erros, incluindo erros de limitação, validação e acesso negado. Para obter uma lista completa, consulte [InvokeHarnessos erros](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeHarness.html#API_InvokeHarness_Errors) na *referência da AgentCore API Amazon Bedrock*. O exemplo a seguir mostra um estado de tarefa com `Retry` `Catch` campos para tratamento de erros: ``` { "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 do IAM para ligar para o Amazon Bedrock AgentCore Os modelos de exemplo a seguir mostram como AWS Step Functions gera políticas do IAM com base nos recursos na definição da sua máquina de estado. Para obter mais informações, consulte [Como o Step Functions gera políticas do IAM para serviços integrados](service-integration-iam-templates.md) e [Descobrir padrões de integração de serviços no Step Functions](connect-to-resource.md). ### Exemplos de políticas do IAM para integração com o Amazon Bedrock AgentCore Os exemplos a seguir mostram como você pode criar políticas do IAM para que sua função de execução de Step Functions interaja com os AgentCore recursos do Amazon Bedrock. Nos exemplos de políticas a seguir, substitua os valores do espaço reservado pelos seus próprios valores. + [Política do IAM para invocar um equipamento específico](#bedrockagentcore-policy-invoke-specific-harness) + [Política do IAM para invocar todos os chicotes em uma conta](#bedrockagentcore-policy-invoke-all-harnesses) #### Política do IAM para invocar um equipamento específico O exemplo de política a seguir permite invocar um arnês Amazon Bedrock específico AgentCore pelo 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 do IAM para invocar todos os chicotes em uma conta O exemplo de política a seguir permite invocar qualquer AgentCore arnês Amazon Bedrock em sua conta. Recomendamos reduzir o escopo até um ARN de arnês específico, quando possível. ``` { "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** Se seu equipamento usa ferramentas como gateways, navegadores ou interpretadores de código, essas permissões são configuradas na função de execução do *arnês, não na função de execução* do Step Functions. Para obter mais informações, consulte [Aproveitar as permissões da função de execução](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness-security.html) no Guia do * AgentCore usuário do Amazon Bedrock*.