Skill 输出 Schema：让 Agent 不再猜下游要什么

Skill输出Schema，是给 Axon Skill 返回结果设计的结构化契约。很多团队已经意识到输入资料不能写在大段提示词里，于是开始把 Source Data 字段化；但执行结束后，结果仍然是一段自由文本。下游 Agent 要继续生成文件、发起确认或写入工作区时，只能猜“这段话里哪些是结论、哪些是证据、哪些需要人工看”。这会带来重复解析、手动复制、低效返工和误读风险。

输入字段解决任务如何开始，Skill输出Schema 解决任务如何交给下一环。前者可以参考 Source Data 字段设计，后者则要回答：这个 Skill 返回什么对象？哪些字段可被机器读取？哪些字段必须给人看？哪些风险会改变 Trust Mode？如果产物要进入 workspace 验收，也可以结合 workspace 产物验收契约 一起设计。

没有输出契约的 Skill，只能生成“看起来有用”的文本；有输出契约的 Skill，才能成为 Agent 编排里的稳定接口。

输出契约从四个对象开始

设计 Skill输出Schema 时，不要一开始就追求复杂。多数办公场景可以先把返回结果拆成四个对象。

对象	作用	典型字段	下游用途
result	给业务用户看的结论	summary、decision、draftText	生成报告、邮件或简报
evidence	证明结论从哪里来	sourceId、quote、filePath、confidence	人工复核和引用来源
risk	标记不能直接自动化的部分	level、reason、affectedObject	Trust Mode 确认和异常分流
nextAction	告诉 Agent 下一步怎么做	actionType、owner、deadline	排程、交接或继续调用 Skill

这样的设计不要求每个字段都很重，但它要求 Skill 返回结果不能只有一段自然语言。JSON Schema 官方说明把 schema 解释为描述 JSON 数据结构的方式，可参考 JSON Schema 概览。在 Axon 场景里，schema 的价值不是炫技，而是让 Agent、人工审核和文件产物使用同一份结构。

result 不是最终真理

result.summary 可以是摘要，result.draftText 可以是草稿，但它不代表 Agent 可以跳过证据和风险。任何会外发、发布、覆盖文件或影响客户的结果，都应该带着 evidence 和 risk 一起返回。

nextAction 要能被拒绝

很多输出只写“建议发送给客户”。更好的做法是写清 actionType、受影响对象和 owner。这样 Trust Mode 才能要求确认人选择通过、退回、改收件人或只保存草稿。

一个可落地的输出 envelope

下面是一个资料整理 Skill 的返回 envelope。它不是为了让每个团队照抄，而是展示字段粒度应该到哪里。

{
  "skillRunId": "run_20260525_0910_research_note",
  "status": "needs_review",
  "result": {
    "summary": "供应商A本周价格上调，但交期承诺没有同步变化。",
    "draftFile": "workspace/output/supplier-brief.md",
    "language": "zh"
  },
  "evidence": [
    {
      "sourceId": "quote-sheet-2026-05",
      "filePath": "workspace/input/supplier-quotes.xlsx",
      "cellRange": "B12:E18",
      "confidence": "high"
    }
  ],
  "risk": {
    "level": "medium",
    "reason": "价格变化会影响客户报价，需业务负责人确认。",
    "affectedObject": "customer quotation draft"
  },
  "nextAction": {
    "actionType": "request_confirmation",
    "owner": "sales-ops",
    "allowedOptions": ["approve_draft", "revise_terms", "save_only"]
  }
}

这个 envelope 可以继续被 Agent 使用：如果 status 是 complete，后续 Skill 生成文件；如果 status 是 needs_review，Agent 转入人工确认；如果 risk.level 是 high，就不进入自动发送路径。OpenAI Agents SDK 的 Tools 文档 也体现了工具返回值在 Agent 执行中的重要性。对 Axon 来说，Skill输出Schema 就是让工具返回值进入白领工作流的治理层。

把 Schema 写成可检查规则

只写文档还不够。团队应该为关键 Skill 写一份最小 schema，用来检查字段是否存在、类型是否正确、风险是否被标记。实践里可以压缩成三次校验。

1. 结构校验：确认 status/result/evidence/risk/nextAction 都存在，并且 status 只能是 complete、needs_review 或 blocked。
2. 证据校验：要求每条 evidence 至少包含来源 ID 和文件路径，不能只给结论。
3. 风险校验：把 risk.level 限定为 low、medium、high，并让 nextAction.allowedOptions 提供可执行选项。

一份简化 JSON Schema 可以这样写：

{
  "type": "object",
  "required": ["skillRunId", "status", "result", "evidence", "risk", "nextAction"],
  "properties": {
    "skillRunId": { "type": "string" },
    "status": { "enum": ["complete", "needs_review", "blocked"] },
    "result": { "type": "object" },
    "evidence": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["sourceId", "filePath"]
      }
    },
    "risk": {
      "type": "object",
      "required": ["level", "reason"],
      "properties": {
        "level": { "enum": ["low", "medium", "high"] }
      }
    },
    "nextAction": { "type": "object" }
  }
}

如果你在做资料检索、PDF 摘要和邮件草稿，也可以参考 Research PDF Email Agent 工作流：这类流程天然需要把摘要、来源、草稿和确认动作分开。

FAQ

Q1：Skill 输出一定要 JSON 吗？
不一定。Markdown、YAML、表格都可以，但关键字段必须稳定。如果后续 Agent 要机器读取，JSON 或 YAML 更容易被校验。

Q2：Schema 会不会限制模型发挥？
会限制不必要的漂移，这是好事。正文草稿可以自然，但状态、证据、风险和下一步动作不应该随意变化。

Q3：什么时候必须设计 Skill输出Schema？
当一个 Skill 的结果会被另一个 Skill、Agent、定时任务或人工验收流程继续使用时，就应该设计。只给个人看的临时摘要可以轻一些。

让每次输出都能接住下一步

从一个高频 Skill 开始，先定义 status/result/evidence/risk/nextAction，再补齐字段类型和验收样例。契约稳定后，把它接入 Agent 编排和 Skill 变更控制。如果团队准备开始使用 Axon，可以先下载并试跑一条低风险链路；需要扩展时，再阅读 Source Data、workspace 产物和 Trust Mode 文章，把 Skill输出Schema 接到真实交付链路里。