这篇文章不是“我发现了一个好工具”，而是源于我在业务系统 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 对写操作做了完整的审批生命周期：

1. 工具命中审批策略 → 图暂停，生成审批卡推给用户
2. 用户看到草稿预览（工单标题、优先级、指派人）
3. 用户确认 → ApprovalResumeExecutor 在执行租约内完成操作
4. approval_id 作为幂等键，重复审批不会创建重复记录
5. 审批超时 → 自动过期，图恢复时不会误执行

这套机制保证了：Agent 可以生成操作建议，但最终决定权在人。02 里讨论的 Human-in-the-Loop，在这里落地成了具体的代码。

模型和知识库：端口-适配器模式

AgentBridge 不绑定任何特定的模型或向量库。所有外部依赖都通过协议接入：

模型层。 AliasLLMGateway 通过 default、fast 等逻辑别名隔离业务代码与具体模型。默认配置可以让多个别名指向同一个模型，也可以由管理员按场景配置不同模型。模型 API Key 加密存储且不会返回浏览器，业务代码不需要感知具体厂商。

知识层。 Retriever 协议支持 fake、langchain_pg（LangChain + 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.py（LangGraph 图构建）
• bootstrap.py（注册入口）

最后还要在 apps/api/domains/bootstrap.py 登记这个插件，并补充 DOMAIN_META_MAP，这样平台和调试台才能发现新的 route。

一个真实的工具接入点

以仓库自带的 work_order_ops 为例，查询工具不会自己创建数据库连接，而是读取组装根已经注入的 data_source；租户条件来自经过验证的 RunContext：

@tool
async def list_work_orders(
    config: Annotated[RunnableConfig, InjectedToolArg],
) -> list[dict[str, Any]]:
    """Return display-safe work orders for the current tenant."""
    ctx = get_run_context(config)
    source = ctx.metadata.get("data_source")
    if source is None:
        return []

    rows = await source.query(
        "SELECT * FROM work_orders WHERE tenant_id = $1",
        ctx.tenant_id,
    )
    return [
        {key: row.get(key) for key in SAFE_ORDER_FIELDS}
        for row in rows
    ]


list_work_orders = attach_tool_meta(
    list_work_orders,
    required_permissions=["workorder:read"],
)

这里有三个关键点：

1. Tool 只是现有业务能力的适配层，不承载数据库连接配置；
2. 查询始终带当前租户，不接受模型随意指定租户；
3. workorder:read 不只是执行前检查，还决定这个工具能否进入模型可见列表。

注册时再把工具、流程图和输入构造器挂到对应 route：

def 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 / Linux：

git clone https://github.com/Foamtor/AgentBridge.git
cd AgentBridge
cp .env.example .env
docker compose up --build

Windows PowerShell：

git clone https://github.com/Foamtor/AgentBridge.git
Set-Location AgentBridge
Copy-Item .env.example .env
docker compose 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 和部署环境完成验收。

觉得有用的话，欢迎 Star：https://github.com/Foamtor/AgentBridge