企业 AI Agent 落地第一课:AI 说"已发布",谁来证明是谁让它发的
上线之后,Agent 不再是一个接口,而是一个会自己定时跑、会替人做决定、会写外部系统的执行者。
所以第一课不是提示词,而是那条"谁授权、谁执行、谁留痕"的证明链。
一条公告,问出三个答不上来的问题
先说一个很常见的场景。
周一早上,运营群里出现一条公告:"第三季度产品升级通知",措辞得体,格式规整。有人问了一句:谁发的?
查了一圈,答案不太好拼:
- 不是人发的,是上周配的一个定时任务;
- 配置任务的同事,上个月已经离职;
- 中途需要人工确认的那一步,是管理员代点的"允许";
- 系统里只记了"发布成功",没记是谁授权、谁确认、为什么放行。
内容没错,流程也没报错。但这条链路里,没有一个环节能证明"是谁让它发的"。
这就是企业 Agent 落地最容易低估的一道坎。Demo 阶段它是个"更聪明的接口",上线之后它是一个会自己跑、会代别人做决定、会写外部系统的执行者。
第一课要立起来的,是这条证明链上的五件事:
- 谁让它干的?(身份)
- 它凭什么能干?(权限)
- 事后凭什么证明?(审计)
- 数据删得掉、找得回吗?(生命周期)
- 没人看着的时候坏了怎么办?(失败)
一、身份契约:每一轮都要能回答"谁让它干的"
同步代码里,身份是"当前线程的状态"。请求进来,Sa-Token 拦截器解析 token,业务代码里 LoginHelper.getUserId() 随时能取到。
但 Agent 不是同步代码。它会切线程、走响应式调度、等人工确认、被定时任务触发。一旦换线程,ThreadLocal 就是空的。
做法只有一句:在请求线程里取一次,之后把身份当入参传下去。
java
Long userId = LoginHelper.getUserId(); // 只在请求线程出现
RuntimeContext ctx = RuntimeContext.builder() // 跨线程由框架保证
.userId(String.valueOf(userId))
.sessionId(String.valueOf(sessionId))
.build();进入 Agent 之后,候选专家、会话资源、记忆归属、知识库可见范围,全部从 ctx.userId() 算,不再回头读 LoginHelper。评审清单里加一条:异步分支不允许出现 LoginHelper。
三处最容易漏:
人工确认的恢复段。 用户点"允许"时,发来的是一个新请求,它自带登录态。但业务要的是原始会话的归属人,不是"谁点的确认"。管理员代确认、共享会话、渠道消息,这三个值可能不一样。恢复时用暂存的 pending.userId(),并标记 resumed = true,否则收尾会把首段的路由记录覆盖掉;确认接口只校验"当前登录人有没有权限处理这条待确认"。
定时任务。 没有人在线,也没有 token。身份来自任务定义:创建人、所属部门、系统账号。创建人离职后任务还跑不跑,是产品规则,必须写在页面上,而不是让代码碰巧跑着。
渠道消息。 身份来自渠道侧的用户映射。映射不上就拒绝,不要退化成"匿名用户"。
判据:单测构造一个 userId 就能跑完整链路,不需要起 Web 环境;每行日志都有 userId 与 sessionId。
二、权限契约:它凭什么能干
两层权限,别混在一起。
Sa-Token 管接口和菜单:这个人能不能访问 /ai/agent/task、能不能看到某个配置页。这是人的属性,登录时确定。
Agent 管工具执行:这次调用能不能做、要不要人工确认、无人值守是否放行。这是这次执行的属性,按来源(对话 / 定时任务 / 渠道)和工具类型重算。
混用的典型写法,是在工具实现里查菜单权限来决定能不能发公告。结果同一个人从对话页能发、从定时任务发不了,规则没人说得清。
BizBuddy 的默认策略是:
- 未命中显式规则的工具一律需要人工确认(
permission-mode=DEFAULT); - 写工具按
ai_tool.tool_type判定,不靠智能体配置"记得别调写工具"; - 无人值守链路(定时任务 / 渠道)的写操作代码级拒绝,只放行白名单里的工具编码;默认白名单只有内置的「平台运行日报」写入工具,它按日期 upsert、本身幂等;
- 待确认调用有有效期(默认 30 分钟),超时重新发起,不留悬挂状态。
一个真实的教训:强制拒绝上线后,平台日报连续几天没有落库。只读汇总工具正常,写工具每次都是 Permission denied by rules。把 write_daily_digest 放进默认白名单后,"开箱即用"才成立。安全默认值不是越严越好,而是严到能解释、能验证。
判据:同一个工具在对话、任务、渠道三种来源下的行为都能解释;每次决策都能在权限决策日志里查到原因。
三、审计契约:事后凭什么证明
标题里的那句话,最终要靠审计回答。
"已发布"不是终点。审计要能还原三件事:谁授权、谁执行、依据是什么。
平台留了六类痕迹:会话消息、工具调用、权限决策、链路追踪、编排运行、平台运行日报。排障时按问题维度查:
- 这次为什么被拦下 → 权限决策日志,含命中规则与理由;
- 这个工具为什么慢 → 工具调用明细;
- 这一轮为什么降级 → 编排运行与链路追踪;
- 定时任务为什么没跑 → 任务执行记录与最后更新时间。
两处最容易做错:
审计里的 user_id 必须从上下文对象取。 如果来自 LoginHelper,异步写入时就是空的。串数据比报错更难查,而且查出来时往往已经过了很久。
确认记录要区分"确认人"和"归属人"。 只记"管理员点了允许",等于没记;要能查到"管理员替哪个用户确认了哪条待办"。HITL 的价值不只是拦住一次写操作,更是留下一条可回放的决策记录。
留存也要定下来:审计默认保留 180 天,每日 03:30 自动清理,多副本抢锁只跑一个实例。清理不含会话正文——正文是业务数据,按会话生命周期处理。
判据:随便挑一条 AI 写过的公告,能从"任务定义 → 身份 → 权限决策 → 工具调用 → 产物"完整串起来。
四、数据契约:删得掉、找得回
Agent 会持续产生数据:会话状态、附件、上下文、记忆。没有契约,它们只有一个默认行为——一直涨。
而且"涨"往往不是线性的。一张图转成 Base64 进模型上下文是几十万字符量级,如果每轮都把历史图片全量下发,会话状态和请求体会随轮次一起膨胀。
BizBuddy 的做法是给每类数据写清四件事:归属、上限、期限、退路。
| 数据 | 归属 | 上限 | 期限与退路 |
|---|---|---|---|
| 会话状态 | 用户 + 会话 | Redis 单实例 512MB 上限,noeviction;健康自检 70% 告警、85% 失败 | 闲置 30 天自动过期;删会话即清 |
| 附件 | 会话附件 | 单图上传 512KB;装配时最长边压到 1568px、质量 0.85 | OSS 原图保留;带 EXIF 方向的原图跳过压缩,避免手机照片横竖颠倒 |
| 会话上下文 | 用户 + 会话 | 超过 50 条或 8 万 token 触发摘要,保留最近 20 条;超大工具结果超过 8 万字符落盘,只回填首尾预览 | 压缩前落盘留痕 |
| 长期记忆 | 用户 | 注入上下文 8000 token;合并时读流水 4000 token | 流水 90 天、归档 365 天、会话日志 180 天;删除前自动留 PRE_DELETE 快照,版本可恢复 |
| 数据库结构 | 版本号 | Flyway V1 基线冻结,V2+ 增量,双方言同步 | 升级前备份;迁移失败即启动失败 |
两个细节值得单独说。
历史图片必须裁剪。 现在的策略是只保留最近 2 条含图片的消息,更早的图片替换成文本占位「历史图片已省略,可在会话附件中查看原图」。会话记录和 OSS 原图不受影响,模型也不会因为十轮前的一张截图,每轮都多背几十万字符。
迁移一旦跑过,就当"已发布"。 我们改过一次已经执行过的 MySQL V2 迁移,结果存量数据卷上的校验和不匹配,应用直接启动失败——Validate failed: Migrations have failed validation。处理方式是 flyway repair,或者删掉那条记录让幂等脚本重跑。这不是 Flyway 严格,而是它替你把"悄悄改历史"拦住了。
判据:随便挑一个用户、一个会话、一份记忆,你能说清它存在哪、上限多少、留多久、删了怎么恢复。
五、失败契约:没人看着的时候,坏了怎么办
企业系统不怕慢,怕的是"错了但没人知道"。
Agent 的失败形态比普通接口多:模型超时、工具抛错、编排停在中途、人工确认没人点、依赖服务降级。这些都要有明确出口。
- 中断任务回收:编排运行、文档解析、向量化、定时任务执行,超过 60 分钟没有更新就判定为已中断并回收;每 5 分钟扫描一次,按最后更新时间判断,避免多副本误伤正在跑的任务。
- 等待有上限:人工确认默认 30 分钟过期;对话消息接口 60 秒 20 次限流;流式连接超时单独配置,不沿用普通请求的默认值。
- 依赖可降级:重排模型未配密钥、超时或返回异常,退回向量原序;BM25 索引未就绪,自动退回纯向量检索。降级不是静默,日志里能查到原因。
- 容量不静默:Redis 达到上限时
noeviction,宁可写入失败,也不淘汰登录态;健康自检按 70% / 85% 两级报出水位。 - 配置 fail-fast:JWT 秘钥、接口加密密钥对、模型密钥加密口令、数据库与 Redis 口令,命中出厂示例值就拒绝启动。非生产环境可以显式降级为告警,生产环境没有这个逃生口。
- 回归可复跑:20 层 HTTP 端到端用例,覆盖鉴权边界、限流、停止生成、人工确认拒绝、无人值守拒绝、渠道验签与出站。对着本地已运行的栈直接跑,不是"提供测试框架"。
判据:拔掉任意一个依赖,你能提前说出系统是"变慢"还是"报错",以及前端会看到什么。
落地顺序:先做什么,后做什么
不用一上来就搭全套。按这个顺序推进,返工最少:
- 先把会写外部世界的动作列全:发公告、建工单、改配置、发消息。只读工具可以后补,写工具必须先有清单。
- 定身份来源:对话、定时任务、渠道各自由谁代表,人工确认恢复时用谁的 ID。
- 给每个写动作定权限与确认策略:谁能触发、是否需要人工确认、无人值守时是否放行。
- 给每类数据定归属、上限、期限、退路,并确认审计能还原"谁授权、谁执行"。
- 设计失败出口:超时、重试、回收、降级、告警,逐条落到代码而不是文档。
- 用端到端用例固化:把上面五条变成可重复执行的断言,每次发版前跑一遍。
上线前,先回答这 12 个问题
- 这次执行的身份是谁?人离职后,他创建的任务还跑不跑?
- 工具被异步调用时,身份从哪来?
- 人工确认的恢复段,用的是确认人还是会话归属人?
- 审计能回答"这条公告是谁授权、谁执行、依据是什么"吗?
- 权限决策、工具调用、编排运行这三类日志,能按同一次请求串起来吗?
- 哪些动作属于"写"?写动作在对话、任务、渠道下分别是什么策略?
- 无人值守时,写工具靠什么被拒绝?漏配的后果是拒绝还是执行?
- 会话状态存在哪?上限多少?谁来清理?
- 历史图片会不会每轮重复下发?附件原图还能找回吗?
- 记忆删了能恢复吗?流水、归档、会话日志各留多久?
- 数据库升级怎么执行?迁移失败时应用是启动还是拒绝启动?
- Redis 打满时,登录态会被淘汰吗?谁会收到告警?
十二个问题都能答上来,再谈提示词优化,才不亏。
收尾
"已发布"三个字,应该是系统里最容易被证明的三个字。
Agent 的能力上限由模型决定,但能不能上线,由这条证明链决定:身份能追到人,权限能说清依据,审计能还原过程,数据能删能恢复,失败能被发现。
这五件事都不复杂,难的是在写第一行工具代码之前就把它们定下来。定下来之后,模型换一代、提示词改几版,平台仍然是那个能解释、拦得住、收得回的平台。
关于 BizBuddy
BizBuddy 是一个全量开源的企业级智能体平台(MIT License):开源中后台底座(Spring Boot 4.1.1 / JDK 21)做底座,AgentScope Java Harness 做智能体内核,纯 Java 全栈、不含 Python,权限、审计、配额、多渠道接入等能力全部随仓库开源。
- 代码仓库:https://gitee.com/zl3624/biz-buddy
- 双栈部署:PostgreSQL 14 与 MySQL 8.0 等价交付,
deploy/deploy-pg与deploy/deploy-mysql可直接起 - 可复跑的 20 层 HTTP 端到端用例 + Playwright UI 用例都在仓库里
欢迎 Star、Issue 与共建。