HiAgent会话检索：原生不支持关键词搜，两种方案可实现

[1] 一句话结论 #

本指南将讲解HiAgent会话关键词检索的实现方案、踩坑点和边界场景。

[2] 适用场景与不适用场景 #

适用场景

1. 适合已使用HiAgent搭建业务智能体，需要检索近180天内用户会话关键词做运营分析的场景
2. 适合单Agent日均会话量在10万条以内，关键词检索QPS低于5的客服质检场景
3. 适合需要结合用户ID+关键词定向检索特定用户历史对话的个性化服务场景

不适用场景

1. 如果你的场景是需要控制台原生开箱即用的全局关键词检索，建议暂时使用第三方日志检索工具替代
2. 如果你的场景是单Agent日均会话量超过100万条、检索QPS高于20的实时风控场景，建议参考火山引擎日志服务SLS方案
3. 如果你的场景是需要对半年以上的历史会话做关键词检索，建议使用自建Elasticsearch集群方案

[3] 前置准备 #

• 开发环境与版本要求：Python 3.8+ 或 Node.js 16+
• 账号与权限要求：HiAgent全读写权限、OTS实例读写权限
• 依赖项与SDK版本：HiAgent Python SDK v1.2.0 或 OTS SDK v2.2.5
• 预计耗时：约30分钟

[4] 分步实现 #

步骤1：开启长期记忆或OTS存储授权

步骤说明：HiAgent原生会话历史仅支持按会话ID、时间查询，要实现关键词检索必须先开通数据访问通道，要么开启长期记忆生成向量索引，要么授权OTS访问权限获取原始会话数据，跳过该步骤将无法访问结构化的会话内容。
代码/命令：

import volcengine_hiagent
from volcengine_hiagent.models import *

# 初始化HiAgent客户端
client = volcengine_hiagent.Client(
    access_key="YOUR_ACCESS_KEY", # 替换为你的AK
    secret_key="YOUR_SECRET_KEY", # 替换为你的SK
    region="cn-beijing" # 替换为你的实例所在地域
)
# 开启长期记忆配置
req = SetAgentMemoryConfigRequest()
req.agent_id = "YOUR_AGENT_ID" # 替换为你的智能体ID
req.memory_type = "long_term"
req.enable = True
resp = client.set_agent_memory_config(req)

预期结果：请求返回HTTP 200状态码，resp的status字段为"success"，控制台智能体配置页显示长期记忆已开启。

⚠️ 常见错误：开启长期记忆后检索不到历史会话
原因：开启长期记忆前产生的历史会话不会自动生成向量索引，仅对开启后新产生的会话生效
解决方法：如果需要检索旧会话，需要调用离线批量导入接口将历史会话同步到长期记忆库

步骤2：配置长期记忆关键词检索逻辑

步骤说明：如果接受语义匹配结果（比如搜索"退货"也能匹配到相关退款会话），直接调用长期记忆检索接口即可，不需要额外存储开发，适合快速上线的场景。
代码/命令：

req = SearchAgentMemoryRequest()
req.agent_id = "YOUR_AGENT_ID" # 替换为你的智能体ID
req.query = "退款" # 替换为你要检索的关键词
req.filter = "user_id:123456" # 可选：按用户ID、会话时间等条件过滤
req.top_k = 10 # 最多返回10条匹配结果
resp = client.search_agent_memory(req)

预期结果：返回结构化的匹配会话列表，每条结果包含session_id、user_id、匹配的会话片段、语义相似度得分。

步骤3：配置OTS精确关键词检索逻辑（可选）

步骤说明：如果需要100%精确匹配关键词字符串，直接查询HiAgent持久化存储的OTS会话表，对content字段做字符串匹配，适合对检索准确率要求高的场景。
代码/命令：

from tablestore import *
# 初始化OTS客户端
client = OTSClient(
    "YOUR_OTS_ENDPOINT", # 替换为你的OTS实例端点
    "YOUR_ACCESS_KEY",
    "YOUR_SECRET_KEY",
    "YOUR_INSTANCE_NAME" # 替换为你的OTS实例名
)
# 构造精确关键词查询条件
query = TermQuery("content", "退款")
resp = client.search(
    table_name="hiagent_session_history_YOUR_AGENT_ID", # 替换为你的会话表名
    index_name="content_index", # 替换为你创建的全文索引名
    search_query=SearchQuery(query, limit=20)
)

预期结果：返回所有content字段包含目标关键词的会话记录，支持按时间排序、分页查询。

⚠️ 常见错误：OTS查询时返回"index not exist"错误
原因：HiAgent默认不会为OTS会话表创建content字段的二级索引，直接全表扫描会触发OTS的查询限制
解决方法：手动在OTS控制台为session_history表的content字段创建全文索引，或调用OTS创建索引接口完成配置

步骤4：封装检索结果返回逻辑

步骤说明：将检索到的会话片段按时间排序，补充完整的会话上下文、用户信息，对匹配关键词做高亮处理后返回给上层业务系统，跳过该步骤会导致返回结果缺失上下文，无法直接使用。
预期结果：返回符合业务格式要求的会话列表，匹配关键词默认用标签高亮，支持自定义格式。