《AI Agent 产品开发·任务定义与能力边界》8.1 能接什么:系统集成的产品地图

Agent 能接哪些系统,不取决于接口数量,而取决于接口的副作用。本节给出读、写、触发三类接口的集成地图模板,用 A Relay、B Quill、C Runner 各画一张,解释只读接入为什么是最稳的第一步、只读又为什么不是零风险,最后给出接入路线图。

以下人物、公司与数字均为教学假设,不构成对任何真实产品的评价。

「这个 Agent 能接我们的 CRM 吗?」这是任务定义阶段最常被问到的问题。问的人通常期待一个二选一的答案:能,或者不能。但真实的产品判断不是二选一,而是先拆开:接的是这个系统的哪一层?读它的数据、写它的字段,还是触发它的流程?三种接法带来的风险、验收方式和回滚成本完全不同。

集成地图要解决的就是这件事。它不是系统清单,不是「已对接多少个平台」的营销数字,而是一张把每个外部系统拆成接口、标出副作用、排好接入顺序的工作图。地图画完,产品经理才能回答:第一步接什么,哪些接口永远不接,哪些接了也必须有人确认。

集成地图不是系统清单

系统清单回答「接了多少」,集成地图回答「接在哪一层」。同样接一个工单系统,只读工单正文和写入工单状态是两件不同的事:前者不改变任何外部状态,后者会让下一个打开工单的人看到不同的队列和优先级。把两者都写成「已对接工单系统」,等于把风险藏进了名词里。

一张可用的集成地图至少要有七个字段:

字段要回答的问题写错会怎样
系统接的是哪个外部系统把同一系统的不同接口混为一谈
接口具体读或写哪个对象验收时说不清到底改了什么
类型读、写还是触发风险等级被低估
数据方向数据从哪来到哪去权限面与隐私边界模糊
失败后果这一步错了会怎样回滚方案无从设计
回滚方式能不能撤回、撤回要多久出事时只能人工补救
负责人谁授权、谁维护权限过期后无人回收

七个字段里,最容易被省略的是「失败后果」和「回滚方式」。团队在演示阶段只关心接口能不能通,不关心通了之后错一次会留下什么。但 Agent 产品的风险恰恰不在「通不通」,而在「通了之后做错了怎么办」。一张没有失败后果的集成地图,只能用于立项,不能用于上线。

三类接口:读、写、触发

把所有接口压成三类,是因为三类的副作用形态不同。读只改变模型看到的上下文;写改变外部系统的状态;触发会让外部系统自己开始一段流程。副作用越往外走,撤回越难,需要的人在环上的位置越靠前。

类型典型接口副作用默认风险回滚难度
读查工单、读商品、拉报告无外部状态变化低不需要回滚
写改队列、改价格、写草稿改变字段或文件中有前值即可回滚
触发发通知、提交审批、调用外部流程引发他人或他系统的动作高通常不能完全撤回

读的风险低,不等于没有风险。它可能读到过期数据,可能读到超出任务需要的隐私字段,也可能因为权限给得太大而看到不该看的东西。读的风险主要落在数据治理,而不是业务状态。

写的关键是「有没有前值」。改价格时记录原价,改库存时记录原库存,改队列时记录原队列,才有回滚的可能。没有前值的写操作,即使技术上能改回去,也无法证明改回了什么。

触发是最容易被低估的一类。发一条通知看起来只是「发消息」,但通知一旦到达供应商,对方可能已经开始备货或调价。技术上撤回一条消息,不等于撤回对方已经采取的行动。所以触发类接口默认按高风险处理,除非能证明外部流程有幂等和撤销机制。

三案例各画一张地图

三个案例的任务不同,集成地图的形状也不同。把它们并排看,可以看到「自主档越高,接口越往外走」这条规律。

A Relay:读两份、写一份

A Relay 是 Northwind 的客服工单分诊 Agent,月工单量 26,400 单,人工分诊基线 3.5 分钟一单。它的地图只有三个接口:

系统接口类型数据方向失败后果回滚
工单系统读工单正文、客户等级、历史工单读外部 → Agent建议依据不足不需要
工单系统写队列归属与优先级写Agent → 外部工单进错队列改回原队列
知识库取首响模板编号读外部 → Agent模板不匹配不需要

