本文复盘一次企业内部办公助手 Agent 的落地实践。

这个项目最开始要验证的问题不是“Agent 能不能聊天”，而是：

当 Agent 开始接工具、调系统、执行业务操作时，怎么保证它是受控的。

如果只是问答，问题相对简单。模型答错了，最多是信息不准。

但一旦 Agent 进入内部业务系统，问题就变成了另一类工程问题：

• 谁能调用这个能力；
• 当前用户有没有权限；
• 这个动作只是查询，还是会改变业务状态；
• 写操作执行前是否需要二次确认；
• 执行结果如何回传；
• 失败后如何解释；
• 操作过程能不能被审计和追溯。

所以办公助手不是把后台搬进聊天框，而是把分散后台能力、熟手经验、权限校验、二次确认和业务 workflow 组织成一条可控执行链路。

整体目标可以概括为：

1. 问题背景：能力不缺，缺的是可复用的处理链路

很多内部系统的问题，并不是“没有能力”。

实际情况往往相反：后台、数据平台、配置系统、运营工具已经有很多能力，只是入口分散、字段分散、路径分散。

熟手处理问题很快，不一定是因为点得快，而是因为他知道：

• 去哪个后台查；
• 用哪个入口；
• 参数怎么整理；
• 查完以后下一步看什么；
• 哪些动作需要谨慎确认；
• 哪些结果可以继续联想追问。

新手慢，也不一定是不努力。他只是还没有建立这张隐形地图。

所以办公助手第一阶段要解决的，不是“模型能不能理解一句中文”，而是：

能不能把原来靠人记住的后台路径和操作经验，沉淀成 Agent 可以理解、可以调用、可以确认、可以审计的流程。

这也是内部 Agent 和普通聊天机器人的核心差异。

聊天机器人解决的是信息表达问题。

企业内部 Agent 解决的是业务执行问题。

2. 场景收敛：先验证查询、写操作和生成后执行

第一阶段我们没有追求覆盖所有后台，而是先选了三类场景：

场景	验证问题	关键风险
对象查询	能否沿着同一个对象连续追问	上下文是否稳定
批量操作	写操作能否先确认再执行	是否误执行、漏确认
运营提醒	内容生成后能否进入发送和结果回传	是否停留在“生成文案”

2.1 对象查询：从“找入口”变成“围绕对象连续追问”

对象查询类需求看起来简单，但真实操作里经常不是查一次就结束。

用户可能先查基础信息，再查关联关系，再查状态，再继续判断下一步看什么。过去这些步骤通常分散在不同后台和入口里。

接入办公助手后，用户可以围绕同一个对象连续追问，Agent 负责把背后的查询链路串起来。

这个场景验证的是：Agent 不只是把一次查询包装成自然语言，而是能把“当前对象”作为上下文继续向下走。

2.2 批量操作：写操作必须进入二次确认

批量操作的对比更明显。

传统后台里，一次批量操作可能要填写对象、操作项、有效期、开关、备注等字段。它看起来只是一次提交，但实际是一条完整操作链路：

• 对象整理；
• 参数填写；
• 操作项确认；
• 生效范围确认；
• 执行；
• 结果汇总。

Agent 加持后的变化不是“少点几个按钮”，而是把这条链路拆成了“模型整理 + 人确认 + 系统执行”。

用户先用一句话描述目标，Agent 整理操作对象、操作内容和执行参数，进入二次确认。用户确认后再执行，并返回结果汇总。

这里的关键点是：

模型可以帮助整理操作意图，但不能把“用户想做什么”直接等同于“用户已经确认执行”。

所以写操作必须显式进入 confirmation。

2.3 生成后执行：不要停在“AI 写文案”

第三类场景是运营提醒类文案辅助。

这个场景很容易被误解成“让 AI 写一段文案”。但真正进入业务系统后，问题不是生成文案，而是生成之后怎么办。

原流程需要在后台表单里填写分类、对象、标题、内容、提醒等级等字段。

Agent 加持后，用户先让办公助手基于对象状态生成提醒文案。用户确认文案后，Agent 再进入发送前确认。确认后才执行发送。发送完成后，还可以继续追问这个对象的其他信息。

这类场景验证的是：Agent 不能停留在“生成内容”，而要能把生成、确认、执行和结果回传串起来。

3. 架构拆分：理解、编排和执行不要混在一起

为了避免办公助手变成一个失控的万能入口，我们在架构上把“理解、编排、执行”拆开。

整体链路可以简化成：

各层职责大致如下：

层级	职责
用户入口	承接消息、用户身份和会话入口
通用 Agent 平台	理解意图、维护会话、加载 Skill、决定是否调用工具
Skill / Workflow	组织业务知识、任务流程、工具描述和确认逻辑
CLI / Tool	承接可执行的原子能力或流程入口
Gateway	鉴权、协议适配、二次确认、审计和下游调用
业务系统	提供被授权、可约束、可追踪的业务能力

