数据产品：先把业务事实整理好，再让 Agent 做判断

本文是 Agent 工程里的经典架构 系列的一篇。文中的业务场景和代码为讲解设计，产品能力以所链接的官方资料为准。

让 Agent 判断客户是否需要续约提醒，模型很快就能给出建议。但如果 CRM 的联系人已经过期、账单系统的合同状态更新延迟，建议再流畅也可能发给错误的人。很多所谓智能不足的问题，最后会落在输入数据不够可靠上。

Designing Data Products提出从使用场景倒推数据产品，确定边界、领域归属和服务目标，再通过更多用例检验复用性。原文主要讨论分析型数据产品。下面把这种交付思路延伸到 Agent 的读取接口，并保留它与交易执行接口的区别。

假设目标是识别未来七天到期、尚未续签的合同。我们首先需要合同标识、状态、到期时间和可联系的人，而不需要把整个客户数据库导出给模型。数据边界应围绕可回答的问题建立。一个叫“客户全量信息”的大对象，字段很多，却可能没有任何明确的质量承诺。

我希望数据接口除了返回字段，还能表达结构版本、生成时间和来源。下面的校验器检查租户、结构和新鲜度，再给业务读取合同状态。它使用固定时间方便验证，属于自建数据契约示例，不是原文提供的 SDK。

from datetime import datetime, timezone, timedelta

NOW = datetime(2026, 12, 1, 1, 0, tzinfo=timezone.utc)


def contract_state(payload, tenant, now):
    if payload["schema"] != 1 or payload["tenant"] != tenant:
        raise ValueError("版本或租户不匹配")
    updated = datetime.fromisoformat(payload["updated_at"])
    if updated.tzinfo is None:
        raise ValueError("时间必须带时区")
    age = now - updated
    if age < timedelta(0) or age > timedelta(minutes=15):
        raise ValueError("数据时间不满足本用例要求")
    row = payload["contract"]
    if row["status"] not in {"active", "expired", "renewed"}:
        raise ValueError("未知合同状态")
    return row["status"]


payload = {"schema": 1, "tenant": "t1",
           "updated_at": "2026-12-01T00:55:00+00:00",
           "contract": {"id": "C1", "status": "active"}}
assert contract_state(payload, "t1", NOW) == "active"
try:
    contract_state(payload, "t1", NOW + timedelta(hours=1))
except ValueError:
    pass
else:
    raise AssertionError("过期数据不能继续被接受")
print("契约检查通过，新鲜度超限时明确拒绝")

完整示例可下载，使用 Python 3.9 或以上版本运行：python3 example.py。只依赖标准库，不调用真实业务服务。

新鲜度要求来自使用场景。做每周经营分析，昨天的数据可能足够；决定今天是否再次扣款，同样的延迟可能不可接受。不能给所有数据统一标注“实时”，却没有测量标准。应明确从业务发生到数据可见的延迟、缺失率，以及发生故障时如何通知使用方。

数据产品还需要明确的负责人。客户联系信息由谁维护，字段含义由谁解释，出现异常由谁修复，都应能够找到对应团队。否则接口文档虽然齐全，数据出问题时仍然只能在群里寻找“了解这个表的人”。所有权不是元数据装饰，而是持续交付的前提。

当多个用例都需要同一份合同事实，可以抽取稳定的共享部分，但不要过早把所有业务塞进一个统一模型。续约提醒需要的信息，与财务结算需要的信息并不完全相同。先让一个用例获得可验证的价值，再用后续用例检验边界，通常更容易控制设计成本。

对于 Agent，返回数据还要考虑权限和信息量。字段级授权、租户过滤与敏感信息脱敏，应在数据服务端完成。数据有明确用途，也更容易决定哪些内容应该进入上下文、哪些仅保留引用。把原始数据库自由查询权交给模型，往往使权限和成本都难以控制。

分析结果可以帮助选择动作，却不应替代最终交易校验。一个“待续约客户”数据集可能有几分钟延迟，Agent 据此整理提醒名单没有问题；真正发送或扣款之前，还需要确认当前合同状态、联系许可和有效授权。读取数据产品与执行业务命令，承担的是不同责任。

落地检查可以从几条具体规则开始：主键是否稳定，状态枚举是否明确，时间是否包含时区，缺失值如何表达，旧结构还能支持多久。再加入数据质量监控和异常示例测试。模型能够补全自然语言，并不意味着可以替数据接口猜测这些基础语义。

我会把数据产品看作一份面向使用者的长期交付承诺：这份数据回答什么问题，可信到什么程度，如何获取，出了问题找谁。把这些约定做好，Agent 才有条件做更复杂的判断；否则接入再多工具，也可能只是把系统之间互相矛盾的事实更快地拼在一起。

上一篇 · 系列目录 · 下一篇