DeepSeek Agent Harness 2026终极指南 - 第9章第44节 工具返回值设计结构化与token经济学第40-43节我们做了文件、bash、检索、联网四件套Agent已经能读改写代码、跑命令、找代码、查文档。但工具返回值的设计还有很多讲究——返回太多占上下文返回太少模型看不懂。这节讲工具返回值设计结构化格式、token经济学、返回值如何影响模型决策。这是工具开发的最后一公里。本文导航为什么返回值设计很重要结构化返回值成功/失败统一格式超大输出截断策略返回值如何影响模型决策实证对比好返回值 vs 坏返回值小结为什么返回值设计很重要工具返回值是模型理解工具执行结果的唯一途径。设计不好模型会误解结果返回成功模型不知道成功了什么浪费token返回1万字模型看不完上下文爆炸决策错误返回信息不全模型做出错误判断好的返回值设计结构化成功/失败统一格式模型容易解析精简只返回必要信息节省token明确告诉模型发生了什么、下一步该做什么结构化返回值成功/失败统一格式很多工具返回的是纯字符串如成功、“失败”。模型很难判断是成功还是失败。解决方案统一结构化格式。tooldefsome_tool(param:str)-str:工具描述try:# 执行逻辑resultdo_something(param)# 成功返回结构化信息returnf成功 - 操作{param}- 结果{result}- 下一步可以继续执行其他操作exceptExceptionase:# 失败返回错误信息和建议returnf失败 - 操作{param}- 错误{str(e)}- 建议检查参数是否正确或尝试其他方法关键点明确标识成功/失败开头写成功“或失败”包含关键信息操作、结果/错误、下一步建议格式化输出用换行、列表方便模型解析超大输出截断策略有些工具返回大量数据read_file读大文件grep搜索大量匹配web_fetch抓取长网页如果不截断会占满上下文窗口。截断策略MAX_OUTPUT4000# 最大输出字符数deftruncate_output(output:str,max_length:intMAX_OUTPUT)-str:截断超长输出iflen(output)max_length:returnoutput# 截断并提示truncatedoutput[:max_length]returnf{truncated}\n\n[输出已截断共{len(output)}字符已显示前{max_length}字符]关键点默认4000字符约1000-2000 token对模型够用提示总长度让模型知道还有多少内容没看到可选参数允许调用方指定max_length返回值如何影响模型决策返回值不仅告诉模型发生了什么还影响模型下一步做什么。案例1文件读取坏返回值def add(a, b): return a b模型不知道这是哪个文件、第几行。好返回值文件test_math.py 行号1-3 内容 1: def add(a, b): 2: return a b 3: 下一步可以用edit_file修改这个函数模型知道这是test_math.py的1-3行可以用edit_file修改案例2命令执行坏返回值1 passed in 0.01s模型不知道命令是否成功。好返回值命令pytest test_math.py -v 状态成功返回码 0 输出 1 passed in 0.01s 下一步测试通过可以继续开发其他功能模型知道命令成功返回码0测试通过可以继续开发实证对比好返回值 vs 坏返回值我们做一个实验让Agent修改一个有bug的函数。实验设置test_math.py里有个bugadd(0, 0)应该返回0但测试失败让Agent修复bug坏返回值版本工具返回test_math.py::test_add FAILED AssertionError: assert 1 0Agent反应看到FAILED知道测试失败看到assert 1 0不知道是哪行代码错了可能盲目修改代码好返回值版本工具返回命令pytest test_math.py -v 状态失败返回码 1 输出 test_math.py::test_add FAILED 失败详情 文件test_math.py 函数test_add 行号8 错误AssertionError: assert add(0, 0) 0 实际值1 期望值0 建议检查add函数在a0, b0时的返回值Agent反应知道是test_math.py第8行知道是add(0, 0)返回了1而不是0精准定位bug快速修复结论好返回值让Agent决策更准确、更高效。小结返回值设计是工具开发的最后一公里设计不好模型误解、浪费token、决策错误。结构化返回值成功/失败统一格式包含操作、结果/错误、下一步建议。超大输出截断默认4000字符提示总长度允许调用方指定max_length。返回值影响模型决策好返回值让模型精准定位问题坏返回值让模型盲目猜测。实证对比好返回值包含文件、行号、错误详情、建议坏返回值只有简单错误信息。设计原则明确、精简、结构化、可操作。DeepPilot v0.4工具返回值设计完成——工具开发从能用升级到好用。下节预告工具返回值设计好了但还有一个问题——模型怎么知道该用哪个工具你让Agent查一下天气它怎么知道要用get_weather而不是web_search下一节讲工具描述工程怎么写工具描述让模型用对工具。这是工具开发的提示词工程。如果觉得本文对你有帮助欢迎点赞、收藏、关注三连本系列持续更新中关注不迷路~