Agno 的 Agentic Framework 在处理工具调用结果时，严格要求所有自定义工具函数的返回值为 str 类型；若返回 int、float 等原生数值类型，将触发 Pydantic 的 ValidationError，导致消息解析失败。
agno 的 agentic framework 在处理工具调用结果时，严格要求所有自定义工具函数的返回值为 `str` 类型；若返回 `int`、`float` 等原生数值类型，将触发 pydantic 的 `validationerror`，导致消息解析失败。
在使用 Agno 构建智能体（Agent）时，工具（Tool）并非仅用于执行逻辑——其返回值会作为上下文消息的一部分，被序列化并注入模型输入流。Agno 内部基于 Pydantic v2 对 Message 结构进行强校验，其中 content 字段明确约束为 str | list[str] 类型（即字符串或字符串列表）。当你的 add(2, 5) 返回整数 7，框架尝试将其赋值给 message.content 时，Pydantic 会拒绝 int 类型，抛出类似以下错误：
content.list[any] Input should be a valid list content.str Input should be a valid string
这并非代码逻辑错误，而是框架协议层面的设计约定：所有工具输出必须是可直接嵌入对话上下文的字符串，便于 LLM 理解、引用与链式推理。
✅ 正确做法：统一将工具函数的返回类型标注为 str，并在函数体内显式调用 str() 转换：
def add(x: int, y: int) -> str:
"""Add two integers and return result as string."""
return str(x + y)
def divide(x: int, y: int) -> str:
"""Divide two integers; handles zero-division defensively."""
if y == 0:
return "Error: Division by zero"
return str(x / y)
def generate_random_number() -> str:
"""Generate random integer between 1–10 and return as string."""
import random
return str(random.randint(1, 10))
⚠️ 注意事项：
-
不要依赖类型提示自动转换：Python 类型注解（如
-> str）仅作提示，不改变运行时行为；务必在函数体中显式return str(...)。 -
避免空值或
None返回：None无法转为字符串且会引发新错误，建议兜底返回"null"或描述性字符串（如"No result available"）。 -
保持文档一致性：更新 docstring 中的
Returns描述，明确标注返回str，避免团队协作误解。 -
调试建议：启用
debug_mode=True和show_tool_calls=True，可清晰看到工具调用输入/输出及消息组装过程，快速定位类型问题。
总结来说，Agno 并非限制功能表达力，而是通过强制字符串化确保工具输出与 LLM 输入格式无缝对齐。这一设计简化了消息编排逻辑，提升了多步工具链（如“加 → 乘 → 除 → 随机数”）的稳定性与可观测性。遵循该规范，即可安全构建可复用、可调试、可扩展的 Agno 智能体。
