AI agent Prompt Contract 设计：把角色、输入、输出和拒绝条件写成接口

很多 AI agent 项目的提示词写得像一段说明书：你是一个专业助手，请认真完成任务。这样的提示词能演示，却很难测试、复用和审查。真正进入工程流程后，提示词应该像接口一样被设计：输入是什么，输出必须长什么样，什么情况下拒绝，哪些字段不能缺，失败时如何把控制权交还给系统。

这就是 Prompt Contract 的价值。它不是让提示词更长，而是把 prompt 从“经验文本”变成“可执行约束”。如果前端、工具层、评测脚本都能读懂这份 contract，agent 的输出才有机会进入真实业务链路。

先给结论：Prompt Contract 至少包含六部分

Prompt Contract 的重点是可检查，不是文案漂亮。判断一份 contract 是否合格，可以问三个问题：工程能不能解析它，测试能不能验证它，出错时系统能不能知道下一步。

一份可直接改造的 Prompt Contract 模板

下面这个模板适合需求整理、内容生成、任务规划、数据分析等多数内部 agent。你可以先用它做最小版本，再按业务加字段。

你是 {agentName}。

职责范围：
- 你只负责：{allowedResponsibilities}
- 你不负责：{deniedResponsibilities}

输入字段：
- userRequest: 用户原始请求
- taskType: 任务类型，枚举值为 {taskTypes}
- context: 已授权上下文，只能使用这里提供的信息
- constraints: 明确约束，例如时间、格式、目标用户、禁止动作
- availableTools: 当前可用工具列表

输出要求：
- 必须输出合法 JSON
- 必须符合 schema: {outputSchema}
- 不允许输出 schema 之外的顶层字段
- 缺少必要信息时，不得猜测，必须设置 nextAction = "ask_user"

拒绝条件：
- 请求超出职责范围
- 输入缺少完成任务的必要字段
- 用户要求执行未授权工具
- 用户要求执行不可逆动作但没有确认信息
- 上下文不足以支持结论

质量标准：
- 每个建议都要能对应到输入或上下文
- 每个风险都要给出下一步处理方式
- 如果 confidence < 0.7，必须说明原因

这个模板的核心不是“写得像规范”，而是让模型知道哪些信息能用、哪些动作不能做、结果如何交给程序继续处理。

一、先写角色边界，不写万能助手

不要把 agent 定义成“全能项目助理”。更稳的写法是：它只负责某类任务，例如“把用户需求整理成结构化 brief”，不负责报价确认、合同发送或外部通知。

角色边界要包含“不做什么”。这能减少模型在模糊输入下自行扩展任务。尤其是面向工具调用的 agent，角色边界最好和工具权限一一对应。

如果一个 agent 没有“不负责什么”，它很容易在用户一句“顺便帮我处理一下”之后进入不该进入的流程。

二、输入字段要结构化

如果输入只是自然语言，模型每次理解都可能不同。可以把用户原文和结构化字段分开：

{
  "userRequest": "帮我整理这个客户需求",
  "projectType": "landing_page",
  "targetAudience": "小企业负责人",
  "knownConstraints": ["一周内上线", "预算有限"]
}

结构化输入让 agent 更容易判断缺什么。

更完整的输入 contract 可以这样设计：

{
  "taskId": "task_20260506_001",
  "taskType": "brief_extraction",
  "userRequest": "帮我整理这个官网改版需求",
  "actor": {
    "userId": "u_123",
    "role": "editor",
    "permissions": ["draft:create", "doc:read"]
  },
  "context": {
    "sourceDocs": ["doc_website_brief_v3"],
    "conversationSummary": "用户希望重做首页，但尚未提供案例和预算。"
  },
  "constraints": {
    "language": "zh-CN",
    "outputStyle": "structured_brief",
    "deadline": "2026-05-12"
  }
}

注意两个细节：第一，权限信息应该由系统传入，而不是让模型猜；第二，上下文应该是“已授权上下文”，不要把全量历史和全部文档都塞进去。

