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

# Personalizar o comportamento do agente do Amazon Bedrock com orquestração personalizada
<a name="agents-custom-orchestration"></a>

O Amazon Bedrock oferece a opção de personalizar a estratégia de orquestração do agente. A orquestração personalizada oferece controle total sobre como você deseja que os agentes lidem com tarefas de várias etapas, tomem decisões e executem fluxos de trabalho. 

Com a orquestração personalizada, você pode criar agentes do Amazon Bedrock que conseguem implementar uma lógica de orquestração específica para seu caso de uso. Isso inclui fluxos de trabalho complexos de orquestração, etapas de verificação ou processos de várias etapas em que os agentes devem realizar várias ações antes de chegar à resposta final. 

Para usar a orquestração personalizada para seu agente, crie uma função do AWS Lambda que descreva a lógica de orquestração. A função controla como o agente responde à entrada fornecendo instruções ao processo de runtime do Bedrock sobre quando e como invocar o modelo e quando invocar ferramentas de ações e, em seguida, determinando a resposta final. 

A opção de orquestração personalizada está disponível em todas as Regiões da AWS onde os Agentes do Amazon Bedrock estão disponíveis. 

É possível configurar a orquestração personalizada no Console de gerenciamento da AWS ou por meio da API. Antes de continuar, verifique se a função do AWS Lambda está pronta para teste.

------
#### [ Console ]

Despois de criar o agente, você pode configurar a orquestração personalizada no console. Configure-os ao editar o agente.

**Como visualizar ou editar a orquestração personalizada para o agente**

