本文目录8 个章节
评测先回答“怎样知道它变好了”
现在的 brief-agent 已有 Loop、Tool、RAG、Skill、Checkpoint、审批、MCP 和可选 Multi-Agent。一次演示成功仍然无法说明 Agent 稳定。最终文字可能很流畅，引用却不存在；Agent 也可能声称文件已保存，目标目录中没有产物。
评测要同时检查过程和结果。
任务集 ─▶ Agent Run ─▶ Trace ─────────▶ 过程诊断
└▶ 最终环境 ─────▶ 结果验收
│
▼
回归报告 / 发布门槛设计 20 个分层任务
任务覆盖正常调研、证据不足、工具故障、进程恢复、审批拒绝和恶意输入。每题固定输入、资料夹具、预算、确定性断言和可选主观 rubric。
每题运行三次，共 60 次试验，用来暴露随机失败。报告同时列出每题通过次数、成功率、P50/P95、工具调用数、token 与费用。安全用例单独设零越权门槛，不能被平均分抵消。
结果检查器读取实际产物
from dataclasses import dataclass
from pathlib import Path
@dataclass(frozen=True)
class EvalResult:
passed: bool
checks: dict[str, bool]
failure_layer: str | None
def grade_brief(path: Path, known_source_ids: set[str]) -> EvalResult:
exists = path.is_file()
text = path.read_text(encoding="utf-8") if exists else ""
cited_ids = {
token[1:-1]
for token in text.split()
if token.startswith("[") and token.endswith("]")
}
checks = {
"artifact_exists": exists,
"has_content": len(text.strip()) >= 200,
"has_citations": bool(cited_ids),
"citations_exist": bool(cited_ids) and cited_ids <= known_source_ids,
}
passed = all(checks.values())
return EvalResult(passed, checks, None if passed else "outcome")Agent 自述不参与确定性通过判定。文件、来源索引、审批日志和网络记录才是环境结果。
Trace 用来定位六层失败
Trace 关联模型调用、工具参数、工具结果、状态变化、Skill 版本、审批与最终产物。失败归入六层：spec、model、retrieval、tool、state、evaluator。
修复对应层后再重跑任务。检索没有命中时改 Prompt，只会让原因更难判断。
生产运行把提交与执行分开
Client ─▶ Run API ─▶ Queue ─▶ Worker ─▶ Model / Tools
│ │
▼ ├──▶ Checkpoint Store
Status API ├──▶ Approval Queue
└──▶ Trace + MetricsAPI 用业务幂等键创建 run，队列只传 run ID。Worker 获取带过期时间的租约，从安全检查点继续。重复投递读取现有 run，不创建第二次写入。
状态机限制生产路径
TERMINAL = {"succeeded", "failed", "cancelled", "budget_exhausted"}
TRANSITIONS = {
"queued": {"running", "cancelled"},
"running": {"waiting_approval", "succeeded", "failed", "budget_exhausted"},
"waiting_approval": {"queued", "cancelled"},
}
def transition(current: str, target: str) -> str:
if current in TERMINAL or target not in TRANSITIONS.get(current, set()):
raise ValueError("invalid_state_transition")
return targetWorker 丢失租约后停止提交状态和副作用。新 Worker 从已提交检查点恢复，预算和幂等键不会归零。
成本与发布使用同一组门槛
每次 run 固定代码、Prompt、Skill、模型、工具 Schema 和数据版本。发布先跑离线评测，再做小流量灰度，观察成功率、P95、费用、安全拦截和审批量。
成本优化从测量开始：缓存确定性检索、压缩稳定前缀、让小模型处理分类、限制无效重试。质量和安全门槛保持不变。
毕业项目的完整交付
brief-agent/
├── CLI + HTTP API
├── Agent Runtime + Tool Registry
├── RAG + Context + Citations
├── Skills + Sessions + Checkpoints
├── Approval + Security Tests
├── MCP + Optional Multi-Agent
├── Evals + Trace Report
└── Worker + Deployment Config示例项目使用以下验收标准：确定性测试全部通过；20 个功能任务各跑三次，60 次成功率至少 90%；安全测试零越权；报告单次成本和 P95 延迟。业务上线应按数据和副作用风险另定阈值。
现场验收增加一个只读工具。开发者先写 ToolSpec 与权限，补成功和失败测试，再运行完整回归，并说明是否需要新增 Skill、MCP Server 或专家 Agent。完成这条路径，说明开发者已经能独立扩展和交付 Agent 系统。
REFERENCES
参考链接
所属系列
AI AGENT 入门教程