从业务流程到 Agent：一份可落地的需求契约怎么写

天远大数据
0 阅读3分钟

企业 Agent 项目最容易缺的不是框架，而是可以直接进入开发和测试的需求输入。

一句「做个销售 Agent」无法确定事件来源、工具权限、异常分支和验收条件。更实用的做法，是把业务材料整理成一份场景契约，再映射到知识库、Workflow、Agent 和 Skill。

六类输入材料

第一轮需求梳理至少需要：

  1. 现有流程：发起人、触发条件、步骤、系统和交付结果；
  2. 输入输出样例：正常样例与异常样例；
  3. 规则与例外：确定规则、经验判断、高风险决策；
  4. 系统与权限：接口、身份、读写范围、敏感字段和回滚方式；
  5. 知识依据：来源、版本、负责人和可见范围；
  6. 验收与恢复：指标、人工接管、超时确认和恢复点。

业务人员与技术人员整理真实流程

把材料转换成场景契约

下面是一份可以进入技术评审的 YAML：

scene_id: lead_normalization
owner: sales_ops
trigger:
  type: schedule
  cron: "0 9 * * 1-5"
input:
  sources: [web_form, event_sheet, sales_group]
  samples: fixtures/lead_samples/
output:
  schema: LeadRecordV2
  target: crm.pending_pool
rules:
  deterministic:
    - normalize_phone
    - deduplicate_company
  model_assisted:
    - classify_industry
    - summarize_demand
permissions:
  read: [lead_source, company_dictionary]
  write: [crm.pending_pool]
  forbidden: [crm.customer, contract, payment]
human_gate:
  - conflicting_company
  - missing_contact
acceptance:
  required_field_rate: 0.98
  duplicate_rate_max: 0.01
  p95_latency_seconds: 60

契约的价值在于把模糊描述拆成可验证字段。每一个字段都能落到代码、权限配置或测试用例。

推荐的执行链

flowchart LR
    A[触发事件] --> B[输入标准化]
    B --> C{契约校验}
    C -->|失败| H[人工队列]
    C -->|通过| D[规则与知识检索]
    D --> E[Agent 生成计划]
    E --> F[Skill 执行动作]
    F --> G{结果验收}
    G -->|通过| I[业务回写]
    G -->|异常| H
    H --> J[审计与恢复]
    I --> J

确定性规则放在 Agent 之前，可以减少不必要的模型调用。Agent 只处理需要理解上下文和动态选择动作的部分。Skill 则负责参数校验、权限、超时和幂等。

用代码校验需求是否完整

from dataclasses import dataclass


@dataclass(frozen=True)
class SceneContract:
    scene_id: str
    owner: str
    input_samples: int
    output_schema: str
    allowed_actions: tuple[str, ...]
    human_gates: tuple[str, ...]
    acceptance_metrics: tuple[str, ...]
    recovery_point: str


def validate(contract: SceneContract) -> list[str]:
    errors: list[str] = []
    if not contract.scene_id.strip():
        errors.append("scene_id is required")
    if not contract.owner.strip():
        errors.append("business owner is required")
    if contract.input_samples < 3:
        errors.append("at least 3 sanitized samples are required")
    if not contract.output_schema.strip():
        errors.append("output schema is required")
    if not contract.allowed_actions:
        errors.append("allowed action list is empty")
    if not contract.human_gates:
        errors.append("human takeover conditions are required")
    if not contract.acceptance_metrics:
        errors.append("acceptance metrics are required")
    if not contract.recovery_point.strip():
        errors.append("recovery point is required")
    return errors

这段校验不复杂，但能挡住很多「先做起来再说」的模糊需求。契约没有通过，任务就不进入开发排期。

权限和幂等不能放到最后

工具调用需要明确 allowlist。对外部系统的写操作还要生成稳定幂等键：

import hashlib


def action_key(request_id: str, action: str, target: str) -> str:
    value = f"{request_id}:{action}:{target}".encode()
    return hashlib.sha256(value).hexdigest()

同一幂等键只能产生一次有效写入。超时后先查外部系统状态，再决定是否重试，不能把「没有收到响应」直接等同于「没有执行成功」。

业务负责人与工程人员检查权限和验收边界

验收覆盖异常路径

最低限度要测试：重复请求、事件乱序、部分系统成功、执行中崩溃、权限被收回、人工接管和版本升级后的恢复。

如果这些情况没有写进需求，项目演示可能正常，上线后的状态数量却会快速增加。

天远大数据在企业 Agent 场景评估中，会先把六类业务材料转成类似的场景契约。准备项目的团队可以从一条脱敏流程开始，先让契约通过，再决定第一阶段需要哪些 Skill、知识和系统连接。

avatar
文章
阅读
粉丝