三、输出 schema 是验收基础

输出不要只要求“一段清晰总结”。更好的方式是规定字段：摘要、缺失信息、下一步动作、风险点、是否需要人工确认。

schema 稳定后，前端展示、评测和自动化流程都更容易接入。

一个更适合落地的输出 schema 可以是：

{
  "status": "ready | needs_input | blocked",
  "summary": "string",
  "structuredResult": {
    "goal": "string",
    "audience": "string | null",
    "constraints": ["string"],
    "deliverables": ["string"]
  },
  "missingFields": [
    {
      "field": "targetAudience",
      "reason": "目标用户会影响页面结构和文案角度",
      "question": "这次页面主要面向哪类客户？"
    }
  ],
  "risks": [
    {
      "level": "medium",
      "reason": "缺少上线时间会影响任务拆分",
      "nextStep": "确认 deadline"
    }
  ],
  "nextAction": "continue | ask_user | human_review | stop",
  "confidence": 0.82
}

这里的 status 和 nextAction 很关键。summary 给人看，nextAction 给系统看。不要让下游流程从一段自然语言里猜“下一步应该干什么”。

四、拒绝条件要写清楚

Prompt Contract 要明确哪些情况不能继续：信息不足、超出权限、要求写入高风险系统、要求处理敏感字段、用户目标和工具能力不匹配。

拒绝不是简单说“不行”，而是输出可执行原因：缺少哪些字段、需要谁确认、可以走哪条替代路径。

可以把拒绝条件写成可测试规则：

拒绝条件越具体，评测越容易覆盖。你可以为每条拒绝规则写一条测试样本，确保 prompt 改版后不会退化。

五、Contract 要接入评测，而不是写完就放着

Prompt Contract 写完后，至少准备三类样本：

一个最小评测表可以这样维护：

{
  "caseId": "brief_missing_audience_001",
  "input": {
    "taskType": "brief_extraction",
    "userRequest": "帮我做一个产品页 brief"
  },
  "expected": {
    "status": "needs_input",
    "nextAction": "ask_user",
    "missingFieldsContains": ["targetAudience"]
  }
}

不要只测试“回答看起来不错”。对 Prompt Contract 来说，关键是字段是否完整、状态是否正确、拒绝是否稳定。

六、失败案例：输出格式每次不同，无法接入系统

一个 agent 能把需求总结得很好，但每次字段顺序和名称不同。有时叫“风险”，有时叫“注意事项”，有时缺少下一步动作。结果业务系统无法解析，只能人工复制。

修复方式不是简单补一句“请按 JSON 输出”，而是把 prompt 改成 contract：固定输入字段、固定输出 schema、缺失信息必须进入 missingFields，下一步动作必须进入 nextAction，同时把 20 条历史失败样本加入回归集。之后输出才真正进入自动化链路。

更重要的是，团队把 prompt 版本号写进日志。后来一次改动导致 missingFields 为空数组，回归测试立刻发现问题，没有等到业务系统解析失败。

七、上线前 Checklist

• 是否写清 agent 负责和不负责的范围
• 输入是否有结构化字段
• 输出是否有稳定 schema
• 拒绝条件是否明确
• 是否定义质量标准和人工确认条件
• contract 变更后是否有回归样本
• 版本变更是否记录原因
• 日志中是否记录 prompt contract version
• 下游系统是否只依赖结构化字段，不解析自然语言

结语

Prompt Contract 把提示词从“经验文本”变成“工程接口”。角色、输入、输出、拒绝条件、评测样本和版本记录越清楚，agent 越容易测试、接入和长期维护。真正有用的 prompt，不是写得更像说明书，而是能被系统验证。

延伸阅读：

• AI Agent 工具调用设计
• AI Agent 状态机设计指南
• Cursor 项目级提示词模板
• Cursor 团队规则文件与代码审查流程