Deep Agents 与可观测:长期任务、文件产物和可评测轨迹
把规划、文件系统、子代理和长期执行串成证据链,并区分普通日志、trace、数据集与评测实验。
长任务容易失败在模型调用之外:计划写得很好,但某个子任务没有真正完成;文件已经更新,最终回答却引用旧结果;进程重启后状态丢失。Deep Agents把规划、文件上下文、子代理和长期记忆等能力组成harness,但应用仍需定义完成证据、权限与恢复策略。
规划和文件不是装饰
计划应拆成有输入、产物与完成条件的步骤。todo变done只能表示状态字段改变,不能证明产物符合要求;真正完成需要文件、工具回执或评测结果支持。计划变更要记录原因和依赖,避免已经失败的前置任务被后续步骤当成成功。
文件系统为大结果提供外部存储,减少把全文反复放进上下文。虚拟文件、宿主文件和远程持久化后端的寿命与权限不同。写入文件路径并不代表数据持久化成功;进程内字典、临时目录或容器临时层在退出后可能消失。文件应记录版本或摘要,最终答案引用具体产物。
文件权限也不能靠“仅使用工作目录”的提示实现。路径规范化、目录限制、符号链接处理、配额和访问身份由执行环境保证;生成代码若可访问宿主任意路径,虚拟文件抽象本身不能阻止越界。
子代理与长期执行
子代理适合拥有清晰边界的独立任务,父任务提供必要上下文、资源范围、预算与输出契约。结果回传最好包含结论、来源、未完成项和产物位置,而不是只写“完成”。子代理失败时父任务决定重试、降级或停止;共享同一可变状态需要并发控制。
长期执行还需要checkpoint、任务租约、取消传播、幂等动作与超时。审批等待和模型调用耗时是不同状态,重启后应知道下一步可否继续,而不是重新运行整个任务。上下文压缩要保留承诺、限制、操作结果与待办,不能仅保留一段流畅摘要。
当前Deep Agents官方文档区分SDK自托管与Managed Deep Agents等部署选择。托管可以承担部分基础设施,但平台依赖包括状态存储格式、trace传输、身份权限、数据留存和成本。选择时先确认能否导出状态与产物、能否替换模型和工具后端,再评估运维收益。
日志、trace、数据集和实验
普通日志是一串事件文本;trace以run/span和parent关系组织一次请求的因果结构,能定位哪个模型调用导致哪个工具动作。至少记录根请求ID、子任务ID、模型与提示版本、工具参数摘要、耗时、用量、错误和产物引用;敏感内容要脱敏或限制采样。
LangSmith将数据集、评测器和实验用于质量比较。数据集是稳定样例与必要参考信息;评测器依据规则、人工或模型产生判断;实验是某个应用版本在指定数据集和配置上的一次运行。线上trace可经过脱敏与标注转成离线回归用例,但不能把全部生产日志直接当干净测试集。
在线评测观察真实交互,离线评测在固定集上比较版本。两者分布、标签可用性和成本不同。模型裁判可能偏好长答案或同源模型,需校准并保留人工抽样;“trace完整”只证明可追踪,不等于答案正确。
跟做:构造可关联产物,不伪造质量评分
保存 deep_trace.py 并用Python 3.11+运行 python deep_trace.py。这是内存机制模型,没有Deep Agents或LangSmith服务调用。citation_present只检查引用标记,trace_linked只检查关联字段,不是事实正确率或真实Agent能力评分。
"""深层任务与轨迹的内存夹具,不是Deep Agents或LangSmith SDK。"""
from pathlib import PurePosixPath
def safe_virtual_path(name):
path = PurePosixPath(name)
if path.is_absolute() or '..' in path.parts or '\\' in name or ':' in name:
raise ValueError('outside virtual workspace')
return str(path)
def run(case_id):
files, spans = {}, []
spans.append({'id': 'r1', 'parent': None, 'kind': 'run', 'case': case_id})
plan = [{'id': 'p1', 'status': 'doing'}, {'id': 'p2', 'status': 'todo'}]
files[safe_virtual_path('research/evidence.txt')] = 'doc-1: 7天'
spans.append({'id': 's1', 'parent': 'r1', 'kind': 'subagent', 'artifact': 'research/evidence.txt'})
plan[0]['status'], plan[1]['status'] = 'done', 'doing'
answer = '7天内申请 [doc-1]'
spans.append({'id': 's2', 'parent': 'r1', 'kind': 'answer', 'evidence_span': 's1'})
plan[1]['status'] = 'done'
return {'answer': answer, 'spans': spans, 'files': files, 'plan': plan}
def evaluate(result, expected_source):
return {'citation_present': f'[{expected_source}]' in result['answer'],
'trace_linked': any(s.get('evidence_span') == 's1' for s in result['spans'])}
if __name__ == '__main__':
result = run('case-001')
print('plan:', result['plan'])
print('trace:', [(s['id'], s['parent']) for s in result['spans']])
print('evaluation:', evaluate(result, 'doc-1'))
try:
safe_virtual_path('../secrets')
except ValueError as error:
print(str(error))实际输出:
plan: [{'id': 'p1', 'status': 'done'}, {'id': 'p2', 'status': 'done'}]
trace: [('r1', None), ('s1', 'r1'), ('s2', 'r1')]
evaluation: {'citation_present': True, 'trace_linked': True}
outside virtual workspace根r1包含子任务s1和回答s2,s2明确引用证据span。case-001使它能关联到固定样例。路径检查拒绝父目录逃逸;因为没有真实磁盘操作,该检查不处理符号链接,也不构成操作系统沙箱。
把期望来源改成doc-2,citation_present变false,但trace结构仍完整;去掉答案中的引用也不影响文件存在。这说明产物、轨迹和质量检查需要不同信号,不能压成一个“执行成功”。
如何排查长期任务
最终答案没用新资料,核对文件摘要、读取span与上下文版本;计划全部done但缺产物,检查状态转换是否绑定验收;取消后子任务继续,检查父子任务管理与远端取消能力;评测涨分却线上变差,检查数据泄漏、样例分布和裁判偏差。
机制与产品范围以 Deep Agents概览 和 LangSmith评测说明 为依据。本文未上传业务数据到平台,也未实测托管部署与长期恢复。
评估平台依赖可做一次退出演练:导出一个任务的状态、文件摘要、span父子ID和数据集样例,换本地存储重新读取,核对是否仍能定位同一产物与失败步骤。若导出只有最终文字而没有工具回执,就只能迁移展示结果,不能声称可恢复执行。托管服务减少运维工作,但这类导出缺口会提高迁移成本;发现字段缺失时先补应用侧独立账本或限制长期任务依赖,再接入新平台。该演练是建议的验收情境,本文未执行平台迁移。
课后练习展开习题收起习题
先独立作答,再展开参考思路。检查自己的解释是否包含机制、条件和反例。
框架日志和可评测轨迹差在哪?
参考思路与常见误区
trace关联根run、子span、工具、版本和产物,数据集case与实验可追溯同一次行为;散落日志难复原因果。
常见误区:有很多日志就等于可观测完备。
todo标done为什么不证明任务完成?
参考思路与常见误区
状态字段需要产物、工具回执或验收证据支持;计划完成与业务质量是独立信号。
常见误区:模型自己宣布完成即可。
文件系统抽象自动保证持久化与隔离吗?
参考思路与常见误区
不保证;虚拟内存、临时目录与持久后端寿命不同,路径、符号链接、配额和权限由环境控制。
常见误区:写文件工具天然是安全持久存储。
线上trace怎样变成回归数据?
参考思路与常见误区
脱敏、去重并补充必要参考和标签,绑定稳定case ID与评测标准,在固定配置下运行实验。
常见误区:把全部生产日志直接当干净测试集。
子代理失败时父任务应如何处理?
参考思路与常见误区
根据产物契约和剩余预算选择重试、降级或停止,明确未完成项,取消传播并避免重复副作用。
常见误区:只读取子代理的完成一句话。