你的AI代理还在写日志？该换合同了

调试生产环境的LLM代理时，你打开日志，看到代理返回了什么，看到它失败了。但你不知道故障发生前系统的状态——什么数据进去了，前置条件是否有效，三步之前哪个策略被悄悄违反了。

日志告诉你发生了什么。它不告诉你什么被允许发生。

这是每个跑代理的团队都会遇到的坑。大多数人用临时断言、仔细记录日志，然后祈祷。我们想要更系统的东西。

于是我们做了DEED。

传统服务出问题时，你看请求和响应，失败边界清晰。但LLM代理管道不同：每一步都在转换共享状态对象。第三步的代理操作的是前两步塑造的输出。等你看到失败，系统已经历多个状态——没有一个被验证过。

标准修复是加断言：

result = await agent.run(state)
assert result.get("score") is not None
assert result.get("enriched") == True

这能跑，直到跑不动。断言散落在执行器代码里。它们不解释条件为何不满足。不写死信队列。不检查点状态让你从故障点重放。而且不看你的Python的人就看不见它们。

DEED在管道定义和代理执行器之间加了一层声明式合同。

每个代理有一份合同：运行前必须为真的是什么（前置条件），运行后必须为真的是什么（后置条件）。每个代理还有策略：允许什么动作，什么有上限，什么明确禁止。

DEED的.dd格式长这样：

agent score_agent
description "ICP scoring agent — evaluates company fit 0.0-1.0"
capabilities ["score_company"]
policy
cap budget_tokens <= 3000
allow score_company if enriched
contract score_contract
pre enriched
post scored
observe
trace true

score_agent运行前：运行时检查当前状态里enriched是否为真。不是——步骤被拒绝，状态原样保留，死信队列写入带完整上下文快照的条目。

代理运行后：运行时检查scored现在是否存在。后置条件失败——同样结果，加上如果你用了计量层，自动退积分。

策略在LLM调用前运行。allow score_company if enriched意味着如果前置检查和动作之间enriched变成false——动作执行前就被拦住。

合同住在管道规格旁边，不埋在执行器代码里。

关键设计：合同是声明式的、可观测的、可重放的。声明式意味着你用领域语言写约束，不用Python。可观测意味着每次检查都发出结构化事件。可重放意味着失败时你有完整状态快照，能从任意检查点重启管道。

这不是类型系统。类型检查静态数据结构。合同检查运行时语义：这个代理被允许在这个状态下做这个吗？这个输出满足我们的业务规则吗？

也不是传统单元测试。测试在部署前运行。合同在生产环境每一步都运行。

我们见过团队用DEED catch三类失败：前置条件失败（代理拿到不该拿到的输入）、后置条件失败（代理输出格式不对或违反业务规则）、策略违规（代理试图调用没授权的能力或超预算）。

每类都有相同处理路径：停止管道、保留状态、写审计日志、可选通知或自动回退。

审计日志本身就是产品。代理系统最难调试的不是"为什么失败"，是"为什么当时没失败"——为什么这个输入通过了验证，为什么那个动作被允许。DEED的轨迹给每个决策点完整上下文。

实现上，DEED运行时是语言无关的。合同用.dd定义，编译成可移植表示，嵌入Python/TypeScript/Go的执行器调用轻量运行时。状态是版本化的不可变对象，检查点成本接近零。

计量层是可选但设计时就在一起的。如果你按token或按调用计费，合同违规触发自动退款。把可靠性机制和商业逻辑绑在一起，改变了团队对代理风险的计算方式。

我们内部用DEED跑销售线索评分管道。之前每周花几小时追幽灵故障：代理返回了分数，但分数格式不对，下游系统默默丢弃，两天后才发现。加合同后，这类故障在部署时或运行时被拒，带完整上下文。

最意外的发现：合同让代理行为更可预测，团队反而敢让代理做更多。前置条件明确后，你能把更复杂的决策推给代理，因为你知道边界在哪。

这不是说合同能 catch 所有bug。LLM 本质有随机性，合同不消除不确定性，只是把不确定性框在已知边界里。你 still 需要评估、需要回退策略、需要人在回路。但你知道什么时候该触发这些机制。

日志告诉你历史。合同定义允许的未来。