1. Faça login no Console de gerenciamento da AWS com uma identidade do IAM que tenha permissões para usar o console do Amazon Bedrock. Em seguida, abra o console do Amazon Bedrock em [https://console.aws.amazon.com/bedrock/](https://console.aws.amazon.com/bedrock).

1. No painel de navegação à esquerda, escolha **Agentes**. Escolha um agente na seção **Agentes**.

1. Na página de detalhes do agente, na seção **Rascunho de trabalho**, selecione **Rascunho de trabalho**.

1. Na página **Rascunho de trabalho**, na seção **Estratégia de orquestração**, escolha **Editar**.

1. Na página **Estratégia de orquestração**, na seção **Detalhes da estratégia de orquestração**, escolha** Orquestração personalizada**.

1. Em **Função do Lambda de orquestração personalizada**, escolha a função do Lambda no menu suspenso e, em **Versão da função**, escolha a versão.

1. Para permitir que o agente use o modelo ao gerar respostas, ative **Ativar modelo**. Se essa configuração estiver desativada, o agente não a usará.

1. Um banner verde é exibido na parte superior da página, indicando que as alterações foram salvas com êxito.

1. Para salvar as configurações, escolha uma das seguintes opções:

   1. Para permanecer na mesma janela e poder alterar dinamicamente a função do AWS Lambda enquanto testa o agente atualizado, escolha **Salvar**.

   1. Para salvar as configurações e retornar à página **Rascunho de trabalho**, escolha **Salvar e sair**.

1. Para testar a orquestração personalizada do agente, escolha **Preparar** na janela **Testar**.

------
#### [ API ]

Para configurar a orquestração personalizada usando as operações de API, envie uma solicitação [UpdateAgent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgent.html) (consulte o link para ver os formatos de solicitação e resposta e detalhes do campo) com um [endpoint de tempo de compilação do recurso Agentes para Amazon Bedrock](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt). Especifique o objeto `orchestrationType` como `CUSTOM_ORCHESTRATION`.

**Exemplo de carga útil de orquestração no React**

A seguir e apresentado um exemplo de reação que mostra a orquestração da cadeia de pensamento. Neste exemplo, após cada etapa, o agente do Amazon Bedrock solicita que o modelo preveja a próxima ação. Observe que o primeiro estado de qualquer conversa é sempre `START`. Eventos são as respostas que a função envia como resposta aos agentes do Amazon Bedrock.

```
function react_chain_of_thought_orchestration(event) {
                    const incomingState = event.state;
                    
                    let payloadData = '';
                    let responseEvent = '';
                    let responseTrace = '';
                    let responseAttribution = '';
                    
                    if (incomingState == 'START') {
                        // 1. Invoke model in start
                        responseEvent = 'INVOKE_MODEL';
                        payloadData = JSON.stringify(intermediatePayload(event));
                    }
                    else if (incomingState == 'MODEL_INVOKED') {
                       const stopReason = modelInvocationStopReason(event);
                       if (stopReason == "tool_use") {
                           // 2.a. If invoke model predicts tool call, then we send INVOKE_TOOL event
                           responseEvent = 'INVOKE_TOOL';
                              payloadData = toolUsePayload(event);
                    } 
                    else if (stopReason == "end_turn") {
                         // 2.b. If invoke model predicts an end turn, then we send FINISH event
                         responseEvent = 'FINISH';
                         payloadData = getEndTurnPayload(event);
                      }
                    }
                    else if (incomingState == 'TOOL_INVOKED') {
                        // 3. After a tool invocation, we again ask LLM to predict what should be the next step
                        responseEvent = 'INVOKE_MODEL';
                        payloadData = intermediatePayload(event);
                    } 
                    else {
                       // Invalid incoming state
                       throw new Error('Invalid state provided!');
                    }
                    
                       // 4. Create the final payload to send back to BedrockAgent
                       const payload = createPayload(payloadData, responseEvent, responseTrace, ...);
                       return JSON.stringify(payload);
                    }
```

**Exemplo de carga útil de orquestração no Lambda**

O exemplo a seguir mostra a orquestração da cadeia de pensamento. Neste exemplo, após cada etapa, o agente do Amazon Bedrock solicita que o modelo preveja a próxima ação. Observe que o primeiro estado de qualquer conversa é sempre `START`. Eventos são as respostas que a função envia como resposta aos agentes do Amazon Bedrock.

A estrutura de carga útil para o Lambda de orquestração

```
{
    "version": "1.0",
    "state": "START | MODEL_INVOKED | TOOL_INVOKED | APPLY_GUARDRAIL_INVOKED | user-defined",
    "input": {
        "text": "user-provided text or tool results in converse format"
    },
    "context": {
        "requestId": "invoke agent request id",
        "sessionId": "invoke agent session id",
        "agentConfiguration": {
            "instruction": "agent instruction>,
            "defaultModelId": "agent default model id",
            "tools": [{
                    "toolSpec": {...} 
                }
                ...
            ],
            "guardrails": {
                "version": "guardrail version",
                "identifier": "guardrail identifier"
            }
        },
        "session": [{
            "agentInput": "input utterance provided in invokeAgent",
            "agentOutput": "output response from invokeAgent",
            "intermediarySteps": [{
                "orchestrationInput": {
                    "state": "START | MODEL_INVOKED | TOOL_INVOKED | APPLY_GUARDRAIL_INVOKED | user defined",
                    "text": "..."
                },
                "orchestrationOutput": {
                    "event": "INVOKE_MODEL | INVOKE_TOOL | APPLY_GUARDRAIL | FINISH | user defined",
                    "text": "Converse API request or text"
                }
            }]
        }],
        "sessionAttributes": {
            key value pairs
        },
        "promptSessionAttributes": {
            key value pairs
        }
    }
}
```

A estrutura de carga útil do Lambda de orquestração

```
{
    "version": "1.0",
    "actionEvent": "INVOKE_MODEL | INVOKE_TOOL | APPLY_GUARDRAIL | FINISH | user defined",
    "output": {
        "text": "Converse API request for INVOKE_MODEL, INVOKE_TOOL, APPLY_GUARDRAIL or text for FINISH",
        "trace": {
            "event": {
                "text": "Trace message to emit as event in InvokeAgent response"
            }
        }
    },
    "context": {
        "sessionAttributes": {
            key value pairs
        },
        "promptSessionAttributes": {
            key value pairs
        }
    }
}
```

Exemplo de START\$1STATE enviado dos Agentes do Amazon Bedrock ao Lambda orquestrador

```
{
    "version": "1.0",
    "state": "START",
    "input": {
        "text": "{\"text\":\"invoke agent input text\"}"
    },
    "context": {
        ...
    }
}
```

Em resposta, se o Lambda de orquestração decidir enviar uma resposta INVOKE\$1MODEL EVENT, ela poderá ser semelhante à seguinte:

```
{
    "version": "1.0",
    "actionEvent": "INVOKE_MODEL",
    "output": {
        "text": "converse API request",
        "trace": {
            "event": {
                "text": "debug trace text"
            }
        }
    },
    "context": {}
}
```

Exemplo de INVOKE\$1TOOL\$1EVENT usando a API Converse 

```
{
    "version": "1.0",
    "actionEvent": "INVOKE_TOOL",
    "output": {
        "text": "{\"toolUse\":{\"toolUseId\":\"unique id\",\"name\":\"tool name\",\"input\":{}}}"
    }
}
```

------