TypeError: cannot use ‘weakref.ReferenceType’ as a dict key (unhashable type: ‘FunctionAgent’)

问题场景

用户按照 LlamaIndex 官方文档中的 FunctionalAgent / Agent 示例编写代码，把 LLM 换成 OpenAILike，其余代码与文档一致。依赖通过 pip install llama-index-core llama-index-llms-openai-like python-dotenv 安装。报错不是发生在构建 Agent 时，而是发生在执行下面这一步时：

response = await workflow.run(user_msg="What is 20+(2*4)?")
print(response)

也就是说，Agent 定义、LLM 接入这些步骤都能通过，真正触发异常的是 workflow 的运行阶段。

报错原文

Traceback:
  File ".venv\Lib\site-packages\workflows\runtime\types\plugin.py", line 603, in Runtime._compose_serializer
    cached = self._serializer_cache.get(workflow)
  File "~\AppData\Local\Python\pythoncore-3.14-64\Lib\weakref.py", line 357, in WeakKeyDictionary.get
    return self.data.get(ref(key),default)

TypeError: cannot use 'weakref.ReferenceType' as a dict key (unhashable type: 'FunctionAgent')

原因分析

从 Traceback 看，异常发生在 workflows 运行时的序列化器缓存逻辑中：Runtime._compose_serializer 尝试用 workflow 对象作为 key 去查询 _serializer_cache（一个 WeakKeyDictionary），而 WeakKeyDictionary.get 内部会先构造 weakref 引用再作为字典 key 使用。当 FunctionAgent 这个对象不可哈希时，这一步就会抛出上面的 TypeError。

结合维护者的回复可以判断，这不是用户的 Agent 代码写法问题，而是 llama-index-workflows 与 llama-index-core 在 0.14.24 这一组合下的兼容性 bug，官方在 v0.14.25 中做了修复。因此“降级 workflows”只是一种规避思路，根因在库版本本身。

环境排查

• 确认 llama-index / llama-index-core 的具体版本，重点看是否仍停留在 0.14.24。
• 确认 llama-index-workflows 的版本，Issue 中触发问题的版本为 2.24.0。
• 确认 Python 版本与解释器路径是否与报错一致（Issue 中为 Python 3.14）。
• 确认 LLM 接入方式（Issue 使用 llama-index-llms-openai-like），但该部分并非报错点。
• CUDA、PyTorch、显卡等本项目未涉及，无需在此场景中排查。

解决步骤

1. 先把 llama-index（或 llama-index-core）升级到 0.14.25 或更高版本，这是维护者明确说明已修复该问题的版本。
2. 升级后重新执行 workflow.run(user_msg=...) 这一段，确认异常是否消失。
3. 如果因为环境限制暂时无法升级，可优先尝试按维护者建议把 llama-index-workflows 降级到较旧版本作为临时规避，但 Issue 中未确认可用版本号，提问者询问的 2.23 也没有得到确认回复，因此该做法不保证有效。
4. 不要通过重写 Agent 或修改 FunctionAgent 用法来绕过报错，问题不在用户代码层面。

验证方法

在升级后的环境中，用与 Issue 相同的调用方式重新运行 await workflow.run(user_msg="What is 20+(2*4)?")，若不再抛出 TypeError: cannot use 'weakref.ReferenceType' as a dict key，并且能正常返回执行结果，即说明该问题已解决。若仍报同样的错，需再次核对 llama-index-core 实际生效版本是否已更新到 0.14.25 以上。

参考来源

run-llama/llama_index #23131

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。