从配置驱动到业务原生：基于 AgentScope 的企业级 Agent 开发实践

AI职场先锋
1

1.1 出发点

1.1.1 业务思考

tips：笔者是海外物流业财团队，所以付款流程是非常核心的能力。

最近的一次需求规划讨论，引发了团队对现有产品的深刻反思。产品同事针对我们之前上线的“付款审批 Agent”提出了几个关键问题，直指当前系统的局限性：

首先，Agent 是否具备真正的“记忆”与“智慧”？

目前的审批场景中存在大量重复性的拒绝原因。例如，当因为供应商存在未处理的负数账单而拒绝付款 A 后，几天付款 A+ 再次提交时，Agent 能否记得之前的拒绝原因，并自动检查该问题是否已解决？此外，Agent 能否通过分析审批轨迹，发现像用户 A 那样“一次性清晰反馈”的高效模式，并将这种最佳实践推荐给像用户 B 那样需要多次往复才能通过审批的用户，从而提升整体效率？

其次，交互能否更加个性化？

Agent 能否自动记忆个人的操作习惯，在对话中根据用户平常关注的重点，提供定制化的提示信息？

第三，能否实现运营自助式的快速定制？

我们希望未来在非技术人员的参与下运营同学也能快速定制专属 Agent。例如在“已计费溯源分析”场景中，帮助业务人员理解“为什么这笔费用是这样计算的”。理想状态下应具备快速配置、快速测试、快速上线的能力。

第四，如何确保财务级的操作安全？

财务安全是第一要义，任何写操作都需要苛刻的审批和确认。目前依靠 Prompt 提示模型进行二次确认的做法无法做到百分百拦截。我们需要一种更精准的机制，在自规划、自执行的工作流中，严格控制哪些写操作必须经由用户确认。

最后，是否支持精准的灰度与实验？

系统需要支持针对特定用户群体进行灰度发布，甚至开展 A/B Test，以验证不同策略的效果。

这些问题让我们猛然醒悟：原来我们之前做的只是一个简单的 Chatbox（聊天框），而非真正的智能 Agent。这一认知激发了团队的沉思。在接下来的一个多月里我们采访了其他团队的案例，展开了多轮分析与讨论，最终沉淀出了以下的技术思考方向。

1.1.2 技术思考

1.1.2.1 思考

先问一句：您的高代码长什么样？

我们观察了几个基于 Google ADK、AgentScope等框架构建的 Agent 应用（Java）。它们呈现出惊人的相似结构：

my-agent-app/├── FinanceAgent.java ← new ReActAgent(), 硬编码 prompt├── HRAgent.java ← new ReActAgent(), 硬编码另一个 prompt├── SalesAgent.java ← new ReActAgent(), 又一个 prompt├── FinanceTool.java ← @Tool 注解，直接注册├── HRTool.java ← @Tool 注解，直接注册├── SessionManager.java ← 自建会话管理├── ContextCompressor.java ← 自建上下文压缩├── SSEController.java ← 自建 SSE 流式输出└── ...

每个团队都在做同样的事：

1. 手写 Agent 类：每个应用有 10+、甚至几十个手写 Agent；每个 Agent 对应一个 Java 类，在构造函数里写死 prompt、指定模型、注册 tool。

2. 手建基础设施：会话持久化、上下文压缩、SSE 协议适配、HITL 框架——每个团队各搭一套。

3. 修改需要发版：改个 prompt 、新加一个 SKILL、新增一个MCP tool，要改代码、编译、部署，一个简单的提示词调优变成一次完整的研发流程。

这是一个工程问题，不是 AI 问题。

1.1.2.2 Agent 工程中的典型坏味道

在实际的 Agent 系统落地过程中，由于缺乏统一的工程化规范与平台支撑，代码库中往往充斥着大量重复、僵化且难以维护的实现模式。以下总结了七类典型的“坏味道”，它们不仅增加了研发成本，更引入了严重的稳定性与安全风险。

坏味道 1：样板代码泛滥——“克隆”而非“创建”

现象描述：

每个 Agent 都被实现为一个独立的 Java 类，且每个类都包含完全一致的双重检查锁定（DCL）单例模式、@PostConstruct 初始化逻辑以及硬编码的依赖注入。

java// BAD：每个 Agent 类都复制了 200+ 行的样板代码@Componentpublic class FinanceMasterAgent {    private static volatile LlmAgent instance;    // ... 标准的 DCL getInstance() 实现 ...    @PostConstruct    public void initializeOnStartup() {        AgentRegistry.register(getInstance());    }}

问题分析：

在一个拥有 20+ 个 Agent 的项目中，private static volatile instance 出现了 30+ 次，getInstance() 逻辑被复制了 20+ 次。新增一个 Agent 的本质变成了“复制粘贴 → 修改类名/Prompt/工具列表 → 修正 @DependsOn”。这种“克隆式开发”导致代码冗余度极高，任何底层框架的升级都需要修改所有 Agent 类，维护成本呈线性增长。