A 的地图里没有触发类接口。它不直接给客户发消息,只给支持人员一个建议。建议采纳率 78%,分诊正确率 91.4%,采纳后仍出错率 2.9%。这三个数字说明:A 的价值来自「人确认得快」,而不是「机器替人决定」。地图上那条写接口之所以安全,是因为它写的是内部队列,且人就在旁边。

B Quill:读一份、写两份

B Quill 是 Meridian 的客户报告起草 Agent,月报告量 606 份,人工基线 4.2 小时一份。它的接口集中在文件侧:

系统接口类型数据方向失败后果回滚
数据平台读客户数据包与上月报告读外部 → Agent初稿事实错误不需要
图表引擎渲染图表文件写Agent → 草稿目录图表与正文不一致重新渲染
文档库写 Markdown 初稿写Agent → 草稿目录初稿不可用删除重写

B 的写接口都落在「草稿目录」,不碰客户门户。这是一个刻意设计的产品边界:Agent 可以生成,但不能发布。一次采纳率 63%,小改率 28%,返工率 9%,三档加起来才是审改工作的真实形状。如果 B 直接写客户门户,返工就不再是内部成本,而是客户可见的事故。

C Runner:读一份、写两份、触发一份

C Runner 是 Kettle 的电商运营任务执行 Agent,月任务量 13,200 个,人工基线 18 分钟一个。它的地图最靠外:

系统接口类型数据方向失败后果回滚
商品中心读商品、价格、库存读外部 → Agent判断依据过期不需要
定价系统改价格、改库存写Agent → 外部价格或库存错误用前值回滚
通知系统向运营与供应商发通知触发Agent → 外部对方已开始行动只能补发更正

C 的自动完成率 78%,其余 22% 转人工;审计抽检比例 8%,单次复核 12 分钟。它的错误中 86% 可回滚,不可回滚错误率 0.238%。这组数字解释了为什么 C 的地图必须把「通知」单独标成触发:写价格错了还能用前值改回去,通知发错了,对方可能已经按错误信息行动。

为什么只读接入是最稳的第一步

只读接入之所以稳,不是因为它简单,而是因为它把「理解是否正确」和「动作是否安全」拆成了两个可以分别验收的问题。

第一,只读不改变外部状态。Agent 读错了工单,最坏结果是给出一条不准确的建议;人看一眼就能发现。写错了队列,下一个人会按错误队列处理;触发错了通知,外部伙伴会按错误信息行动。只读把错误的暴露面限制在「建议」这一层。

第二,只读可以和人工判断直接对比。让 Agent 先只读,再输出它认为的队列、优先级和模板编号,然后与人工分诊结果对照,就能在上线前得到一组可复算的一致率。这个动作不需要改任何系统,也不需要外部伙伴配合。

第三,只读能暴露数据质量问题。字段缺失、编码不一致、历史工单脏数据,这些问题在只读阶段就会显现。如果先做写接口,数据问题会被写操作放大,排查时很难分清是模型判断错了,还是输入本身就错了。

第四,只读给团队留出建立信任的时间。支持人员先看到「它读得懂工单」,才会愿意让它写队列;先看到「它写的队列我改过两次」,才会讨论要不要扩大范围。信任不是一次性授权,而是一串可观察的小成功。

但只读只是第一步,不是终点。一个永远只读的 Agent,价值停在建议层,用户仍要把结果手工复制到系统里。只读接入选的是「先证明理解力」,不是「永远不写」。地图上的写接口应该在只读阶段就跑通验收标准,只是先不打开。

只读也有三种风险

把只读说成零风险是另一种偷懒。只读至少有三类风险,产品文档里要单独写。

权限过大。 为了省事,团队常给 Agent 一个「读全部工单」的账号。它确实只需要读当前工单,但账号能看到所有客户的历史。正确的做法是按任务开数据范围:只读当前工单、当前客户、与分诊相关的字段。

数据过期。 只读接口返回的是某一刻的快照。工单在 Agent 读取后被人改过,建议就会基于旧状态。地图上要标出哪些接口有缓存、缓存多久、是否需要二次确认。

隐私越界。 工单正文里可能有客户的联系方式、合同金额、投诉记录。Agent 读这些字段是为了分诊,不代表可以把它写进建议、日志或提示词。读权限和用权限要分开写。

