Awesome Agentic Engineering

生产指南 · 10 项证据门槛

AI Agent 生产就绪检查清单

Demo 只能证明 Agent 偶尔能完成一次任务。生产评审要回答的是：当真实用户、真实数据和真实工具进入系统后，任务是否有边界、行为是否可重复、过程是否可观测、失败是否可恢复、成本是否受控。

给 Agent 评分 获取模板

如何使用这份清单

每项按 0–2 分评估：0 分表示控制缺失；1 分表示已有控制，但仍不完整或依赖人工；2 分表示团队能提供可重复验证的证据。把结果记录进 Agent Card ，并在模型、工具、权限、数据源或上线范围变化时重新评审。

总分不能覆盖上线阻塞项。 如果缺少授权控制、破坏性工具没有边界、密钥可能暴露，或者失败后没有恢复路径，无论其他维度得分多高，都应该停止上线。

10 项生产门槛

维度 达到 2 分的证据 必须阻断上线的情况
目标清晰度 明确用户、任务边界、成功指标和非目标 要求 Agent 处理一类无法定义边界的请求
工具权限 逐工具权限、白名单、参数校验和高风险写操作审批 模型控制的动作可以超过请求者自身权限
记忆 状态结构、所有者、保留期、查看、删除和租户隔离 状态可能跨用户泄漏，或用户无法删除
评估 覆盖正常、边界、对抗和失败路径的版本化用例 上线质量只靠几条 Demo Prompt 判断
失败处理 超时、有界重试、降级、幂等和用户恢复路径 局部失败可能静默重复执行或丢失副作用
安全 提示注入、数据边界、密钥、网络出口和危险工具测试 检索内容可以重写系统指令或暴露凭据
可观测性 模型、检索、工具、策略、成本和结果共用 Trace ID 运维人员无法还原一次关键动作为什么发生
成本控制 单次预算、步骤上限、并发配额、告警和强制终止 循环执行没有确定性的花费上限
人工审核 风险分级、授权审批人、完整证据和可恢复状态 不可逆或高影响动作无需人工确认即可执行
文档 安装、架构、负责人、威胁模型、Runbook 和示例 只有原始开发者知道如何运维或关闭 Agent

什么才算证据

文档里写了一句“要安全”不等于系统真的执行了安全控制。优先提供其他工程师可以检查或重新运行的产物：

  • 目标证据：与明确工作流绑定的验收标准和非目标。
  • 权限证据：工具 Schema、Scope、策略决策记录和拒绝调用测试。
  • 评估证据：包含预期结果的 Fixture 和明确的发布阈值。
  • 运维证据：Trace、预算告警、回滚步骤和事故负责人。
  • 人工控制证据：谁在执行前审核了什么证据，以及审批结果。

可以参考仓库中的 Agent Card 示例 ，把证据放在代码附近，而不是只存在于一次无法复现的上线会议里。

如何解释 20 分评分

分数 阶段 建议动作
0–7 仅 Demo 保持只读或模拟工具，先定义工作流和负责人
8–14 原型 只面向内部用户，设置严格限制并强制人工审核
15–18 有限 Beta 小流量灰度，关闭全部上线阻塞项
19–20 生产候选 完成运维评审，只在证据充分后逐步扩大权限

使用 在线评分器 可以生成可分享的评分链接，并下载机器可读的 agent-card.json。

下载 fail-closed Starter

不需要 Node.js 或 npm。选择与 Agent 风险相符的最小 Profile， 将 JSON 保存为 agent-card.json，将 YAML 保存为 .github/workflows/agent-readiness.yml。

Profile Agent Card 工作流
只读 下载 JSON 下载 YAML
仅草稿 下载 JSON 下载 YAML
状态变更 下载 JSON 下载 YAML

每套 Starter 都从 0/20 和一个显式上线 blocker 开始。CI 会检查 这些下载文件与 agentic-init 输出逐字节一致。

把评审变成 CI 门禁

将 Agent Card 保存在实际消费仓库中。当卡片、工作流、工具或评估发生变化时，运行公开的 Node 24 Action。 

- uses: lindixu6-hash/awesome-agentic-engineering@v0
  with:
    card: agent-card.json
    min-score: "15"
    fail-below: "true"
    fail-on-blockers: "true"

为保持向后兼容，严格阻塞项模式需要显式开启。Action 会输出数值得分、评级、徽章、综合门禁结果、阻塞项数量和阻塞项列表，并在 Workflow Summary 中分别展示两类门禁。整个过程不调用模型 API，也不需要外部 Key。

无需 clone，也可以直接在本地运行：

npm exec --yes \
  --package=github:lindixu6-hash/awesome-agentic-engineering#v0 \
  -- agentic-score agent-card.json

如需查看可执行 Runtime 集成，可以检查 LangGraph.js Eval 与 OpenAI Agents SDK Eval。 两者都在不使用模型 API Key 的情况下运行相同 Fixture 与 Result 契约。

把事故变成回归测试

当公开事故、内部失败、安全漏洞或红队结果被转成下一次发布前必跑的测试，生产就绪度才会真正累积。

  1. 记录来源，并准确区分：真实事故、漏洞、对抗测试还是研究 PoC。
  2. 用 Given 写前置状态，用 When 写危险行为，用 Then 写必须生效的控制。
  3. 将 Fixture 加入评估集，定义预期的拒绝、审批、降级或隔离结果。
  4. 用该用例阻断发布，避免同类问题静默回归。

查看 带来源的中文生产事故案例库 ，其中每个案例都包含 Given/When/Then 回归测试。

一次可执行的上线评审

  1. 完成十项评分，并为每个 2 分附上证据。
  2. 将上线阻塞项与数字总分分开记录。
  3. 执行正常、对抗、超时、局部失败和预算耗尽测试。
  4. 确认审批人、回滚负责人、关闭路径和事故沟通渠道。
  5. 从只读、影子或小流量模式开始，依据证据逐步扩大权限。

把 上线检查模板 复制进 Release Issue，让最终决策和证据可以被复盘。