View a markdown version of this page

建立事件 - Amazon Bedrock AgentCore
事件承載類型擷取組態事件分支

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

建立事件

事件是短期的基本單位，從中將結構化資訊擷取到 AgentCore 記憶體中的長期記憶體。CreateEvent 操作可讓您將各種類型的資料存放在 AgentCore 記憶體中，由演員和工作階段組織。事件的範圍在記憶體內：

ActorId

識別與事件相關聯的實體，例如最終使用者或代理程式/使用者組合

SessionId

將相關事件分組在一起，例如對話工作階段

CreateEvent 操作會在指定的記憶體工作階段中存放新的不可變事件。事件代表客服人員想要記住的個別資訊片段，例如對話訊息、使用者動作或系統事件。

此操作適用於：

  • 記錄使用者、客服人員和工具之間的對話歷史記錄

  • 儲存使用者互動和行為

  • 擷取系統事件和狀態變更

  • 在工作階段中建立活動的時間記錄

如需範例程式碼，請參閱案例：客戶使用 AgentCore Memory 支援 AI 代理程式。

注意

如果您想要將內容饋送至長期記憶體，而不將其保留為可擷取的短期事件，請改用 IngestData 操作。

事件承載類型

payload 參數接受承載項目清單，可讓您在單一事件中存放不同類型的資料。常見的承載類型包括：

對話式

用於儲存具有角色 （例如「使用者」或「輔助」) 和內容的對話訊息。

JSON

用於儲存非整合的 JSON 格式資料，例如行為事件、活動日誌或系統事件，每個承載最多 100 KB。

Blob

用於儲存二進位格式資料，例如映像和文件，或代理程式獨有的資料，例如以 JSON 格式存放的資料。

注意

對話和 JSON 承載會擷取到長期記憶體中。Blob 承載只會存放在短期記憶體中，而不會擷取。

因為 payload是清單，單一事件可以攜帶多個承載項目，並混合承載類型。下列範例顯示 JSON 請求內文，可將對話訊息、JSON 活動日誌和二進位 Blob (Base64 編碼影像） 儲存在一個事件中：

範例 – 多承載事件請求 

{
  "memoryId": "mem-12345abcdef",
  "actorId": "agent-support-123/customer-456",
  "sessionId": "session-789",
  "eventTimestamp": 1718806000000,
  "payload": [
    {
      "conversational": {
        "content": {
          "text": "Here's a photo of the camera I'm interested in."
        },
        "role": "USER"
      }
    },
    {
      "json": {
        "content": {
          "eventType": "product_viewed",
          "productId": "cam-9921",
          "category": "action-cameras",
          "priceUsd": 349.99
        }
      }
    },
    {
      "blob": "iVBORw0KGgoAAAANSUhEUg..."
    }
  ]
}

擷取組態

使用 extractionConfig 參數來設定此事件的長期記憶體擷取行為。使用此參數傳遞自訂命名空間變數值，供服務在擷取namespaceTemplates期間取代。

namespaceVariables

自訂命名空間變數索引鍵與其值的映射。如果您在建立記憶體時使用 namespaceKeys 參數定義自訂命名空間變數，請在此處傳遞其值，以便服務可以解析長期記憶體儲存的命名空間階層。所有索引鍵和值都必須是小寫。

下列範例顯示如何在建立事件時傳遞自訂命名空間變數值：

{
  "memoryId": "mem-12345abcdef",
  "actorId": "user456",
  "sessionId": "session789",
  "eventTimestamp": 1692804206123,
  "payload": [
    {
      "conversational": {
        "content": {"text": "I need help with my deployment."},
        "role": "USER"
      }
    }
  ],
  "extractionConfig": {
    "namespaceVariables": {
      "orgname": "engineering",
      "teamname": "backend"
    }
  }
}
注意

如果 中的必要值extractionConfig遺失或無效，CreateEvent操作仍會成功，且事件會保留在短期記憶體中。不過，可能無法針對受影響的策略啟動長期記憶體擷取。設定付費日誌以監控擷取失敗。

事件分支

branch 參數可讓您透過進階分支組織事件。這適用於訊息編輯或替代對話路徑等案例。例如，假設您有一個長時間執行的對話，並且您意識到您有興趣探索從 5 則訊息開始的替代對話。您可以使用 branch 參數從該訊息開始新的對話，並存放在新的分支中，這可讓您返回原始對話。此外，如果您想要讓使用者編輯最近的訊息 （如果使用者提早按下 或輸入錯別字） 並繼續對話，這就很有用。

建立分支時，您可以指定：

name

分支的描述性名稱，例如 "edited-conversation"。

rootEventId

分支來源的事件 ID。

以下是建立分支事件以代表已編輯訊息的範例：

{
  "memoryId": "mem-12345abcdef",
  "actorId": "agent-support-123/customer-456",
  "sessionId": "session-789",
  "eventTimestamp": 1718806000000,
  "payload": [
    {
      "conversational": {
        "content": {
          "text": "I'm looking for a waterproof action camera for extreme sports."
        },
        "role": "USER"
      }
    }
  ],
  "branch": {
    "name": "edited-conversation",
    "rootEventId": "evt-67890"
  }
}