坏味道 2：核心配置硬编码——Prompt 迭代受阻

现象描述：

Agent 的三大核心要素——Prompt（指令）、模型参数（Temperature 等）、API Key——全部以 Java 常量或字符串字面量的形式写死在代码中。

java// BAD：500+ 行的业务决策树硬编码在 Java 方法中private static String buildInstruction() {    return """        你是一个专业的财务诊断助手...        ## Act 0: 识别用户输入...        ## Act 1: 诊断问题根因... (30+ 个错误码逻辑)        """;}// BAD：敏感信息与模型配置硬编码public class ModelFactory {    public static final String API_KEY = "sk-xxxxxxxx"; // 甚至提交到了 Git}

问题分析：

  • 研发瓶颈：Prompt 的微调需要经历“改代码 → Code Review → 编译 → 部署”的全流程，周期以周计，而业务对 Prompt 的迭代需求以天计。

  • 安全隐患：API Key 等敏感信息直接暴露在代码仓库中。

  • 灵活性缺失：不同 Agent 的 Temperature 参数散落在各处，无法统一管控或动态调整。

坏味道 3：能力绑定僵化——工具与 Skill 无法动态编排

现象描述：

Agent 拥有的工具集（Tools）和技能（Skills）在代码构建阶段即被固定，通过硬编码列表或 Classpath 路径加载。

java// BAD：工具列表焊死在代码里.tools(List.of(    AgentTool.create(OrderAgent.getInstance()),    AgentTool.create(RefundAgent.getInstance())))// BAD：Skill 路径硬编码Skill diagnosisPlan = factory.createSkillFromResource("skills/diagnosis/diagnosis_plan");

问题分析：

  • 运维困难：若某个 MCP 服务故障需临时下线，或需灰度发布新工具，必须修改代码并重新发版，无法做到运行时热插拔。

  • 耦合度高：上百处散落的能力绑定使得全局视角下的依赖关系难以梳理，阻碍了 Agent 能力的复用与组合。

坏味道 4：MCP 管理缺失——连接泄露与环境混淆

现象描述：

MCP Server 的地址硬编码在代码中，且每次工具调用都重新建立连接，缺乏连接池管理。

java// BAD：预发环境地址硬编码，极易引发生产事故private static final String ORDER_MCP_URL = "https://...pre-region...";// BAD：每次调用都执行 TCP 握手 + 初始化 + 关闭public static String invokeMcpTool(...) {    McpSyncClient client = McpClient.sync(transport).build();    client.initialize();     // ... execute ...    client.closeGracefully();}

问题分析：

  • 高风险配置：硬编码的环境地址（如 pre-）若在发布时未清理，将导致生产环境调用预发服务，引发 P1 级事故。

  • 性能低下：ReAct 循环中频繁短连接导致额外的 100-500ms 延迟，且无熔断机制，高并发下易拖垮 MCP Server。

坏味道 5：身份透传断裂——“上帝视角”的安全隐患

现象描述：

用户身份仅在 Session 层标识，未透传至下游工具或 MCP 调用中，所有操作均以应用服务账号身份执行。

java// BAD：工具调用时操作人为空，或使用应用级认证request.put("creatorNo", ""); ClientMcpRequestAuth auth = ClientMcpRequestAuth.of(serverUrl).generateAuthMaterial(); // 应用身份

问题分析：

  • 审计缺失：无法追踪具体是哪个用户通过 Agent 执行了敏感操作（如创建规则、审批）。

  • 权限失控：缺乏用户粒度的数据隔离与权限控制，违背零信任安全原则。在财务等敏感场景下，这是不可接受的红线问题。

坏味道 6：HITL（人工确认）逻辑分散且脆弱

现象描述：

人工确认逻辑由各个工具自行实现，方式五花八门：有的返回魔术字符串期望 LLM 识别，有的阻塞线程轮询 Redis，有的抛异常中断流程。

java// BAD 6a：依赖 LLM 理解魔术字符串，易陷入死循环return "NEED_CONFIRM: 金额过大，请确认";// BAD 6b：阻塞 Agent 线程等待确认Thread.sleep(1000); // 占用宝贵线程资源

问题分析：

  • 不可靠：LLM 不一定能正确解析停止信号，可能导致死循环或误执行。

  • 资源浪费：阻塞式等待严重消耗服务器线程资源。

  • 体验割裂：不同工具的确认交互不一致，前端适配困难。

  • 覆盖不全：外部 MCP 工具无法嵌入本地 HITL 逻辑，导致高危操作缺乏必要的人工把关。

坏味道 7：配置版本管理缺失——回滚如“考古”

现象描述：

即使配置外置到数据库或配置中心，也缺乏完整的版本快照、审计日志和灰度机制。