这三类风险不会因为「只是读」而消失。它们只是不会立刻造成业务状态错误,所以更容易被忽略。

把地图写成可运行的模型

下面这个模型把集成地图做成可检查的结构:每个接口带类型和可回滚标记,风险由副作用推导,接入顺序固定为读、写、触发。三个案例的地图也写在同一个文件里。

// file: src/task/08-1-integration-map.ts
// tier: L2
// verify: node --test test/task/08-1-integration-map.test.ts

// 集成地图:把每个外部系统拆成读、写、触发三类接口,再按风险排序。
// 地图只描述边界,不替产品决定要不要接。

import { CASES, type Profile } from "../cases.ts";

export type SurfaceKind = "read" | "write" | "trigger";

export type Surface = {
  readonly system: string;
  readonly kind: SurfaceKind;
  readonly detail: string;
  readonly reversible: boolean;
};

export type Risk = "low" | "medium" | "high";

export const KIND_LABEL: Record<SurfaceKind, string> = {
  read: "只读",
  write: "写入",
  trigger: "触发",
};

// 接入顺序固定:先只读,再可回滚写入,最后才是触发。
export const SURFACE_ORDER: readonly SurfaceKind[] = ["read", "write", "trigger"];

// 只读不会改变外部状态;写入可回滚;触发会引发外部流程,通常不能完全撤回。
export function riskOf(surface: Surface): Risk {
  if (surface.kind === "read") return "low";
  if (surface.kind === "write") return surface.reversible ? "medium" : "high";
  return "high";
}

export type IntegrationMap = {
  readonly caseKey: Profile["key"];
  readonly surfaces: readonly Surface[];
  readonly counts: Record<SurfaceKind, number>;
};

export function countKinds(
  surfaces: readonly Surface[],
): Record<SurfaceKind, number> {
  const counts: Record<SurfaceKind, number> = { read: 0, write: 0, trigger: 0 };
  for (const surface of surfaces) counts[surface.kind] += 1;
  return counts;
}

export function buildMap(
  caseKey: Profile["key"],
  surfaces: readonly Surface[],
): IntegrationMap {
  return { caseKey, surfaces, counts: countKinds(surfaces) };
}

export const MAPS: Record<Profile["key"], IntegrationMap> = {
  A: buildMap("A", [
    {
      system: "ticketing",
      kind: "read",
      detail: "读取工单正文、客户等级与历史工单",
      reversible: true,
    },
    {
      system: "ticketing",
      kind: "write",
      detail: "写入队列归属与优先级",
      reversible: true,
    },
    {
      system: "knowledge-base",
      kind: "read",
      detail: "按队列取首响模板编号",
      reversible: true,
    },
  ]),
  B: buildMap("B", [
    {
      system: "data-pack",
      kind: "read",
      detail: "读取客户数据包与上月报告",
      reversible: true,
    },
    {
      system: "chart-engine",
      kind: "write",
      detail: "渲染图表并写入草稿目录",
      reversible: true,
    },
    {
      system: "document-store",
      kind: "write",
      detail: "写入 12 到 20 页 Markdown 初稿",
      reversible: true,
    },
  ]),
  C: buildMap("C", [
    {
      system: "catalog",
      kind: "read",
      detail: "读取商品、价格与库存",
      reversible: true,
    },
    {
      system: "pricing",
      kind: "write",
      detail: "修改价格与库存",
      reversible: true,
    },
    {
      system: "notification",
      kind: "trigger",
      detail: "向运营与供应商发通知",
      reversible: false,
    },
  ]),
};

// 地图排期:同一批接口按风险从低到高拆成可独立验收的阶段。
export function rolloutOrder(surfaces: readonly Surface[]): Surface[] {
  return [...surfaces].sort(
    (a, b) => SURFACE_ORDER.indexOf(a.kind) - SURFACE_ORDER.indexOf(b.kind),
  );
}

// 只读切片是接入的第一步:能证明理解力,又不改变任何外部状态。
export function readOnlySlice(map: IntegrationMap): Surface[] {
  return map.surfaces.filter((surface) => surface.kind === "read");
}

export function profileOf(map: IntegrationMap): Profile {
  const found = CASES.find((profile) => profile.key === map.caseKey);
  if (!found) throw new Error(`unknown case: ${map.caseKey}`);
  return found;
}

