本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用自訂協同運作來自訂 Amazon Bedrock 代理程式的行為
<a name="agents-custom-orchestration"></a>

Amazon Bedrock 為您提供自訂代理程式協同運作策略的選項。自訂協同運作可讓您完全控制代理程式處理多步驟任務、做出決策和執行工作流程的方式。

使用自訂協同運作，您可以建置可實作使用案例專屬協同運作邏輯的 Amazon Bedrock 代理程式。這包括複雜的協同運作工作流程、驗證步驟或多步驟流程，其中代理程式必須先執行數個動作，才能找到最終答案。

若要針對代理程式使用自訂協同運作，請建立概述您的協同運作邏輯的 AWS Lambda 函數。該函數可控制代理程式回應輸入的方式，方法是提供指示給 Bedrock 的執行時期程序，以說明何時及如何調用模型、何時調用動作工具，然後決定最終回應。

自訂協同運作選項適用於提供 Amazon Bedrock 代理程式的所有 AWS 區域。

您可以在AWS 管理主控台中或透過 API 設定自訂協同運作。在繼續之前，請確定您的 AWS Lambda 函數已準備好進行測試。

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

在主控台，您可以在建立代理程式之後設定自訂協同運作。您可以在編輯代理程式時進行設定。

**檢視或編輯代理程式的自訂協同運作**

1. 使用具有 Amazon Bedrock 主控台使用許可的 IAM 身分登入AWS 管理主控台。接著，開啟位於 [https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock) 的 Amazon Bedrock 主控台。

1. 在左側導覽窗格中，選擇**代理程式**。接著在**代理程式**區段中選擇代理程式。

1. 在代理程式詳細資訊頁面的**工作草稿**區段中，選取**工作草稿**。

1. 在**工作草稿**頁面的**協同運作策略**區段中，選擇**編輯**。

1. 在**協同運作策略**頁面上，於**協同運作策略詳細資訊**區段中，選擇**自訂協同運作**。

1. 對於**自訂協同運作 Lambda 函數**，請從下拉式功能表中選擇 Lambda 函數，對於**函數版本**，請選擇版本。

1. 若要允許代理程式在產生回應時使用該範本，請開啟**啟用範本**。如果關閉此組態，代理程式就不會使用範本。

1. 頁面頂端會出現綠色橫幅，指出已成功儲存變更。

1. 若要儲存設定，請選擇下列其中一個選項：

   1. 若要保持在相同的視窗中，以便在測試更新的代理程式時動態變更 AWS Lambda 函數，請選擇**儲存**。

   1. 若要儲存設定並返回**工作草稿**頁面，請選擇**儲存並結束**。

1. 若要測試代理程式的自訂協同運作，請在**測試**視窗中選擇**準備**。

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

若要使用 API 操作設定自訂協同運作，請使用 [Amazon Bedrock 代理程式建置時期端點](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt)傳送 [UpdateAgent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgent.html) 請求 (請參閱連結以了解請求和回應格式及欄位詳細資訊)。將 `orchestrationType` 物件指定為 `CUSTOM_ORCHESTRATION`。

**React 中的協同運作承載範例**

以下是一個 React 範例，展示了思維鏈協同運作的過程。在此範例中，在每個步驟之後，Amazon Bedrock 代理程式會要求模型預測下一個動作。請注意，任何對話的第一個狀態一律為 `START`。事件是函數傳送的回應，做為對 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);
                    }
```

**Lambda 中的協同運作承載範例**

下列範例展示思維鏈的協同運作過程。在此範例中，在每個步驟之後，Amazon Bedrock 代理程式會要求模型預測下一個動作。請注意，任何對話的第一個狀態一律為 `START`。事件是函數傳送的回應，做為對 Amazon Bedrock 代理程式的回應。

協同運作 Lambda 的承載結構

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

來自協同運作 lambda 的承載結構

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

從 Amazon Bedrock 代理程式傳送至協調器 Lambda 的 START\_STATE 範例

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

作為回應，如果協同運作 Lambda 決定傳送 INVOKE\_MODEL EVENT 回應，回應看起來可能會類似以下內容：

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

使用 Converse API 的 INVOKE\_TOOL\_EVENT 範例 

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

------