在多代理系统中，子代理负责执行由主代理分配的各种任务。由于子代理的执行环境具有不确定性——网络延迟、外部API响应缓慢、计算资源争用等因素都可能导致任务执行时间超出预期。超时控制机制正是在这种背景下应运而生，它是保障整个系统稳定运行的关键防线。
防止子代理无限制等待是超时控制的首要目标。当子代理被分配一个任务后，如果没有超时机制，任务可能因为外部依赖阻塞而无限期地占用系统资源。这不仅浪费了宝贵的计算资源，还可能导致整个代理链路的级联延迟，最终影响用户体验。
及时释放资源给其他任务是超时控制的另一个重要作用。在并发场景下，多个子代理共享有限的系统资源（如线程池、数据库连接、内存等）。如果一个子代理长时间占用资源而不释放，其他等待执行的任务就会被阻塞，形成资源饥饿。通过设定合理的超时阈值，系统可以强制回收异常子代理占用的资源，将其重新分配给正常的任务流程。
长时间无反馈会令用户感到困惑甚至沮丧。用户向系统发起请求后，如果子代理在后台无限制地运行而不返回任何进度信息，用户无法判断系统是正在正常处理还是已经卡死。超时控制结合进度报告机制，可以在任务执行超时后及时向用户返回部分结果或友好提示，避免用户因为等待过久而放弃使用。
要点总结： 超时控制是多代理系统的必备机制，它解决了资源泄漏、系统稳定性、用户体验三大核心问题。没有超时控制的系统就像没有保险丝的电闸，随时可能因为局部故障引发全局崩溃。
TaskOutput是子代理任务执行结果的标准封装结构，其中的timeout参数是超时控制的核心配置项。理解timeout参数的含义和使用方法，是正确实现超时控制的前提。
参数说明： timeout参数定义了子代理任务的最大等待时间，单位为毫秒（ms）。当一个子代理任务被派发后，主代理会启动一个计时器，在timeout指定的时间范围内等待子代理返回结果。如果在规定时间内子代理没有返回结果，系统将触发超时处理流程。
默认值： 框架通常将timeout的默认值设置为30000ms（即30秒）。这个默认值适用于大多数中等复杂度的任务，但在实际应用中，开发人员应根据任务的具体特性进行调整。过短的timeout会导致正常任务被误判为超时，过长的timeout则会削弱超时控制的意义。
超过时间抛出TimeoutError。当timeout被触发时，系统会生成TimeoutError异常，该异常包含了超时任务的标识信息、实际等待时长、已获取的部分结果等上下文数据。主代理可以捕获这个异常并根据业务逻辑决定后续处理策略。TimeoutError不应被视为普通的程序错误，而应被理解为系统流程中的一个正常分支。
合理设置timeout的策略：
不同的任务类型具有不同的执行特征，采用统一的超时策略是不合理的。合理的做法是根据任务的预期执行时间、资源消耗、重要性等因素，为任务分配合适的超时策略。
快速任务的特点是执行时间短、确定性高、资源消耗小。这类任务包括简单的数据查询、本地缓存读取、基础计算等。对于快速任务，建议采用同步等待策略：主代理派发任务后直接阻塞等待子代理返回结果，如果超过timeout则立即抛出异常。
慢速任务通常涉及外部API调用、大规模数据处理、文件IO等操作。这类任务的执行时间波动较大，可能因为网络状况或数据量的不同而产生数倍的差异。对于慢速任务，建议采用异步加轮询的策略：主代理派发任务后不阻塞等待，而是定期检查任务状态，同时允许主代理在等待期间处理其他工作。
未知任务的执行时间无法预先估计，可能是几秒钟也可能是几个小时。这类任务包括用户自定义脚本执行、AI模型推理、大规模文件扫描等。对于未知任务，建议采用"最大超时+定期检查进度"的组合策略：设置一个绝对的最大超时时间防止系统被无限占用，同时要求子代理定期报告进度，主代理根据进度信息判断任务是否仍在正常进行。
| 任务类型 | 预期耗时 | 推荐策略 | 推荐Timeout |
|---|---|---|---|
| 快速任务 | < 10s | 同步等待 | 5s - 10s |
| 慢速任务 | 30s - 5min | 异步+轮询 | 60s - 300s |
| 未知任务 | 不确定 | 最大超时+进度检查 | 300s+（可配置） |
当子代理任务超时后，系统需要根据业务场景选择合适的处理策略。不同的策略对应不同的用户体验和系统行为，选择正确的策略至关重要。
终止是最直接的超时处理策略。当超时发生后，系统强制停止子代理的执行，回收其占用的系统资源，并标记任务状态为"已终止"。终止策略适用于那些不要求必须完成的任务，或者超时后再继续执行已经没有意义（如实时查询类任务）。终止后系统应记录超时日志，分析超时原因，为后续优化提供数据支持。
重试策略适用于那些偶发性超时的任务。许多超时是因为暂时的网络波动或资源争用导致的，稍后重试可能就会成功。重试策略包括立即重试和延迟重试两种模式：立即重试适用于预期短时间内故障会恢复的场景，延迟重试（如等待几秒后再试）则适用于需要短暂恢复时间的场景。需要注意的是，重试次数应该有限制，避免形成无限重试的死循环。
降级策略是指在超时发生后，系统不再等待完整结果，而是使用已有的部分结果或默认值继续执行。降级的核心思想是"总比没有好"。例如，在查询用户信息时，如果查询详细资料的任务超时，可以先返回用户的基本信息，详细资料标记为"加载中"。降级策略在超时控制中应用广泛，它能够在异常情况下维持系统的基本可用性。
无论采用哪种超时处理策略，都应该将超时事件和当前可用的部分结果反馈给用户。透明的沟通能够提升用户对系统的信任度。建议的做法是：在返回结果中包含一个状态字段，清晰标识哪些数据是完整的、哪些是超时后降级使用的，并提示用户如有需要可以重新发起请求获取完整结果。
核心原则： 超时不是失败，而是一个状态分支。系统应该优雅地处理超时，始终保持对外输出的确定性和可用性。终止、重试、降级三种策略可以根据业务场景组合使用，形成完整的超时处理链路。
长任务的心跳机制是超时控制的进阶形态。对于执行时间较长的任务，简单地在固定时间后触发超时是不够的——我们需要一种机制来持续监控子代理的健康状态，在任务真正异常时及时干预，在任务正常运行时避免误判。
子代理在执行长任务期间，应按照约定的时间间隔（如每5秒）向主代理发送进度报告。进度报告应包括：任务标识、当前进度百分比、已执行时间、预计剩余时间、当前阶段描述等信息。主代理接收进度报告后，会重置该子代理的心跳计时器，确认子代理仍在正常工作。
主代理维护一个心跳超时检测器，定期检查所有活跃子代理的最后心跳时间。如果一个子代理在"心跳超时阈值"（通常设置为心跳间隔的3倍）内没有发送任何进度报告，主代理就会怀疑该子代理可能已经失联。这时主代理可以先发送一个探活请求，确认子代理的状态。如果探活也失败，则正式判定子代理超时失联。
当子代理在心跳超时阈值内没有任何响应时，系统会执行"超时断开"操作。这个操作包括：标记子代理为"失联"状态、记录最后已知进度、释放子代理占用的所有资源（内存、文件句柄、网络连接等）、通知主代理该子代理已断开。超时断开是一种保护性措施，防止失联子代理的资源泄漏导致系统稳定性下降。
在某些场景中，子代理可能在短暂失联后恢复通信（如网络闪断后重连）。系统应该支持断线重连机制：当子代理重新发送心跳后，主代理识别出这是一个之前标记为失联的子代理，检查其任务状态和进度，如果任务仍在有效期内，则允许其继续执行，并从断点处恢复工作。这种机制对于执行时间极长的任务尤为重要，避免了因短暂故障而导致整个任务重新执行。
心跳机制的价值： 心跳机制将超时控制从"一刀切的静态超时"升级为"动态的健康监控"。它不仅告诉系统"任务是否超时"，还能回答"任务现在进行到哪一步了"、"任务是否还在正常工作"、"如果中断了，从哪里可以恢复"等更深层次的问题。心跳机制是实现高可靠性多代理系统的基础设施。