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

快速结论：这个报错通常出现在 LlamaIndex 的 FunctionAgent / Workflow 示例运行时，`workflow.run(…)` 阶段内部序列化缓存尝试把 workflow 对象当作 WeakKeyDictionary 的键，而 `FunctionAgent` 不可哈希，于是抛出 `TypeError: cannot use ‘weakref.ReferenceType’ as a dict key (unhashable type: ‘FunctionAgent’)`。优先排查并升级或降级 `llama-index-core` / `llama-index-workflows` 的版本组合。

适用环境：Issue 中确认使用 LlamaIndex 0.14.24（llama-index==0.14.24、llama-index-core==0.14.24）、llama-index-workflows==2.24.0、llama-index-llms-openai-like==0.8.0，运行在 Python 3.14（Windows，路径为 AppData\Local\Python\pythoncore-3.14-64）；用户以 OpenAILike 方式调用 FunctionAgent 示例代码。

最快修复方案：升级到 v0.14.25 的 llama-index(-core)，Issue 评论中明确说明该版本修复了此问题。

注意事项：该结论来自 Issue 评论，未附带完整的验证复现记录；若无法升级到 0.14.25，维护者也建议降级 `llama-index-workflows`（评论中未给出确认可用的具体版本号，用户曾询问 2.23 是否可行，未获明确答复）。降级或混用版本时需注意 llama-index-core 与 llama-index-workflows 之间的兼容性。

问题场景

用户按照 LlamaIndex 官方文档的 FunctionAgent 示例编写代码，仅把 LLM 换成 OpenAILike 方式，其余代码相同。在执行 response = await workflow.run(user_msg="What is 20+(2*4)?") 这一步时触发报错，问题发生在 workflow 运行阶段，而不是模型调用本身。

报错原文

Traceback:
  File ".venv\Lib\site-packages\workflows\runtime\types\plugin.py", line 603, in Runtime._compose_serializer(self, workflow, serializer, *additional_types)
    597 def _compose_serializer(
    ...
--> 603     cached = self._serializer_cache.get(workflow)
    604     if cached is not None and cached[0] == additional_types:

  File "~\AppData\Local\Python\pythoncore-3.14-64\Lib\weakref.py", line 357, in WeakKeyDictionary.get(self, key, default)
    356 def get(self, key, default=None):
--> 357     return self.data.get(ref(key),default)

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

原因分析

可能原因是该版本的 workflows 运行时在 _compose_serializer 中使用了 WeakKeyDictionary 做序列化器缓存，缓存以 workflow 对象（此处为 FunctionAgent）作为键。当该对象不可哈希时，WeakKeyDictionary 内部构造 weakref 引用并作为 dict key，就会抛出上述 TypeError。维护者确认这是新版 workflows 中需要打补丁的问题，并在 llama-index(-core) v0.14.25 中修复，因此可判断为版本缺陷而非用户代码写法错误。

环境排查

确认 llama-index 与 llama-index-core 的版本，Issue 中为 0.14.24。
确认 llama-index-workflows 版本，Issue 中为 2.24.0。
确认 LLM 相关包版本：llama-index-llms-openai-like==0.8.0、llama-index-llms-openai==0.7.10、llama-index-llms-dashscope==0.7.0。
确认其他依赖：llama-index-embeddings-openai==0.6.0、llama-index-instrumentation==0.6.0。
确认 Python 版本与运行环境（Issue 中为 Python 3.14、Windows）。

解决步骤

先确认当前 llama-index(-core) 与 llama-index-workflows 的实际版本，判断是否处于 Issue 描述的 0.14.24 / 2.24.0 组合。
优先尝试将 llama-index(-core) 升级到 v0.14.25，评论中明确该版本修复了此问题。
如果暂时无法升级到 0.14.25，可按维护者建议将 llama-index-workflows 降级（评论中未给出经确认的具体版本，用户询问的 2.23 未获明确答复，降级前建议先做小范围验证）。
改动版本后，在干净环境中重新运行 FunctionAgent 示例，重点观察 workflow.run(...) 是否仍进入 _compose_serializer 并报同样的 TypeError。
若升级 / 降级后仍报错，收集完整版本清单与 Traceback，回到 Issue 补充信息。

验证方法

重新执行原本报错的 workflow.run(user_msg="What is 20+(2*4)?") 调用，如果不出现 TypeError: cannot use 'weakref.ReferenceType' as a dict key (unhashable type: 'FunctionAgent')，并能正常打印 response，即说明版本修复已生效。