这篇文章不是“我发现了一个好工具”而是源于我在业务系统 AI 接入中反复遇到的同一个需求现有系统有数据、有接口要“加 AI 能力”但没有人想推倒重来。这个系列前几篇讲了生产级 Agent 的架构、能力分层、评测体系这篇讲一个更实际的问题这些能力怎么接到一个已经跑了几年的系统上。一、老系统加 Agent难在哪你手上有一个跑了三五年的工单系统、审批系统或管理平台。数据都在、接口也有现在要“加个 AI 能力”。看起来有三条路但每条都有坑从编排框架搭。LangGraph、CrewAI 当然可以包装现有 API但它们更偏向解决流程编排。身份接入、工具权限、审批恢复、审计留痕、事件协议和运维页面通常仍要由项目自行建设。只包一层 RAG。接个向量库用户问问题Agent 检索文档回答。这条路能快速出 Demo但单独增加 RAG 只能解决知识检索不能覆盖“创建工单”“审批变更”这类受权限控制的业务写入。之前的一篇生产级 Agent 的四层能力里讨论过RAG 只是 Agent 能力的一层不是全部。在现有系统里硬改。往老代码里塞 AI 调用逻辑。短期能跑长期是灾难。权限、审批、审计这些东西跟业务代码搅在一起改一个动一片。三条路的共同问题你需要的不是重新建一个系统是在现有系统旁边加一层桥。二、框架设计为什么做成这样AgentBridge 的设计从一个问题出发怎么让 AI 调用你的业务接口同时不要求侵入式改造已有系统的核心代码你写插件平台管剩下的核心思路是插件化。你的系统有 API你编写或让 AI 编程助手生成一个插件告诉平台”这些 API 能做什么、需要什么参数、返回什么格式”。这不要求把 AI 逻辑塞回老系统但仍需要完成业务接口映射、权限声明和插件测试。剩下的事对话管理、权限校验、审批流程、审计日志、模型路由由平台处理。代码结构上三层边界清晰packages/core/ 可复用运行时生命周期、协议、适配器 apps/api/ 服务入口路由、组装根 apps/api/domains/ 你的业务插件一个目录一个能力插件不碰平台内部平台不碰业务逻辑。组装根lifespan.py负责把两者接在一起。平台与插件按明确契约演进升级时仍应以插件测试验证兼容性而不是假定永远零成本兼容。接口契约按用途分组便于接入方核对 JSON/SSE、审批和管理接口而不是依赖一段不可追踪的自然语言约定。权限两层设计很多 Agent 项目只做了一层权限在工具执行前检查一次。AgentBridge 做了两层第一层预过滤。PolicyEngine.filter_tools()在 LLM 生成回复之前就把用户没权限的工具移除。LLM 根本看不到这些工具自然也不会尝试调用。这比事后拒绝更安全模型不会在推理过程中产生”我应该调用某个接口但被拒绝了”的幻觉。第二层调用时鉴权。tool_guard在工具实际执行前再查一次权限。无论调用来自模型规划、直接调用还是权限状态在运行过程中发生变化执行边界都会重新判断。工具通过元数据声明自己需要什么权限attach_tool_meta(required_permissions[workorder:read])def list_work_orders(query, tenant_id, run_context):...写操作审批流 幂等查询是安全的写操作不是。AgentBridge 对写操作做了完整的审批生命周期工具命中审批策略 → 图暂停生成审批卡推给用户用户看到草稿预览工单标题、优先级、指派人用户确认 →ApprovalResumeExecutor在执行租约内完成操作approval_id作为幂等键重复审批不会创建重复记录审批超时 → 自动过期图恢复时不会误执行这套机制保证了Agent 可以生成操作建议但最终决定权在人。02 里讨论的 Human-in-the-Loop在这里落地成了具体的代码。模型和知识库端口-适配器模式AgentBridge 不绑定任何特定的模型或向量库。所有外部依赖都通过协议接入模型层。AliasLLMGateway通过default、fast等逻辑别名隔离业务代码与具体模型。默认配置可以让多个别名指向同一个模型也可以由管理员按场景配置不同模型。模型 API Key 加密存储且不会返回浏览器业务代码不需要感知具体厂商。知识层。Retriever协议支持fake、langchain_pgLangChain pgvector、external对接外部 RAG 服务和rag_agent_pg只读 RAG-Agent PostgreSQL 参考接入。langchain_pg和external按租户传递、校验检索上下文rag_agent_pg目前只用于固定演示租户不能把它当作通用多租户 RAG 方案。这跟 01 里讨论的多模型路由策略是同一个思路简单任务用快模型复杂任务用强模型代码级别不感知具体厂商。可观测性全链路每次工具调用包括被拒绝的都会记录到审计日志。EventLog 保存事件流RunStore 追踪每次对话的状态平台同时提供 Prometheus 指标端点。OpenTelemetry 已预留 span 接入点但 v1.0.0 中仍是占位实现需要接入具体 SDK 和 exporter 后才能形成真实链路追踪。审计和可观测从设计之初就是平台的一等公民不是事后补的。运维管控接入之后谁来管接入 Agent 能力不只是写个插件就完了。生产环境需要持续运营AgentBridge 的后台管理覆盖了几个关键点模型管理。管理员可以在管理页面配置模型API Base、模型名、温度API Key 加密存储浏览器端看不到明文。模型通过逻辑别名接入别名如何映射由部署者决定切换模型不需要修改业务插件代码。Prompt 管理。管理中心可以查看、编辑和发布已注册的 Prompt。平台采用“线上发布优先、插件文件兜底”的分层策略并记录名称、版本和来源。当前黄金案例已经把work_order_ops.planner接入真实模型规划流程默认离线模型桩用于确定性验证不以 Prompt 调优效果作为演示目标。审计与用量。每次工具调用包括被拒绝的留痕当前可导出脱敏的审计 JSONL并在运行记录中按状态、路由和时间排查。Token 用量提供按模型和租户聚合的基础数据计费、结算与账单仍应由业务侧系统完成。这些管理能力随源码提供不需要业务插件重复实现。它们服务于自托管单机实例的日常管理不等同于云托管 Studio也不代表默认具备多机高可用能力。把这些串起来架构是这样的仓库自带的 Verification Workbench 面向开发者验证平台链路不是客户业务前端。正式接入时业务前端消费标准 JSON/SSE 事件AgentBridge 处理中间的治理逻辑原有系统继续负责业务数据与业务规则。三、不只有对话四种接入模式01 里讨论过”大多数场景用 Workflow不要迷信纯 Agent Loop”。AgentBridge 的插件体系把这四种模式都覆盖了你可以根据自己的场景选择模式 A只读查询用户说“查一下本月工单”Agent 调用list_work_orders查询数据库动态生成表格和 ECharts 图表。返回的不是纯文本而是结构化的 SSE 事件。自带工作台已经实现work_order_ops的表格和图表渲染自定义插件仍需在自己的业务前端为x.domain.*事件注册对应的展示逻辑。这解决了 01 里提到的”输出格式控制”问题Agent 不是只能回文字。验证工作台提供预定义的测试场景每个用例标注了验证问题和预期效果。运行后在同一页面查看业务展示表格、图表、引用、审批卡和平台链路证据。模式 B知识检索用户说“工单处理规范是什么”Agent 通过Retriever检索知识库返回答案时附带引用来源文档名、章节锚点、跳转链接。结果可以携带评分和来源便于追溯而不是只返回一段无法核对的答案。混合检索和 Rerank 可以作为具体Retriever适配器的能力接入AgentBridge 负责把检索 Port 注入业务插件并不把某一种检索算法写死在核心里。模式 C结构化输出台账预览、多维统计、审批单格式化。AgentBridge 的 SSE 扩展事件支持x.domain.name模式插件写入结构化扩展片段由平台生命周期统一按序推送前端再按事件类型渲染不同组件。模式 D审批写入用户说”帮我创建一个工单”Agent 生成草稿标题、优先级、指派人推送给用户确认。用户点”批准”系统幂等执行。如果网络抖动导致重复提交approval_id保证不会创建两条记录。这就是 02 里 Human-in-the-Loop 的落地形态。截图停留在等待人工决定的状态没有执行批准也没有写入新工单。四、用 AI 写插件Vibe Coding 接入前三篇没覆盖的一个话题是接入 Agent 能力这件事本身也可以让 AI 编程助手参与。它要做的不是凭空生成业务而是把现有接口映射成模型可调用的 Tools再按业务需求设计路由、权限、输出和测试。AgentBridge 的SKILL.md是一份给 AI 编程助手看的接入指南。你打开 Cursor、Codex 或 Claude Code让它先读 AgentBridge 仓库中的AGENTS.md、SKILL.md和参考插件如果现有业务系统也在可访问的工作区再让它读取接口代码。然后描述你的业务需求我的系统政务工单管理平台有 REST API 我的接口/api/workorders查询、/api/workorders创建、/api/knowledge检索 用户会问本月有哪些待处理工单帮我创建一个XX类型的工单AI 助手读完接入文档和 5 条 MUST 规则后从_scaffold/创建插件主要修改四个文件tools.py工具定义查询接口、创建接口state.py状态类型声明graph.pyLangGraph 图构建bootstrap.py注册入口最后还要在apps/api/domains/bootstrap.py登记这个插件并补充DOMAIN_META_MAP这样平台和调试台才能发现新的 route。一个真实的工具接入点以仓库自带的work_order_ops为例查询工具不会自己创建数据库连接而是读取组装根已经注入的data_source租户条件来自经过验证的RunContexttool async def list_work_orders(config: Annotated[RunnableConfig, InjectedToolArg],)-list[dict[str, Any]]:Return display-safe work ordersforthe current tenant. ctxget_run_context(config)sourcectx.metadata.get(data_source)ifsourceis None:return[]rowsawait source.query(SELECT * FROM work_orders WHERE tenant_id $1, ctx.tenant_id,)return[{key: row.get(key)forkeyinSAFE_ORDER_FIELDS}forrowinrows]list_work_ordersattach_tool_meta(list_work_orders,required_permissions[workorder:read],)这里有三个关键点Tool 只是现有业务能力的适配层不承载数据库连接配置查询始终带当前租户不接受模型随意指定租户workorder:read不只是执行前检查还决定这个工具能否进入模型可见列表。注册时再把工具、流程图和输入构造器挂到对应 routedef register(graphs, tools, input_builders, **kwargs): tools.register(work_order_ops,[list_work_orders])graphs.register(work_order_ops, build_work_order_ops_graph)input_builders.register(work_order_ops, _build_input)真实插件通常还会注册知识检索、结构化事件和版本化审批动作并用 API 测试验证无权限工具不可见、跨租户失败以及重复审批不重复写入。接入的工作量主要集中在业务映射和验收而不是重建平台公共能力。5 条 MUST 规则守住架构边界不直接导入适配器、不在插件里推 SSE、不在核心层硬编码业务插件名、适配器接线只在lifespan.py、权限必须声明并双检。这降低了接入门槛。不需要理解平台内部的 30 个协议和适配器怎么配合只需要告诉 AI”我的系统有什么”。插件调试台面向开发者验证接入结果同一页面可以编辑请求、观察实时事件、检查工具调用和导出坏案例不是面向最终客户的业务前端。五、跑起来三步部署macOS / Linuxgitclone https://github.com/Foamtor/AgentBridge.gitcdAgentBridgecp.env.example .envdockercompose up--buildWindows PowerShellgitclone https://github.com/Foamtor/AgentBridge.git Set-Location AgentBridge Copy-Item .env.example .envdockercompose up--build默认体验不需要 API Key、不需要预先准备外部数据库也不依赖云服务。首次启动后从docker compose logs api取得仅显示一次的admin初始密码登录后必须先设置新密码。默认 Compose 被设计为使用 PostgreSQL 合成业务数据、离线模型桩和 fake knowledge覆盖查询、图表、草稿、审批与幂等创建。项目自带的work_order_ops参考实现演示了完整的业务闭环查工单用户问”本月有哪些待处理工单”Agent 查询数据库返回表格 按状态分布的柱状图。查知识用户问”工单处理有什么规范”Agent 检索知识库返回带引用来源的答案。创建工单用户说”帮我创建一个 XX 类型的工单”Agent 生成草稿预览标题、优先级、指派人、台账摘要用户确认后执行。它不是一组写死在前端的展示卡片默认配置中的查询面向 PostgreSQL 合成工单数据审批使用平台生命周期创建操作以approval_id保证幂等。但它仍是参考业务插件不是可直接交付给某个行业的成品系统。你可以把它当模板按自己的数据模型和接口实现新的插件。需要说明的是Python/API/Core/Web 测试、Web 生产构建、架构检查和docker compose config --quiet已作为 v1.0.0 发布门禁通过真实 Docker Compose golden smoke 尚未在我的发布环境完成。不同机器的 Docker Engine、镜像网络和数据卷条件不同正式部署前仍应按docs/deploy.md在目标环境完成验证。v1.0.0 的主承诺是单机部署迁移恢复、具体 IdP 联调和多机验证属于后续工程。六、什么时候该用什么时候不该用01 里讨论过”Workflow vs Agent”的选择。AgentBridge 也有自己的适用边界适合的场景给现有系统加一个对话入口用户用自然语言查数据、做分析产品验证阶段快速展示”我们的系统可以做 AI 操作”给领导或客户看内部效率工具团队需要自然语言操作已有系统但不想改老代码多个系统共享一套权限、审批和审计体系不适合的场景从零做 AI 产品没有现有系统→ 直接用 LangGraph、CrewAI硬实时控制或高频交易模型和工具调用具有不确定延迟→ 使用确定性的传统链路用它替代完整的企业身份体系 → 控制台提供本地管理员认证生产业务身份仍应对接你的 JWT/OIDC 与权限来源简单判断你的系统有接口想让 AI 在权限和审批控制下调用它们可以考虑 AgentBridge。如果只是做一个没有业务工具和治理要求的轻量 AI 原型直接使用模型 SDK 或编排框架通常更简单如果从一开始就需要权限、审批、审计和可追溯事件即使是新项目AgentBridge 仍可能适合。AgentBridge v1.0.0 已作为单机稳定版发布定位是可自托管、面向 Vibe Coding 的源码型业务 AI 底座而不是公共 SDK、云托管 Studio 或现成行业系统。若你手上的系统正好有类似需求不想推倒重来想快速验证受控的 Agent 能力可以试试。默认 Compose 不需要 API Key 或云服务正式接入仍应按自己的模型、身份、数据、RAG 和部署环境完成验收。觉得有用的话欢迎 Starhttps://github.com/Foamtor/AgentBridge