翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# カスタムオーケストレーションを使用して 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 ID を使用して、AWS マネジメントコンソールにサインインします。Amazon Bedrock コンソール ([https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/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\$1STATE の例

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

オーケストレーション Lambda が INVOKE\$1MODEL EVENT レスポンスを送信することにした場合のレスポンスは次のようになります。

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

Converse API を使用した INVOKE\$1TOOL\$1EVENT の例 

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

------