小程序开放平台

文档中心
平台概述

getHistoryMessages

更新时间:2025-10-31 14:49:39

getHistoryMessages

方法概述

getHistoryMessages
用于获取指定会话的历史消息记录,支持分页查询和排序功能。该方法主要用于获取对话历史详情,支持按时间排序和游标分页。

基本信息

  1. 函数签名
    getHistoryMessages(params: GetHistoryMessagesParams): Promise<GetHistoryMessagesResponse>
  2. 服务 URI
    GET
    /v1/aiagent/agents/:agentId/messages
  3. 返回类型
    Promise<GetHistoryMessagesResponse>
    - 异步方法,返回历史消息数据
  4. 调用方式 内部方法,由 AgentRuntime 框架提供

功能说明

  • 历史消息获取:获取指定会话的历史消息记录
  • 分页支持:支持游标分页,避免一次性加载大量数据
  • 排序功能:支持按时间升序或降序排列消息
  • 消息详情:提供完整的消息内容和元数据信息

参数说明

GetHistoryMessagesParams 参数数据结构:

字段名
类型
描述
是否必传
conversation_idstring会话 ID
cursorstring请求的游标
countnumber返回消息数量
sortstring排序方式 'desc'、'asc'

参数详细说明

conversation_id 字段

  • 类型:字符串
  • 作用:指定要获取历史消息的会话ID
  • 来源:通常由
    getConversations
    方法返回的会话ID

cursor 字段

  • 类型:字符串(可选)
  • 作用:分页游标,用于获取下一页数据
  • 用途:实现分页查询,避免一次性加载大量数据

count 字段

  • 类型:数字(可选)
  • 作用:指定返回的消息数量
  • 默认值:通常有默认的每页数量限制

sort 字段

  • 类型:字符串(可选)
  • 可选值
    • 'desc'
      - 降序排列(最新的消息在前)
    • 'asc'
      - 升序排列(最早的消息在前)
  • 默认值:通常默认为
    'desc'

返回值说明

该方法返回

GetHistoryMessagesResponse
类型的数据,包含历史消息列表和分页信息。

使用示例

基础使用示例

const agent = this.getAgent();
if (!agent) return;

// 获取会话的历史消息
const historyMessages = await agent.getHistoryMessages({
    conversation_id: "conv_1234567890"
});

console.log("历史消息:", historyMessages);

分页查询示例

const agent = this.getAgent();
if (!agent) return;

// 分页获取历史消息
const historyMessages = await agent.getHistoryMessages({
    conversation_id: "conv_1234567890",
    count: 20,  // 每页20条消息
    cursor: "cursor_1234567890"  // 游标位置
});

console.log("分页消息:", historyMessages);

按时间排序示例

const agent = this.getAgent();
if (!agent) return;

// 按时间升序获取历史消息(最早的消息在前)
const historyMessages = await agent.getHistoryMessages({
    conversation_id: "conv_1234567890",
    sort: "asc",
    count: 50
});

console.log("按时间排序的消息:", historyMessages);

获取最新消息示例

const agent = this.getAgent();
if (!agent) return;

// 获取最新的10条消息
const latestMessages = await agent.getHistoryMessages({
    conversation_id: "conv_1234567890",
    sort: "desc",
    count: 10
});

console.log("最新消息:", latestMessages);

注意事项

⚠️ 重要提醒

  1. 会话ID有效性:确保 conversation_id 是有效的会话ID
  2. 分页处理:使用 cursor 进行分页查询,避免内存溢出
  3. 排序选择:根据业务需求选择合适的排序方式
  4. 数量限制:注意 count 参数的限制,避免请求过多数据
  5. 错误处理:建议添加 try-catch 块处理可能的异常