问题分析：

  • 回滚困难：Prompt、模型参数、工具集往往联动变更。当出现幻觉或效果下降时，无法一键回滚到“上周的稳定状态”，因为相关配置散落在不同的 Commit 或记录中，恢复过程如同“考古”。

  • 无迹可寻：缺乏“谁在何时改了什么”的审计链路，也无法进行 A/B 测试或灰度发布，导致优化效果无法量化，风险不可控。

总结：上述坏味道反映了 Agent 工程从“原型演示”向“生产系统”演进过程中的典型阵痛。解决之道在于构建统一的 Agent Runtime 平台，将单例管理、配置外置、动态编排、连接池、身份透传、HITL 拦截及版本控制下沉为平台基础能力，让开发者专注于业务逻辑与 Prompt 优化，而非重复造轮子。

1.1.3 结论总结

基于以上的业务思考和技术思考，我们总结出来：

1. 长期记忆需要结构化、持久化、定制化。

2. Agent 自进化需要定义到业务维度，而且要做到自动闭环就需要具体灵活的高定制

3. 真正做到运营可随时定制 Agent，就要零代码配置化接入：新增 Agent/SKILL/MCP 无需编写代码，仅通过页面配置即可实现即时上线，降低使用门槛。

4. hitl 的能力要做到工程级别的精确匹配，就要在框架级别做改造，研发工程级别的 hitl。

5. 灰度策略的定制自然也是工程级别的研发。

我们一开始在希望在内部的各类 AI 平台寻找最优解，后来慢慢发现要做到以上几点，很难依托 AI 技术平台来完成全链路闭环，原因有以下节点：

1. 比如长期记忆的业务定制化，一般平台提供的往往是 RAG 的模式，这往往很难做到精准可控。

2. 再比如运营可用更是难上加难，毕竟 Agent 的配置平台充斥着大量的技术要点，且如何和业务平台精准绑定需要有技术做大量改造。

3. hitl 工程级别的定制更不可能依靠技术平台了。

有了以上的思考，一个难以自控的想法不断在脑海间滋生，我们要基于高代码开发一套完全和业财平台深度融合，快配置、快发布、灰度、自进化的 Agent 平台！

▍1.2 平台建设要点总结

1. 完全由配置驱动的 Agent 运行引擎

    1. 零代码配置化接入：新增 Agent/SKILL/MCP 无需编写代码，仅通过页面配置即可实现即时上线，降低使用门槛。
    2. 轻量级隔离运行时 Runtime：采用“即用即建”机制，运行时动态构建轻量级 Agent 实例外壳。该机制复用了底层的 Skill、SKILL 及 MCP 实例，在确保①资源高效共享、②性能卓越的同时，实现 Agent 会话执行环境的完全隔离，保障稳定性与安全性。

2. 低成本兼容各个生态平台

    1. 通用的 Skill 市场扩展能力：可快速支持其他 Skill 市场
      1. 生产环境：对接 Aone Skill 市场，满足高可用、高标准的生产级需求。
      2. 研发测试：建设 OSS Skill，提供灵活便捷的调试与验证环境，加速迭代周期。

3. 多方位推动 Agent 整体效果进化

    1. 内循环：对话和用户操作轨迹持久化、结构化，定时自动进行偏好和 case 整理。
      1. 支持配置化开启和定制搜集策略
      2. 特点：自闭环
    1. 外循环：用户反馈闭环优化，自动收集会话评价、工具调用成功率与任务完成率等指标，结合人工标注数据驱动 Prompt 与 Skill 策略迭代，让 Agent 越用越准。
      1. 非自动闭环，需要人工介入
    1. A/B 实验与灰度发布：支持多版本 Agent 并行运行与流量切分，通过真实业务数据验证改进效果，确保每次升级都带来可量化的体验提升。
      1. 非自动闭环，需要人工介入

4. 完全垂直的业务 Agent 配置，和业财平台综管打通，实现完全自由化定制页面

    1. 业务语义原生映射：Agent 配置项直接对应业财领域的业务对象（如发票类型、结算主体、费用科目），而非抽象的技术参数，业务人员无需理解底层模型结构即可精准定义 Agent 行为边界。
    2. 综管平台一体化管控：Agent 的创建、发布、权限分配与版本管理全部集成至业财综管后台，与现有组织架构、角色体系及审批流程无缝衔接，确保智能体治理与企业管理体系同频共振。
    3. 零代码页面自定义：支持通过可视化编辑器自由编排对话界面、表单字段、结果展示卡片及操作按钮，不同业务线可独立打造专属交互体验，无需前端开发介入即可快速响应个性化需求。

5. 全链路身份标识和建立细粒度权限控制机制

    1. 在原有系统中，我们基于 Web 层实现了权限管控，采用 ACL、数据标识以及用户白名单等方式进行分层管理。但随着 MCP 逐步下沉至 HSF 接口层，并由 Agent 主导调用链路，传统的 Web 层权限模型已难以覆盖新的调用路径。
2

这个agent好全面，值得学习