AG2 记忆接入指南用 Hindsight 的 retain / recall / reflect 工具为 AG2 智能体构建跨会话长期记忆【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsightoutput_article使用 hindsight-ag2 为 AG2 智能体接入 Hindsight 长期记忆hindsight-ag2是 Hindsight 官方提供的 AG2社区版 AutoGen 分支集成包它通过一次调用把hindsight_retain、hindsight_recall、hindsight_reflect三个 Hindsight 工具直接注册到 AG2 智能体上让智能体在会话结束后不再遗忘一切而是能在多次对话之间共享长期记忆。本指南将带你完成安装、注册、连接配置、GroupChat 共享记忆与验证全流程并结合仓库源码说明工具底层如何工作。为什么用 hindsight-ag2AG2 本身就内置了完善的工具调用机制工具是带有Annotated类型注解的普通 Python 函数AG2 会根据这些注解自动生成 LLM 可见的工具 Schema。hindsight-ag2正是利用这一模式把 Hindsight 的三个核心操作包装成 AG2 原生工具hindsight_retain(content)—— 存储内容Hindsight 会从原始文本中抽取事实、实体与关系hindsight_recall(query)—— 多策略搜索Hindsight 依次执行语义检索、BM25、图谱遍历与重排返回带编号的记忆列表hindsight_reflect(query)—— 综合推理基于记忆库的 disposition 特质从所有相关记忆中合成一个有依据的答案。工具注册完成后由智能体自己决定何时存储事实、何时检索过去、何时推理总结——你不需要在代码里硬编码任何记忆读写逻辑。前置条件开始之前请确认以下环境就绪Python 3.10 或更新版本hindsight-ag2的pyproject.toml声明requires-python 3.10AG2 已安装且版本ag2 0.9.0一个可访问的 Hindsight 后端可以是自托管服务器也可以是 Hindsight Cloud自托管 Hindsight 的启动方式可参考仓库根目录 README.md推荐用 Docker 一条命令启动docker run暴露 8888 API 端口也支持 pip 裸机安装hindsight-api后运行hindsight-api以及 Kubernetes Helm 部署。Step 1安装集成包pip install hindsight-ag2安装后即可导入两个核心入口定义见 hindsight-integrations/ag2/hindsight_ag2/init.pyregister_hindsight_tools创建工具并同时注册到 AG2 智能体上一步到位create_hindsight_tools只创建工具函数列表由你手动注册更灵活。包依赖ag20.9.0与hindsight-client0.4.0见 hindsight-integrations/ag2/pyproject.toml。Step 2在智能体上注册工具在 assistant 和执行智能体上一次性注册 Hindsight 工具from autogen import AssistantAgent, UserProxyAgent, LLMConfig from hindsight_ag2 import register_hindsight_tools llm_config LLMConfig(api_typeopenai, modelgpt-4o-mini) with llm_config: assistant AssistantAgent( nameassistant, system_messageYou are a helpful assistant with long-term memory., ) user_proxy UserProxyAgent( nameuser, human_input_modeNEVER, ) # Register Hindsight memory tools on both agents register_hindsight_tools( assistant, user_proxy, bank_idmy-bank, hindsight_api_urlhttp://localhost:8888, ) result user_proxy.initiate_chat( assistant, messageRemember that I prefer Python over JavaScript., )这之后 assistant 就拥有了hindsight_retain、hindsight_recall、hindsight_reflect三个工具。为什么两个智能体都要注册因为 AG2 的工具调用流程是LLM 侧智能体提出工具调用、执行智能体实际运行它——assistant 负责决定调用哪个工具user_proxy 负责真正执行二者缺一不可。源码视角注册背后发生了什么从 hindsight-integrations/ag2/hindsight_ag2/tools.py 可以看到register_hindsight_tools的实现tools create_hindsight_tools(bank_idbank_id, **kwargs) for tool_fn in tools: agent.register_for_llm(descriptiontool_fn.__doc__)(tool_fn) executor.register_for_execution()(tool_fn)它先调用create_hindsight_tools生成工具列表然后对每个工具分别执行register_for_llm把 docstring 作为工具描述提供给 LLM和register_for_execution注册到执行端。这正是 AG2 官方推荐的register_for_llm/register_for_execution配对模式。单元测试 hindsight-integrations/ag2/tests/test_tools.py 验证了注册后 LLM 端调用 3 次、执行端调用 3 次且每次register_for_llm都带上了非空的description。Step 3配置连接configure()允许你一次性设置全局连接与默认参数之后每次调用工具无需重复传参from hindsight_ag2 import configure configure( hindsight_api_urlhttp://localhost:8888, api_keyyour-key, # or set HINDSIGHT_API_KEY env var budgetmid, # low / mid / high max_tokens4096, tags[source:ag2], # default tags for retain )create_hindsight_tools(...)的构造参数会覆盖全局配置因此你可以先设好默认值再按需为某套工具调整budget、max_tokens或tags。源码视角配置解析与客户端解析全局配置定义在 hindsight-integrations/ag2/hindsight_ag2/config.py默认 API 地址是DEFAULT_HINDSIGHT_API_URL https://api.hindsight.vectorize.io即 Hindsight Cloud 的生产端点api_key未显式传入时会回退读取环境变量HINDSIGHT_API_KEYHindsightAG2Config是一个 dataclass字段包括hindsight_api_url、api_key、budget默认mid、max_tokens默认4096、tags、recall_tags、recall_tags_match默认any与verbose配套提供get_config()读取当前全局配置、reset_config()重置为None。客户端解析逻辑在 hindsight-integrations/ag2/hindsight_ag2/_client.py 的resolve_client()优先使用显式传入的client否则从显式参数 → 全局配置依次解析base_url与api_key两者都没有时抛出HindsightError(No Hindsight API URL configured. ...)。构造Hindsight客户端时还注入了 30 秒超时和hindsight-ag2/{version}的 User-Agent。参数总览create_hindsight_tools的完整参数默认值均来自 hindsight-integrations/ag2/hindsight_ag2/tools.py参数默认值说明bank_id必填Hindsight 记忆库 ID记忆的作用域clientNone预先配置好的Hindsight客户端优先级最高hindsight_api_url全局配置或生产地址Hindsight API 地址api_key全局配置或环境变量API 密钥budgetmidrecall/reflect 的预算级别low/mid/highmax_tokens4096recall 结果的最大 token 数tagsNoneretain 存储时附加的默认标签recall_tagsNone搜索记忆时按标签过滤recall_tags_matchany标签匹配模式any/all/any_strict/all_strictretain_metadataNoneretain 操作的元数据字典retain_document_idNoneretain 的文档 ID用于分组 / upsert 记忆recall_typesNone按事实类型过滤world/experience/observationrecall_include_entitiesFalserecall 结果是否包含实体信息reflect_contextNonereflect 操作的附加上下文reflect_max_tokensmax_tokensreflect 结果的最大 token 数reflect_response_schemaNone约束 reflect 输出格式的 JSON Schemareflect_tagsrecall_tagsreflect 使用的记忆过滤标签缺省回退到 recall_tagsreflect_tags_matchrecall_tags_matchreflect 的标签匹配模式include_retainTrue是否包含 retain 工具include_recallTrue是否包含 recall 工具include_reflectTrue是否包含 reflect 工具从源码看create_hindsight_tools内部会把显式参数 → 全局配置 → 内置默认值三级回退例如budget的生效顺序是budget or config.budget or midmax_tokens同理回退到4096。测试文件 hindsight-integrations/ag2/tests/test_tools.py 覆盖了默认 budget 为 mid、显式参数覆盖全局配置等场景。三个工具如何工作三个工具都是带Annotated类型注解的普通 Python 函数AG2 据此自动生成 LLM 可见的 Schemadef hindsight_retain( content: Annotated[ str, The information to store in long-term memory. Include important facts, user preferences, decisions, or anything that should be remembered across conversations., ], ) - str:从 hindsight-integrations/ag2/hindsight_ag2/tools.py 可以看到每个工具的底层调用retain组装{bank_id, content}及可选的tags/metadata/document_id调用resolved_client.retain(**retain_kwargs)成功返回Memory stored successfully.失败抛出HindsightError(Retain failed: ...)recall组装{bank_id, query, budget, max_tokens}及可选的tags/tags_match/types/include_entities调用resolved_client.recall(...)无结果返回No relevant memories found.有结果则编号成1. .../2. ...的列表reflect组装{bank_id, query, budget}及可选的context/max_tokens/response_schema/tags/tags_match调用resolved_client.reflect(...)返回response.text空结果回退为No relevant memories found.。测试 hindsight-integrations/ag2/tests/test_tools.py 逐项验证了参数透传比如 retain 会传递tags、metadata、document_idrecall 会传递budget、max_tokens、tags、tags_match、types、include_entitiesreflect 会传递budget、context、max_tokens、response_schema、tags。任何底层异常都会被包装成HindsightError定义于 hindsight-integrations/ag2/hindsight_ag2/errors.py方便上层统一捕获。高级手动注册工具register_hindsight_tools适合大多数场景当你需要对注册方式做精细控制时可以用create_hindsight_tools手动注册from hindsight_ag2 import create_hindsight_tools tools create_hindsight_tools( bank_idmy-bank, hindsight_api_urlhttp://localhost:8888, ) for tool_fn in tools: assistant.register_for_llm(descriptiontool_fn.__doc__)(tool_fn) user_proxy.register_for_execution()(tool_fn)只安装部分工具通过include_retain/include_recall/include_reflect三个开关可以只注册需要的工具。例如只保留存储和检索tools create_hindsight_tools( bank_idmy-bank, hindsight_api_urlhttp://localhost:8888, include_retainTrue, include_recallTrue, include_reflectFalse, )测试 hindsight-integrations/ag2/tests/test_tools.py 验证了各种组合全部排除时返回空列表只包含某个工具时列表长度为 1 且函数名为对应工具名。GroupChat 中的共享记忆多个智能体可以用同一个bank_id共享一个记忆库注册时统一使用bank_idteam-memory那么 researcher 学到的知识writer 也能读到。from autogen import AssistantAgent, UserProxyAgent, GroupChat, GroupChatManager, LLMConfig from hindsight_ag2 import register_hindsight_tools llm_config LLMConfig(api_typeopenai, modelgpt-4o-mini) with llm_config: researcher AssistantAgent(nameresearcher, system_messageYou research topics.) writer AssistantAgent(namewriter, system_messageYou write content.) executor UserProxyAgent(nameexecutor, human_input_modeNEVER) # All agents share the same memory bank for agent in [researcher, writer]: register_hindsight_tools(agent, executor, bank_idteam-memory) group_chat GroupChat(agents[researcher, writer, executor], messages[]) manager GroupChatManager(groupchatgroup_chat)这里的核心机制是记忆按bank_id隔离凡是注册为同一bank_id的智能体retain 都写入同一个记忆库、recall/reflect 都查询同一个记忆库从而形成团队级共享记忆。验证记忆确实生效一套可靠的验证流程注册工具并开始一次对话告诉智能体一件需要记住的事情让它调用hindsight_retain结束这次对话用相同的bank_id开启一次全新对话询问智能体之前告诉它的内容。示例对话一中说 Remember that I prefer Python over JavaScript.对话二问 What language do I prefer?。如果第二个对话中的智能体能正确回忆起偏好说明记忆链路已打通。你可以在执行智能体的回复或日志中观察它是否真的调用了hindsight_recall/hindsight_reflect。常见错误与排查每次运行用了不同的 bank记忆作用域是bank_id。如果两次对话之间的bank_id不一致第二次运行无法回忆起第一次存储的内容。检查所有register_hindsight_tools/create_hindsight_tools调用中的bank_id是否一致。忘了在执行智能体上也注册register_hindsight_tools需要同时传入 LLM 侧智能体和执行智能体。LLM 侧提出工具调用、执行侧实际运行工具两边都注册了工具调用链才能完成。如果只注册了 assistant执行时会因为找不到对应工具而失败。没有指向一个运行中的后端工具实际调用的是 Hindsight API。运行前确认hindsight_api_url或 Cloud 凭据指向可达的服务器——例如自托管时确认http://localhost:8888已启动、端口已监听。如果既没有传client/hindsight_api_url也没有调用过configure()resolve_client()会直接抛出HindsightError提示缺少 API URL 配置。期望不提问就自动 recall智能体自己决定何时调用工具。如果它始终不调用 recall可以在提示词中引导它去查询已知信息或依赖reflect对已存记忆进行推理总结。FAQ必须要用 Hindsight Cloud 吗不需要。自托管服务器同样可用——把hindsight_api_url指向你的服务器例如http://localhost:8888不传该参数时才默认使用 Cloud 生产地址。自托管部署方式见仓库根目录 README.md 与 docker/docker-compose 下的编排示例。多个智能体可以共享记忆吗可以。用同一个bank_id在每个智能体上注册工具即可共享同一个记忆库GroupChat 场景正是这样工作的。可以只安装部分工具吗可以。create_hindsight_tools支持include_retain、include_recall、include_reflect三个开关按需注册。如何控制 recall 的深度设置budgetlow/mid/high和max_tokens既可以在configure(...)中全局设置也可以通过create_hindsight_tools(...)按工具集覆盖。测试验证了budget和max_tokens会原样透传给client.recall。连接失败会怎样retain / recall / reflect 任一调用抛出异常时集成层会记录日志并以HindsightError形式重新抛出消息形如 Retain failed: ... / Recall failed: ... / Reflect failed: ...便于在你的代码中统一 try/except 处理。进一步探索完整集成说明与参数表hindsight-docs/docs-integrations/ag2.md集成包源码hindsight-integrations/ag2/hindsight_ag2/tools.py、hindsight-integrations/ag2/hindsight_ag2/config.py、hindsight-integrations/ag2/hindsight_ag2/_client.py集成包 READMEhindsight-integrations/ag2/README.md单元测试参数透传与错误处理验证hindsight-integrations/ag2/tests/test_tools.py项目总览与快速开始README.md/output_article【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考