HelloAgents ToolResponse 工具响应协议为什么字符串返回值正在拖累你的智能体【免费下载链接】HelloAgentsA agent framework based on the tutorial hello-agents项目地址: https://gitcode.com/gh_mirrors/he/HelloAgents在构建 AI 智能体Agent时一个容易被忽视的瓶颈是工具响应协议工具执行完把结果丢回给大模型时到底该返回什么HelloAgents 智能体框架给出的答案是一套标准化的ToolResponse 工具响应协议——它用「状态 文本 结构化数据」取代了模糊的纯字符串返回让智能体不再靠猜来理解工具结果。字符串返回值到底卡住了智能体的哪里在传统写法里工具执行完毕通常就返回一行字符串例如计算结果: 5或错误: 文件不存在。看着没什么问题但在真实的智能体循环中这类字符串返回值会引发四个连锁问题问题后果❌ 状态不明确成功、失败还是部分完成只能靠猜❌ 错误难以解析想用代码判断错误类型只能写脆弱的正则匹配❌ 无法携带结构化数据文件内容、结果数量等只能塞进文本里❌ 智能体盲飞模型无法确切知道工具是否真正执行成功说白了字符串把发生了什么和意味着什么混在了一起而智能体最需要的恰恰是后者。一次看懂 ToolResponse 协议的核心结构HelloAgents 在 hello_agents/tools/response.py 中定义了ToolResponse数据类它把一次工具调用拆成 6 个各司其职的字段字段作用谁在消费status执行状态SUCCESS/PARTIAL/ERROR智能体、熔断器text给大模型阅读的格式化文本LLMdata结构化数据载荷结果值、数量等智能体逻辑error_info错误码 错误消息仅 ERROR 时错误处理层stats运行统计耗时、token 数等可观测性系统context上下文信息入参、工具名等日志追踪三种状态的设计非常克制SUCCESS任务完全按预期执行PARTIAL结果可用但有折扣——比如搜索结果太多被截断、大数改用科学计数法ERROR没有有效结果是致命错误。这个三分法恰好覆盖了智能体在真实任务中最常遇到的三种局面也避免了把一切非失败都当成功的传统陷阱。三个工厂方法5 行代码造出标准响应协议把创建响应封装成了三个类方法见 hello_agents/tools/response.py日常开发基本不用手写构造参数# 成功 ToolResponse.success(text文件读取成功, data{content: Hello, size: 5}) # 部分成功 ToolResponse.partial(text搜索结果前 100 条, data{total: 500}) # 错误 ToolResponse.error(codeToolErrorCode.NOT_FOUND, message文件 config.py 不存在)完整协议说明可参考官方文档docs/tool-response-protocol.md。15 个标准错误码让每个失败都对号入座光有状态还不够ERROR状态下的错误码才是机器可判断的关键。HelloAgents 在 hello_agents/tools/errors.py 中定义了 15 个标准错误码按类别一目了然资源类NOT_FOUND资源不存在、PERMISSION_DENIED权限不足、IS_DIRECTORY、BINARY_FILE参数类INVALID_PARAM参数无效、INVALID_FORMAT格式错误执行类EXECUTION_ERROR、TIMEOUT、INTERNAL_ERROR状态类CONFLICT乐观锁冲突、CIRCUIT_OPEN熔断器开启网络类NETWORK_ERROR、API_ERROR、RATE_LIMIT错误码的价值不止于分类好看。它让上层系统可以确定性地做出决策——例如熔断器在 hello_agents/tools/circuit_breaker.py 中只需判断response.status ToolStatus.ERROR就记录一次失败连续失败达到阈值即打开熔断整个过程不需要解析任何一行文字。从字符串工具迁移到 ToolResponse 的三步走已有工具迁移到协议成本极低核心只有三步改返回类型run()的返回值从str改为ToolResponse基类签名见 hello_agents/tools/base.py成功路径原来return 计算结果: 5的地方改成ToolResponse.success(text..., data{result: 5})错误路径原来return 错误: 文件不存在的地方改成ToolResponse.error(code..., message...)并尽量选用最精确的错误码。框架对旧代码也很友好通过ToolRegistry注册的普通函数会被自动包装成ToolResponse自动计时、填充 context异常则自动转为EXECUTION_ERROR错误响应包装逻辑见 hello_agents/tools/registry.py。也就是说哪怕你写的是最简单的函数工具智能体拿到的依然是标准结构。智能体收到 ToolResponse 后会做什么在 Agent 核心循环hello_agents/core/agent.py中status字段直接驱动分支处理SUCCESS→ 将text交给模型继续推进任务PARTIAL→ 额外提示模型结果不完整避免它把截断结果当成全部ERROR→ 把错误码 消息明确注入上下文模型知道该换策略而不是原地重试。配合基类的run_with_timing()hello_agents/tools/base.py每次执行还会自动补上time_ms耗时统计和入参上下文未捕获的异常也会被兜底转成标准错误响应——工具系统从此永远不会把裸异常抛给智能体。写工具时的三条最佳实践错误码要精确能用PERMISSION_DENIED就别用EXECUTION_ERROR错误码是给机器读的越精确决策越准data 载荷要丰富别只返回找到 3 个文件把文件列表、数量放进data智能体才能做后续程序化处理善用 stats 统计填入耗时、调用次数等指标可观测性系统TraceLogger就能直接生成性能报表。想动手体验的话直接运行示例 examples/tool_response_demo.py——它用一个演示计算器依次触发了 SUCCESS、PARTIAL、ERROR 三种状态是理解这套智能体工具响应协议最快的方式回归测试在 tests/test_tool_response_protocol.py。小结一次返回的规范换来全链路的确定性ToolResponse 协议做的事情看似只是换个返回类型但它实际重塑了整条链路工具用三种状态 标准错误码自证结果注册表统一计时与兜底熔断器按状态计数做保护智能体按状态分支决策。当每个环节都依赖同一个结构化契约时你的智能体就从凭感觉干活升级为按证据干活——这正是生产级多智能体框架与玩具 Demo 的分水岭。【免费下载链接】HelloAgentsA agent framework based on the tutorial hello-agents项目地址: https://gitcode.com/gh_mirrors/he/HelloAgents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
HelloAgents ToolResponse 工具响应协议：为什么字符串返回值正在拖累你的智能体
HelloAgents ToolResponse 工具响应协议为什么字符串返回值正在拖累你的智能体【免费下载链接】HelloAgentsA agent framework based on the tutorial hello-agents项目地址: https://gitcode.com/gh_mirrors/he/HelloAgents在构建 AI 智能体Agent时一个容易被忽视的瓶颈是工具响应协议工具执行完把结果丢回给大模型时到底该返回什么HelloAgents 智能体框架给出的答案是一套标准化的ToolResponse 工具响应协议——它用「状态 文本 结构化数据」取代了模糊的纯字符串返回让智能体不再靠猜来理解工具结果。字符串返回值到底卡住了智能体的哪里在传统写法里工具执行完毕通常就返回一行字符串例如计算结果: 5或错误: 文件不存在。看着没什么问题但在真实的智能体循环中这类字符串返回值会引发四个连锁问题问题后果❌ 状态不明确成功、失败还是部分完成只能靠猜❌ 错误难以解析想用代码判断错误类型只能写脆弱的正则匹配❌ 无法携带结构化数据文件内容、结果数量等只能塞进文本里❌ 智能体盲飞模型无法确切知道工具是否真正执行成功说白了字符串把发生了什么和意味着什么混在了一起而智能体最需要的恰恰是后者。一次看懂 ToolResponse 协议的核心结构HelloAgents 在 hello_agents/tools/response.py 中定义了ToolResponse数据类它把一次工具调用拆成 6 个各司其职的字段字段作用谁在消费status执行状态SUCCESS/PARTIAL/ERROR智能体、熔断器text给大模型阅读的格式化文本LLMdata结构化数据载荷结果值、数量等智能体逻辑error_info错误码 错误消息仅 ERROR 时错误处理层stats运行统计耗时、token 数等可观测性系统context上下文信息入参、工具名等日志追踪三种状态的设计非常克制SUCCESS任务完全按预期执行PARTIAL结果可用但有折扣——比如搜索结果太多被截断、大数改用科学计数法ERROR没有有效结果是致命错误。这个三分法恰好覆盖了智能体在真实任务中最常遇到的三种局面也避免了把一切非失败都当成功的传统陷阱。三个工厂方法5 行代码造出标准响应协议把创建响应封装成了三个类方法见 hello_agents/tools/response.py日常开发基本不用手写构造参数# 成功 ToolResponse.success(text文件读取成功, data{content: Hello, size: 5}) # 部分成功 ToolResponse.partial(text搜索结果前 100 条, data{total: 500}) # 错误 ToolResponse.error(codeToolErrorCode.NOT_FOUND, message文件 config.py 不存在)完整协议说明可参考官方文档docs/tool-response-protocol.md。15 个标准错误码让每个失败都对号入座光有状态还不够ERROR状态下的错误码才是机器可判断的关键。HelloAgents 在 hello_agents/tools/errors.py 中定义了 15 个标准错误码按类别一目了然资源类NOT_FOUND资源不存在、PERMISSION_DENIED权限不足、IS_DIRECTORY、BINARY_FILE参数类INVALID_PARAM参数无效、INVALID_FORMAT格式错误执行类EXECUTION_ERROR、TIMEOUT、INTERNAL_ERROR状态类CONFLICT乐观锁冲突、CIRCUIT_OPEN熔断器开启网络类NETWORK_ERROR、API_ERROR、RATE_LIMIT错误码的价值不止于分类好看。它让上层系统可以确定性地做出决策——例如熔断器在 hello_agents/tools/circuit_breaker.py 中只需判断response.status ToolStatus.ERROR就记录一次失败连续失败达到阈值即打开熔断整个过程不需要解析任何一行文字。从字符串工具迁移到 ToolResponse 的三步走已有工具迁移到协议成本极低核心只有三步改返回类型run()的返回值从str改为ToolResponse基类签名见 hello_agents/tools/base.py成功路径原来return 计算结果: 5的地方改成ToolResponse.success(text..., data{result: 5})错误路径原来return 错误: 文件不存在的地方改成ToolResponse.error(code..., message...)并尽量选用最精确的错误码。框架对旧代码也很友好通过ToolRegistry注册的普通函数会被自动包装成ToolResponse自动计时、填充 context异常则自动转为EXECUTION_ERROR错误响应包装逻辑见 hello_agents/tools/registry.py。也就是说哪怕你写的是最简单的函数工具智能体拿到的依然是标准结构。智能体收到 ToolResponse 后会做什么在 Agent 核心循环hello_agents/core/agent.py中status字段直接驱动分支处理SUCCESS→ 将text交给模型继续推进任务PARTIAL→ 额外提示模型结果不完整避免它把截断结果当成全部ERROR→ 把错误码 消息明确注入上下文模型知道该换策略而不是原地重试。配合基类的run_with_timing()hello_agents/tools/base.py每次执行还会自动补上time_ms耗时统计和入参上下文未捕获的异常也会被兜底转成标准错误响应——工具系统从此永远不会把裸异常抛给智能体。写工具时的三条最佳实践错误码要精确能用PERMISSION_DENIED就别用EXECUTION_ERROR错误码是给机器读的越精确决策越准data 载荷要丰富别只返回找到 3 个文件把文件列表、数量放进data智能体才能做后续程序化处理善用 stats 统计填入耗时、调用次数等指标可观测性系统TraceLogger就能直接生成性能报表。想动手体验的话直接运行示例 examples/tool_response_demo.py——它用一个演示计算器依次触发了 SUCCESS、PARTIAL、ERROR 三种状态是理解这套智能体工具响应协议最快的方式回归测试在 tests/test_tool_response_protocol.py。小结一次返回的规范换来全链路的确定性ToolResponse 协议做的事情看似只是换个返回类型但它实际重塑了整条链路工具用三种状态 标准错误码自证结果注册表统一计时与兜底熔断器按状态计数做保护智能体按状态分支决策。当每个环节都依赖同一个结构化契约时你的智能体就从凭感觉干活升级为按证据干活——这正是生产级多智能体框架与玩具 Demo 的分水岭。【免费下载链接】HelloAgentsA agent framework based on the tutorial hello-agents项目地址: https://gitcode.com/gh_mirrors/he/HelloAgents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考