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

# 使用工作階段管理 API 存放和擷取對話歷史記錄與內容
<a name="sessions"></a>

**注意**  
工作階段管理 API 處於預覽狀態，可能會有所變更。

 工作階段管理 API 可讓您在使用 LangGraph 和 LlamaIndex 等開放原始碼架構建置的生成式 AI 應用程式中，儲存用於持續對話的檢查點。您可以使用 API 跨多步驟工作流程安全地管理狀態和對話內容。您不需要為狀態和內容持久性建置、維護或擴展自訂後端解決方案。

您可以使用工作階段管理 API 執行以下操作：
+ 適用於反覆測試和人機迴圈工作流程階段的檢查點工作流程階段。
+  從中斷點繼續對話和任務。
+ 檢閱工作階段日誌以分析工作流程階段和偵錯失敗。

由於工作階段是 Amazon Bedrock 中的資源，因此您可以使用 AWS Identity and Access Management (IAM) 控制對工作階段的存取。根據預設，Amazon Bedrock 會使用 AWS受管金鑰進行工作階段加密，包括工作階段中繼資料，或者您可以使用自己的 AWS KMS 金鑰。如需詳細資訊，請參閱[工作階段加密](sessions-encryption.md)。

 您可以使用 Amazon Bedrock APIs 或 AWS SDKs 建立和管理 Amazon Bedrock 工作階段。對於建置在 LangGraph 上的應用程式，您可以使用`langgraph_checkpoint_aws.saver` 程式庫中的 `BedrockSessionSaver` 類別。這是 LangGraph CheckpointSaver 的自訂實作。如需詳細資訊，請參閱 [LangChain](https://github.com/langchain-ai) GitHub 儲存庫中的 [langgraph-checkpoint-aws](https://github.com/langchain-ai/langchain-aws/tree/main/libs/langgraph-checkpoint-aws)。

**注意**  
您可以使用工作階段來存放使用開放原始碼架構建置之生成式 AI 應用程式的狀態和對話歷史記錄。對於 Amazon Bedrock 代理人，服務會自動管理對話內容，並將其與您在 [InvokeAgent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html) API 操作中指定的代理程式特定 sessionId 建立關聯。

**Topics**
+ [使用案例範例](#sessions-use-case)
+ [工作流程](#sessions-workflow)
+ [考量事項](#sessions-considerations)
+ [工作階段加密](sessions-encryption.md)
+ [建立工作階段以準備儲存對話歷史記錄和內容](sessions-create.md)
+ [在工作階段中存放對話歷史記錄和內容](sessions-store-coversation.md)
+ [從工作階段擷取對話歷史記錄和內容](sessions-retrieve-coversation.md)
+ [在使用者結束對話時結束工作階段](sessions-end-session.md)
+ [刪除工作階段及其所有資料](sessions-delete-session.md)
+ [使用 BedrockSessionSaver LangGraph 程式庫存放和擷取對話歷史記錄與內容](sessions-opensource-library.md)

## 使用案例範例
<a name="sessions-use-case"></a>

您有一個應用程式使用 LangGraph 代理程式來協助客戶規劃行程。使用者可以開始與此代理程式對話，為即將到來的旅程建立行程、新增目的地、偏好的飯店和航班詳細資訊。

透過工作階段管理 API，代理程式可以在延伸的多步驟互動中儲存中繼狀態和持久性內容。代理程式可以在新增每個目的地之後，使用 Amazon Bedrock 工作階段設置其狀態的檢查點，保留客戶偏好設定的詳細資訊。

如果對話中斷或失敗，代理程式可以在稍後以原封不動的內容 (包括文字和影像) 繼續工作階段。這可讓代理程式繼續進行，無需客戶重複提供資訊。此外如果失敗，您可以調查工作階段詳細資訊以偵錯原因。

## 工作流程
<a name="sessions-workflow"></a>

使用工作階段管理 API 的工作流程如下所示。如需有關使用 BedrockSessionSaver 程式庫的資訊，請參閱 [使用 BedrockSessionSaver LangGraph 程式庫管理工作階段](sessions-opensource-library.md)。
+ **建立工作階段** — 最終使用者第一次開始對話時，您會使用 [CreateSession](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_CreateSession.html) API 操作建立工作階段，並指定工作階段的 ID。您在存放和擷取對話狀態時使用此 ID。
+ **存放對話和內容** — 當最終使用者與您的生成式 AI 助理互動時，請使用 [CreateInvocation](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_CreateInvocation.html) API 在工作階段內建立互動群組。對於每次調用，請使用 [PutInvocationStep](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_PutInvocationStep.html) API 操作來存放每次互動的精細狀態檢查點，包括文字和影像。
+ **擷取對話歷史記錄和內容** — 使用 [GetSession](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_GetSession.html)、[ListInvocations](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ListInvocations.html) 和 [GetInvocationStep](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_GetInvocationStep.html) API 操作來擷取工作階段中繼資料和互動詳細資訊。
+ **結束工作階段** — 當工作階段完成時，使用 [EndSession](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_EndSession.html) API 操作結束工作階段。結束工作階段後，您仍然可以存取其內容，但無法新增至其中。若要刪除工作階段及其內容，請使用 [DeleteSession](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_DeleteSession.html) API 操作。

## 考量事項
<a name="sessions-considerations"></a>

在您建立和管理工作階段之前，請注意下列事項：
+ 您可以使用 Amazon Bedrock APIs和 AWS SDKs 建立和管理工作階段。您無法使用 AWS 管理主控台來管理工作階段。
+ 對於建置在 LangGraph 上的代理程式應用程式，您可以使用 `langchain-aws` 程式庫中的 `BedrockSessionSaver` 類別。這是 LangGraph CheckpointSaver 的自訂實作。如需有關使用 BedrockSessionSaver 程式庫的資訊，請參閱 [使用 BedrockSessionSaver LangGraph 程式庫管理工作階段](sessions-opensource-library.md)。若要直接檢視程式碼，請參閱 [LangChain](https://github.com/langchain-ai) GitHub 儲存庫中的 [langgraph-checkpoint-aws](https://github.com/langchain-ai/langchain-aws/tree/main/libs/langgraph-checkpoint-aws)。
+ 如果您在建立工作階段時指定客戶受管 AWS KMS 金鑰，則建立工作階段的使用者或角色必須具有使用金鑰的許可。如需詳細資訊，[工作階段加密](sessions-encryption.md)。
+ 工作階段管理 API 具有下列配額：
  + 工作階段中所有調用之間的調用步驟數目 — 1000
  + 每個調用步驟的大小上限 — 50 MB
  + IdleSession 逾時 — 1 小時
  + 保留期間 — 工作階段資料會在 30 天後自動刪除