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

# 控制代理程式工作階段內容
<a name="agents-session-state"></a>

若要更好地控制工作階段內容，您可以修改代理程式中的 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_SessionState.html#bedrock-Type-agent-runtime_SessionState](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_SessionState.html#bedrock-Type-agent-runtime_SessionState) 物件。[https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_SessionState.html#bedrock-Type-agent-runtime_SessionState](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_SessionState.html#bedrock-Type-agent-runtime_SessionState) 物件包含可跨回合維護的資訊 (分開 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html) 請求和回應)。您可以使用此資訊，在使用者對話期間為代理程式提供對話內容。

[https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_SessionState.html#bedrock-Type-agent-runtime_SessionState](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_SessionState.html#bedrock-Type-agent-runtime_SessionState) 物件的一般格式如下所示。

```
{
    "sessionAttributes": {
        "{{<attributeName1>}}": "{{<attributeValue1>"}},
        "{{<attributeName2>}}": "{{<attributeValue2>"}},
        ...
    },
     "conversationHistory": {
          "messages": [{
              "role": "user | assistant",
              "content": [{
                  "text": "string"
              }]
          }],
               },
    "promptSessionAttributes": {
        "{{<attributeName3>}}": "{{<attributeValue3>"}},
        "{{<attributeName4>}}": "{{<attributeValue4>"}},
        ...
    },
    "invocationId": "string",
    "returnControlInvocationResults": [
        [ApiResult](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ApiResult.html) or [FunctionResult](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_FunctionResult.html),
        ...
    ],
    "knowledgeBases": [
       {
        "knowledgeBaseId": "string",
        "retrievalConfiguration": {
            "vectorSearchConfiguration": {
                "overrideSearchType": "HYBRID | SEMANTIC",
                "numberOfResults": int,
                "filter": [RetrievalFilter](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrievalFilter.html) object
            }
        }
       },
       ...
    ]
}
```

選取主題以進一步了解 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_SessionState.html#bedrock-Type-agent-runtime_SessionState](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_SessionState.html#bedrock-Type-agent-runtime_SessionState) 物件中的欄位。

**Topics**
+ [工作階段和提示工作階段屬性](#session-state-attributes)
+ [工作階段屬性範例](#session-attribute-ex)
+ [提示工作階段屬性範例](#prompt-session-attribute-ex)
+ [動作群組調用結果](#session-state-return-control)
+ [知識庫擷取組態](#session-state-kb)

## 工作階段和提示工作階段屬性
<a name="session-state-attributes"></a>

Amazon Bedrock 代理程式可讓您定義下列保留在工作階段部分的內容屬性類型：
+ **sessionAttributes** – 在使用者和代理程式之間的[工作階段](advanced-prompts.md#advanced-prompts-terminology)中保留的屬性。使用相同 `sessionId` 提出的所有 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html) 請求都屬於相同的工作階段，只要尚未超過工作階段時間限制 (`idleSessionTTLinSeconds`) 即可。
+ **conversationHistory** – 對於多代理協同作業，如果協作者代理程式啟用了 `conversationalHistorySharing`，則會接受處理執行時間請求的其他內容。根據預設，此欄位會在調用協作者代理程式時由主管代理程式自動建構。您可以選擇性地使用此欄位來提供額外的內容。如需詳細資訊，請參閱 [搭配 Amazon Bedrock 代理人使用多代理協同作業](agents-multi-agent-collaboration.md)。
+ **promptSessionAttributes** – 單一[回合](advanced-prompts.md#advanced-prompts-terminology)持續存在的屬性 (一次 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html) 呼叫)。當您編輯協同運作基本提示範本時，可以使用 $prompt\_session\_attributes$ [預留位置](prompt-placeholders.md)。此預留位置將在執行時期填入您在 `promptSessionAttributes` 欄位中指定的屬性。

您可以在兩個不同步驟中定義工作階段狀態屬性：
+ 當您設定動作群組並[寫入 Lambda 函數](agents-lambda.md)時，請在傳回 Amazon Bedrock 的[回應事件](agents-lambda.md#agents-lambda-response)中包含 `sessionAttributes` 或 `promptSessionAttributes`。
+ 在執行時期期間，當您傳送 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html) 請求時，請在請求內文中包含 `sessionState` 物件，以在對話期間動態變更工作階段狀態屬性。

## 工作階段屬性範例
<a name="session-attribute-ex"></a>

下列範例使用工作階段屬性來個人化傳送給使用者的訊息。

1. 撰寫您的應用程式碼，要求使用者提供其名字和想要向代理程式提出的請求，並將答案儲存為變數 {{<first\_name>}} 和 {{<request>}}。

1. 撰寫您的應用程式程式碼以傳送包含下列內文的 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html) 請求：

   ```
   {
       "inputText": "{{<request>}}",
       "sessionState": {
           "sessionAttributes": {
               "firstName": "{{<first_name>}}"
           }
       }
   }
   ```

1. 當使用者使用您的應用程式並提供其名字時，您的程式碼會將名字做為工作階段屬性傳送，且代理程式會在[工作階段](advanced-prompts.md#advanced-prompts-terminology)期間存放其名字。

1. 由於工作階段屬性是在 [Lambda 輸入事件](agents-lambda.md#agents-lambda-input)中傳送，因此您可以在動作群組的 Lambda 函數中參考這些工作階段屬性。例如，如果動作 [API 結構描述](agents-api-schema.md)在請求內文中需要名字，您可以在為動作群組編寫 Lambda 函數時使用 `firstName` 工作階段屬性，以在傳送 API 請求時自動填入該欄位。

## 提示工作階段屬性範例
<a name="prompt-session-attribute-ex"></a>

下列一般範例使用提示工作階段屬性來提供代理程式的時間內容。

1. 撰寫您的應用程式程式碼，將使用者請求存放在名為 {{<request>}} 的變數中。

1. 撰寫您的應用程式碼，以便如果使用者在 {{<request>}} 中使用表示相對時間的單字 (例如「明天」) 時，可以擷取使用者所在位置的時區，並將其存放在名為 {{<timezone>}} 的變數中。

1. 撰寫您的應用程式以傳送包含下列內文的 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html) 請求：

   ```
   {
       "inputText": "{{<request>}}",
       "sessionState": {
           "promptSessionAttributes": {
               "timeZone": "{{<timezone>}}"
           }
       }
   }
   ```

1. 如果使用者使用指出相對時間的單字，您的程式碼將傳送 `timeZone` 提示工作階段屬性，並且代理程式將在此[回合](advanced-prompts.md#advanced-prompts-terminology)期間存放它。

1. 例如，如果使用者詢問 **I need to book a hotel for tomorrow**，您的程式碼會將使用者的時區傳送給代理程式，而代理程式可以判斷「明天」所指的確切日期。

1. 提示工作階段屬性可用於下列步驟。
   + 如果您在協同運作提示範本中包含 $prompt\_session\_attributes$ [預留位置](prompt-placeholders.md)，FM 的協同運作提示會包含提示工作階段屬性。
   + 提示工作階段屬性會在 [Lambda 輸入事件](agents-lambda.md#agents-lambda-input)中傳送，可用於協助填入 API 請求或在[回應](agents-lambda.md#agents-lambda-response)中傳回。

## 動作群組調用結果
<a name="session-state-return-control"></a>

如果您將動作群組設定為[在 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html) 回應中傳回控制權](agents-returncontrol.md)，您可以加入下列欄位，在後續 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html) 回應的 `sessionState` 中傳送調用動作群組的結果：
+ `invocationId` – 此 ID 必須符合 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html) 回應 `returnControl` 欄位中 [ReturnControlPayload](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ReturnControlPayload.html) 物件傳回的 `invocationId`。
+ `returnControlInvocationResults` – 包括您從調用動作取得的結果。您可以設定應用程式以傳遞 [ReturnControlPayload](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ReturnControlPayload.html) 物件，以執行 API 請求或呼叫您定義的函數。然後，您可以在這裡提供該動作的結果。`returnControlInvocationResults` 清單的每個成員都是下列其中一項：
  + [ApiResult](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ApiResult.html) 物件，其中包含代理程式預測應該在先前 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html) 序列中呼叫的 API 操作，以及在系統中調用動作的結果。一般格式如下所示：

    ```
    {
        "actionGroup": "string",
        "agentId" : :string",
        "apiPath": "string",
        "confirmationState" : "CONFIRM | DENY",
        "httpMethod": "string",
        "httpStatusCode": integer,
        "responseBody": {
            "TEXT": {
                "body": "string"
            }
        }
    }
    ```
  + [FunctionResult](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_FunctionResult.html) 物件，其中包含代理程式預測應該在先前 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html) 序列中呼叫的函數，以及在系統中調用動作的結果。一般格式如下所示：

    ```
    {
        "actionGroup": "string",
        "agentId" : :string",
        "confirmationState" : "CONFIRM | DENY",
        "function": "string",
        "responseBody": {
            "TEXT": {
                "body": "string"
            }
        }
    }
    ```

提供的結果可以用作進一步協同運作的內容、傳送到後製處理，讓代理程式格式化回應，或直接用於代理程式對使用者的回應。

## 知識庫擷取組態
<a name="session-state-kb"></a>

若要修改連接至代理程式之知識庫的擷取組態，請加入 `knowledgeBaseConfigurations` 欄位並包含您要指定其組態的每個知識庫的組態清單。請指定 `knowledgeBaseId`。在 `vectorSearchConfiguration` 欄位中，您可以指定下列查詢組態 (如需這些組態的詳細資訊，請參閱 [設定和自訂查詢和回應產生](kb-test-config.md))：
+ **搜尋類型** – 知識庫是否僅搜尋向量嵌入 (`SEMANTIC`) 或向量內嵌和原始文字 (`HYBRID`)。使用 `overrideSearchType` 欄位。
+ **擷取結果的數量上限** – 查詢擷取要在回應中使用的結果數量上限。
+ **中繼資料和篩選** – 您可以設定的篩選條件，根據資料來源檔案中的中繼資料屬性來篩選結果。