这里最重要的一点，是不要让 Agent 直接面对所有内部系统。

Agent 擅长理解自然语言、组织上下文、判断下一步动作，但它不应该绕过权限系统，不应该直接拼内部接口，也不应该对高风险操作拥有默认执行权。

4. Gateway：不是转发层，而是受控执行层

Gateway 在这个设计里不是简单的 HTTP 转发层。

它更像 Agent 和业务系统之间的受控执行层，需要回答几个问题：

• 当前用户有没有权限使用这个能力；
• 当前动作是否需要二次确认；
• 下游系统协议是否需要适配；
• 结果如何被标准化返回给 Agent；
• 操作过程是否需要记录审计日志；
• 权限失败、业务失败、参数错误分别如何解释。

一个简化后的执行流程大概是：

1. Agent 根据 Skill 判断需要调用某个 Tool。
2. Tool 请求进入 Gateway。
3. Gateway 根据身份信息做用户识别。
4. Gateway 根据 permission_scope 做权限校验。
5. 如果是只读操作，校验通过后直接调用下游。
6. 如果是写操作，先生成 preview 或 confirmation。
7. 用户确认后，Gateway 再执行真实写操作。
8. Gateway 将执行结果、失败原因或确认状态标准化返回给 Agent。

这层的价值在于：能力可以继续扩展，但扩展不是无边界的。

每新增一个能力，都要先被描述、授权、接入、确认和审计，而不是临时把一个后台接口塞给模型。

5. Skill：不是说明文档，而是业务能力的组织方式

办公助手里另一个关键点是 Skill。

很多人第一次听到 Skill，容易把它理解成“给模型看的说明文档”。但在这个项目里，Skill 更像业务能力的组织方式。

如果把所有能力写进一份大文档，模型会遇到两个问题：

• 上下文膨胀，能力越多，命中越不稳定；
• 业务边界模糊，查询、写操作、流程任务混在一起，后续维护困难。

所以办公助手没有简单按后台系统拆能力，而是尽量按用户问题和业务对象拆。

可以简单理解成几层：

• 根 Skill 做总分诊，先判断用户问题的大方向；
• 领域文档判断具体业务域，缩小上下文范围；
• Tool 承接单个原子能力；
• Workflow 承接多步任务闭环；
• 写操作再走 confirmation。

5.1 根 Skill 先做路由，不要塞满所有工具

根 Skill 不负责塞满所有工具，而是先做路由，让模型按任务选择当前需要加载的领域能力。

一个简化示意如下：

## Loading Order

1. Read this root file to understand runtime rules and domain routing.
2. Pick one domain according to the user's intent:
   - domains/object/DOMAIN.md: object query and related status.
   - domains/ops/DOMAIN.md: confirmation-based write operations.
   - domains/message/DOMAIN.md: message generation and sending flow.
3. Read the domain's referenced tools/*.yaml file.
4. If the matched tool has `requires_confirmation: true`,
   read common/confirmation.md.
5. If the gateway returns an auth error,
   read common/auth-errors.md.

这样做的好处是，模型每次只读当前任务需要的那条路径，其他领域的 Tool 不进入上下文。

5.2 只读 Tool：描述清楚输入输出和权限范围

对于只读查询类能力，Tool 更像一个清晰的原子能力说明。

tools:
  - name: query_object_profile
    description: Query object profile through the gateway.
    permission_scope: object.profile.read
    gateway_route: object.profile.query
    requires_confirmation: false
    request:
      type: object
      required: [object_id]
      properties:
        object_id:
          type: string
          description: Business object id.
    response:
      data:
        type: object
        properties:
          object_id:
            type: string
          display_name:
            type: string
          status:
            type: string

这里要明确几件事：

• Tool 的职责要足够窄；
• request / response 要结构化；
• permission_scope 要明确；
• 只读操作不需要 confirmation；
• 返回结果要方便 Agent 继续组织回答或进入下一步。

5.3 写 Tool：必须显式标记 confirmation

写操作则必须显式标记需要确认。

这个字段很小，但它决定了 Agent 能不能从“会调工具”走向“受控执行”。

tools:
  - name: execute_controlled_action
    description: Execute a controlled action after human confirmation.
    permission_scope: object.action.write
    gateway_route: object.action.execute
    requires_confirmation: true
    request:
      type: object
      required: [object_ids, action_type, params]
      properties:
        object_ids:
          type: array
          items:
            type: string
          description: Business object ids.
        action_type:
          type: string
          description: Controlled action type.
        params:
          type: object
          description: Action parameters.

读写 Tool 的差别，表面上只是 requires_confirmation 这个字段。

但工程上的意义很大：它把“模型决定做什么”和“人确认是否执行”拆开了，也让 Gateway 可以统一处理确认、审计和结果回传。

5.4 confirmation 流程本身也要被写清楚

确认流程不能只靠约定。

