KDD Cup 数据分析 Agent：受限工具、持久状态和 trace 评估
KDD Cup 是由 ACM SIGKDD 组织的年度数据挖掘与知识发现竞赛。把竞赛任务交给 Agent 时，难点不在于让模型“会写一段 pandas”，而在于让每次分析都可复现：工具权限可控，状态可以恢复，模型的每一步都能通过 trace 解释。
本文给出一个与具体年份数据集无关的参考架构。数据集、指标和提交规则必须以对应 KDD Cup 年份的官方页面为准。
1. 先限制 Agent 能做什么
不要让模型直接拿到宿主机 shell。把能力拆成小工具，并为每个工具定义输入 schema、资源上限和输出 schema：
list_tables：只读列出数据集中的表和字段；profile_table：只读统计缺失率、基数和少量分位数；sample_rows：按固定上限抽样，禁止任意导出全表；run_query：只允许参数化 SQL，限制扫描字节数和执行时间；run_python：在临时目录运行白名单库，限制 CPU、内存和墙钟时间；write_artifact：只允许写入当前 run 目录，拒绝路径穿越。
工具返回结构化结果，不把异常堆栈直接拼回提示词。一个最小的工具调用记录可以长这样：
{
"tool": "profile_table",
"args": {"table": "events"},
"result": {"rows": 120000, "null_rate": {"latency_ms": 0.02}},
"limits": {"timeout_ms": 5000, "max_output_bytes": 20000}
}2. 用持久状态让分析可恢复
把“对话历史”与“分析状态”分开。状态至少包括 run_id、数据集版本、当前假设、已生成 artifact、验证结果和待办步骤。每次工具调用成功后，以追加事件的方式保存状态；恢复时从最后一个完整事件重建快照。
from dataclasses import dataclass, field
@dataclass
class RunState:
run_id: str
dataset_sha256: str
hypotheses: list[str] = field(default_factory=list)
artifacts: list[str] = field(default_factory=list)
completed_steps: list[str] = field(default_factory=list)
def checkpoint(state: RunState, event_store):
event_store.append({"type": "state_snapshot", "state": state.__dict__})不要把 API key、原始数据行或完整提示词写入普通 trace。敏感值应由运行时注入并在日志层脱敏；artifact 只记录内容哈希和相对路径。
3. trace 要回答什么问题
评估 trace 时，先看可审计性，再看模型是否“说得像人”：
- 每个结论是否能追溯到具体数据版本、工具调用和 artifact？
- 工具失败后是否停止、重试或换用替代路径，并留下原因？
- Agent 是否越权读取数据、跳过验证或重复执行有副作用的步骤？
- 同一个
run_id重放时，随机种子、依赖版本和输入是否一致？
可以把一次运行拆成四类指标：任务结果（如提交文件是否满足官方 schema）、过程约束（越权调用数、超时数）、恢复能力（中断后成功续跑比例）和 trace 质量（关键结论的证据覆盖率）。这些是评估维度，不是某届 KDD Cup 的官方评分。
4. 一个最小评估集
在接入真实竞赛数据前，准备固定 fixture：缺失值、类别爆炸、超大字段、恶意路径和工具超时各一组。每次提交 Agent 版本都运行：
- 正常分析：能生成带哈希的报告和提交 artifact；
- 工具拒绝：越过行数、时间或路径限制时返回明确错误；
- 中断恢复：在任意 checkpoint 后杀掉进程，恢复后不重复写入；
- 证据检查：报告中的数字都能映射到 trace 事件；
- 复现检查：固定依赖和随机种子后，关键摘要一致。
结语
KDD Cup 场景最适合用来检验 Agent 的工程纪律：受限工具降低爆炸半径，持久状态降低中断成本，trace 让结果可以复盘。真正的竞赛成绩仍取决于具体数据、特征和官方评测；本文没有运行任何 KDD Cup 官方数据集，也没有声称某种架构带来分数提升。
参考来源：
- ACM SIGKDD KDD Cup Archives：https://www.kdd.org/kdd-cup
- KDD Cup 当年竞赛页面、数据许可和提交规范（以具体年份官方页面为准）