View a markdown version of this page

创建事件 - 亚马逊基岩 AgentCore
事件负载类型提取配置活动分支

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

创建事件

事件是短期的基本单位，从中可以将结构化信息提取到记忆中的长期记 AgentCore 忆中。该CreateEvent操作允许您在 AgentCore 内存中存储各种类型的数据，这些数据按参与者和会话组织。事件的作用域在内存中，如下所示：

ActorId

识别与事件相关的实体，例如最终用户或 agent/user 组合

SessionId

将相关事件分组在一起，例如对话会话

该CreateEvent操作在指定的内存会话中存储一个新的不可变事件。事件代表您的代理想要记住的个别信息，例如对话消息、用户操作或系统事件。

此操作可用于：

  • 记录用户、代理和工具之间的对话历史记录

  • 存储用户互动和行为

  • 捕获系统事件和状态变化

  • 建立会话中按时间顺序排列的活动记录

有关示例代码，请参阅场景：客户支持 AI 代理使用 AgentCore 内存。

注意

如果您想将内容输入长期内存而不将其保留为可检索的短期事件，请改用该IngestData操作。

事件负载类型

该payload参数接受有效负载项目列表，允许您在单个事件中存储不同类型的数据。常见的有效载荷类型包括：

对话式

用于存储带有角色（例如 “用户” 或 “助手”）的对话消息和内容。

JSON

用于存储非对话 JSON-formatted 数据（例如行为事件、活动日志或系统事件），每个有效负载最大 100 KB。

Blob

用于存储二进制格式的数据，例如图像和文档，或代理独有的数据，例如以 JSON 格式存储的数据。

注意

会话和 JSON 有效载荷被提取到长期内存中。Blob 有效载荷仅存储在短期内存中，不能提取。

因为payload是一个列表，所以单个事件可以携带多个有效载荷项目并混合有效载荷类型。以下示例显示了一个将对话消息、JSON 活动日志和二进制 blob（base64 编码的图像）存储在一个事件中的 JSON 请求正文：

示例 — Multi-payload 活动请求 

{
  "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在提取期间将替换为这些变量值。

命名空间变量

自定义命名空间变量键到其值的映射。如果您在创建内存时使用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

分支的描述性名称，例如 “已编辑的对话”。

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