否则模型很容易跳过关键步骤，直接把“用户想做什么”误当成“用户已经确认执行”。

1. Call execute with --requires-confirmation.
2. Show the returned preview to the human operator.
3. If approved, call confirm with the returned confirm_id.
4. Return execution result and summary to the user.

这也是企业内部 Agent 和普通工具调用 Demo 的区别：Demo 里调通接口就结束了，真实业务里要考虑权限、确认、失败、审计和追溯。

6. Tool 解决单步动作，Workflow 才解决一件事

办公助手落地过程中，一个很重要的判断是：Tool 和 Workflow 不能混在一起。

Tool 解决的是“能不能做一个动作”。

比如查一个对象、取一个状态、生成一段内容、触发一次通知。

但真实业务里，用户要的往往不是一个动作，而是“把这件事处理完”。

这就需要 Workflow。

类型	解决什么	示例
Tool	一个原子动作	查询对象、获取状态、生成内容、触发通知
Workflow	一个多步任务闭环	批量操作、提醒发送、问题排查、上传后校验

以批量操作为例，它不是一个 execute 就能解释清楚的动作。

一个相对完整的流程可能是：

parse intent
  -> resolve objects
  -> handle ambiguity
  -> build action preview
  -> ask human confirmation
  -> execute
  -> return summary

如果没有 Workflow，Agent 很容易变成“会调很多工具，但不会把事做完”。

这也是很多内部 AI 助手容易卡住的地方：单点能力看起来很多，真正处理问题时却断在中间。

办公助手要补的，就是这条中间链路。

7. 哪些场景不适合第一阶段接入 Agent

企业内部 Agent 很容易陷入一个诱惑：

既然能接工具，那是不是应该把所有接口都接进去？

我们的判断是，不应该。

至少在第一阶段，不应该。

不适合直接接入的场景包括：

场景	原因
强交互场景	过程依赖大量用户即时反馈，不适合封装成一次工具调用
长事务场景	需要完整状态管理和恢复机制
复杂状态机场景	状态转换必须由业务系统提供严格约束
重业务上下文授权场景	单靠通用 Gateway 难以表达完整授权语义
高风险不可逆写操作	一旦误执行，影响真实业务流程

原因不是技术做不到，而是风险收益比不合适。

普通问答答错了，最多是信息不准；执行动作出错，就可能影响真实业务流程。

所以更稳妥的路线是：

先接高频、常用、可闭环、风险可控的场景，让 Agent 稳定完成真实任务，再逐步扩大边界。

8. 可复用清单：内部 Agent 接业务系统前先问这些问题

这次实践沉淀下来，至少有一组检查项可以复用。

8.1 能力接入前

• 这个能力是查询还是写操作；
• 是否高频、常用、可闭环；
• 是否需要二次确认；
• 是否已有明确权限模型；
• 是否能提供结构化输入输出；
• 是否有可解释的失败原因；
• 是否能记录审计日志。

8.2 Skill 设计时

• 是否按用户问题或业务对象拆分，而不是简单按后台系统堆工具；
• 根 Skill 是否只做路由；
• 领域 Skill 是否控制上下文范围；
• Tool 是否足够原子；
• Workflow 是否描述完整任务闭环；
• 写操作是否显式声明 requires_confirmation；
• 权限失败、参数缺失、下游失败是否有独立处理路径。

8.3 Gateway 设计时

• 身份信息从哪里来；
• 权限校验在哪一层做；
• permission_scope 如何和业务权限模型映射；
• 写操作 preview 如何生成；
• confirm_id 如何管理；
• 执行结果如何标准化；
• 审计信息记录哪些字段；
• 下游协议差异在哪里适配。

总结

办公助手这个项目验证的不是“又做了一个 AI 应用”。

它更像是自研 Agent 平台进入真实业务系统的第一站。

这次实践给我们的判断是：

企业内部 Agent 的价值，不在于让模型拥有更多后台能力，而在于把后台能力组织成更稳定、更安全、更可复用的业务流程。

Agent 从聊天走向执行，中间隔着的不是一句 prompt。

而是一整套工程机制：Skill 分层、Tool 描述、Workflow 编排、Gateway 鉴权、二次确认、审计记录和边界控制。

如果只把后台接口塞给模型，能力越多，风险越大。

如果把能力放进受控流程里，Agent 才有机会从“能回答”走向“能办事”。

花椒技术交流群

还在孤军研究 AI 工程化、AI 编程、Agent 落地，没人同行交流、没人拆解实战？

这里汇聚一线技术从业者，专注代码评审、企业内部 AI 助手真实实战落地。

想紧跟 AI 前沿动态、交流工程落地经验、少走踩坑弯路，欢迎直接加入「花椒技术交流群」。

群内专属福利拉满：每日精选研发向 AI 行业日报、文章独家延伸资料、文中未展开的技术细节，全部同步共享。

如果群过期关注公众号 花椒技术，私信回复「交流群」获取最新入群二维码。