// 一行摘要,评审会上直接对照任务量与接口结构。
export function mapSummary(map: IntegrationMap): string {
  const profile = profileOf(map);
  return [
    `${profile.key} ${profile.name}`,
    `${profile.monthlyTasks.toLocaleString("en-US")} 任务/月`,
    `读 ${map.counts.read}`,
    `写 ${map.counts.write}`,
    `触发 ${map.counts.trigger}`,
  ].join(" / ");
}

riskOf 的判断顺序值得注意:读永远是低风险;写要看是否可回滚,可回滚是中风险,不可回滚直接升为高风险;触发不看可回滚标记,一律高风险。这不是说触发一定不能用,而是说它不能靠「技术上能撤回」来降级。

rolloutOrder 把一张地图排成接入顺序:先读、再写、最后触发。readOnlySlice 取出第一步能独立验收的接口。mapSummary 把案例的任务量和接口数量放在一行,方便在评审会上对照——同样是「一个读接口」,落在 26,400 单和 606 份上是不同的暴露规模。

模型不替产品做决定。它只保证一件事:当有人说「我们已经接入了这个系统」时,团队能追问一句「接的是哪一类接口,失败了怎么回滚」。

从地图到接入路线

一张地图要变成路线图,需要给每一类接口配一个退出条件。C Runner 的放量节奏可以直接借用:

阶段接什么时长退出条件
影子全部只读,只记录不执行4 周与人工决策一致率 ≥ 85%
执行 5%低风险写动作4 周错误率 ≤ 2%,零不可回滚错误
执行 20%加中风险写动作8 周错误率 ≤ 1.8%,回滚成功率 100%
执行 60%不含高风险动作—连续 8 周达标

这张表里没有「全量」这一行,是刻意的。触发类接口和高风险写动作不应该出现在自动放量的终点,它们需要单独的人审或完全不接。地图的价值之一,就是让团队早一点承认:有些接口不是「以后再接」,而是「设计上就不接」。

路线图还要写清楚「不接什么」。不接的接口同样是产品决策:不接客户门户的发布接口,意味着 B 的产出永远停在草稿;不接供应商的自动下单接口,意味着 C 的通知永远只到「提醒」这一层。把这些写进地图,比写在需求文档的附录里更不容易被后来的版本悄悄推翻。

小结

  • 集成地图不是系统清单,它按接口拆系统,按副作用排风险。
  • 读、写、触发三类接口的副作用形态不同,风险不能用一个「已对接」概括。
  • 只读接入是最稳的第一步,因为它把「理解是否正确」和「动作是否安全」分开验收。
  • 只读不是零风险:权限过大、数据过期、隐私越界都要单独写。
  • 写接口的关键是前值,没有前值就没有可证明的回滚。
  • 触发接口默认高风险,技术撤回不等于外部行动撤回。
  • A 不接触发、B 只写草稿目录、C 把通知单列,三张地图的差异就是三种责任分配。
  • 地图还要写「不接什么」,否则边界会在后续版本里被慢慢磨掉。

阅读导航:上一节:7.3 出事了谁负责 · 下一节:8.2 权限面:它能碰哪些数据与动作 。

常见错误与边界

  1. 把系统数量当集成能力。 接了很多系统但全是只读,和接一个系统但能安全写入,是两种完全不同的产品;用数量宣传会误导用户对能力的预期。
  2. 把读接口当无风险。 读可能带来权限过大、数据过期和隐私越界;这些风险不改变业务状态,但会改变合规与信任。
  3. 写接口不留前值。 没有前值的写操作无法证明回滚到了什么状态;「我记得原来是 100」不算回滚能力。
  4. 用技术撤回掩盖触发风险。 消息可以撤回,对方已经采取的行动不能;触发类接口要按外部流程的真实后果定级。
  5. 只画要接的接口。 不接的接口同样要写进地图,否则下一版需求会以「顺手加一个」的方式突破边界。
  6. 把地图当一次性文档。 系统接口、权限和负责人都会变;地图不随版本更新,就会变成一张过期的宣传图。

这一节画的是「能接什么」。下一节要把地图上的每个接口翻到背面,写清楚它到底能碰哪些数据、能做什么动作。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图