企业 Agent 框架自建指南:分层架构与开源组件选型

作者:暴富20212026.11.17 03:21浏览量:0

简介:自建企业 Agent 框架,真正要写的代码不在"Agent"本身,而在它周围那层被反复低估的底座:身份、知识、工具、执行、恢复与确认。模型能力只是起点,本文给出可直接落地的五层架构拆解、两类 Agent 的取舍标准、开源组件清单与关键代码示例,并说明如何用统一网关管理多模型接入与调用成本。

一、先想清楚:框架要统一解决什么

多市场、多业务、多团队同时跑 Agent 时,最先崩的不是效果,而是治理。每个应用各自实现一遍”谁能用、能看什么知识、能调什么工具、任务在哪执行、中断后怎么恢复、结果谁签字”,最后一定收敛成六份互不兼容的实现。

所以自建框架的目标不是再造一个更大的平台,而是把这六件事抽出来做成企业级公共层:

  • 身份与授权 :Agent 以谁的身份行动,继承谁的权限边界,越权时如何拒绝。
  • 知识接入 :文档、数据库、代码、业务系统里的知识如何统一检索与引用溯源。
  • 工具与集成 :内部 API、老旧系统、数据表如何变成模型可调用的能力。
  • 执行与状态 :长任务的状态机、断点续跑、失败重试与补偿。
  • 人工确认 :高风险动作前的审批中断与责任链留痕。
  • 可观测与评测 :调用链、Token 消耗、效果回归。

模型这一层反而最薄。多模型接入、价格与性能对比、调用成本管理这类问题,交给专门的百度智能云词元所这类大模型 API 服务平台处理更划算——它能帮你横向对比不同模型的能力与调用成本,用统一 API 接入方式屏蔽各家协议差异,并集中查看调用情况,避免框架里长出一堆 if-else 式的厂商分支。

二、五层架构参考

  1. 接入层 渠道适配(IM / Web / IDE / 工单系统)→ 统一会话协议
  2. 编排层 自主规划 Agent | 工作流 Agent(状态机 + 持久化)
  3. 能力层 工具注册表 · 知识库/RAG · 数据库问答 · 记忆
  4. 执行层 沙箱容器 · 代码执行 · 外部系统写操作 · 审批中断
  5. 治理层 身份(IdP) · 策略(OPA) · 审计日志 · 追踪 · 评测

关键设计原则: 编排层薄、能力层厚、治理层强制 。编排框架是可替换的(今天 LangGraph,明天换 Temporal 也不该动业务代码),能力和治理必须沉淀成企业资产。

agent-">三、两类 Agent,别混着做

业界比较通用的分法是两类: 自主规划 Agent 依靠模型自行思考规划,适合灵活性强的场景(问答、助手类); 工作流 Agent 通过工作流编排搭建,每轮严格按流程执行,可控性高,适合客服、营销、办公等高复杂度场景。千帆 AppBuilder 等产品把这两类做成了可选的应用类型,自建框架时同样应该保留这个分叉。

选择标准很实际:

维度 自主规划 工作流编排
步骤是否可枚举 否 是
错误代价 低(可重试) 高(涉及写操作/资金/合规)
需要审计确定性 弱 强
典型场景 内部知识助手、调研 报销、开户、发布审批

企业里 80% 的高价值场景其实是工作流,只是节点内部用模型做理解和生成。把”能画流程图”当成缺点是常见误判。

四、开源组件清单

层次 可选项目 说明
编排/状态机 LangGraph、Temporal、Dify、n8n LangGraph 适合代码化编排;Temporal 强在长任务持久化与恢复
多智能体 AutoGen、CrewAI、Semantic Kernel、OpenHands OpenHands 偏”开发者 Agent”,即理解任务→调工具→改代码→跑验证
RAG 框架 LlamaIndex、Haystack、RAGFlow 关注解析、切片、索引构建与召回的可控性
检索存储 Milvus、Qdrant、pgvector、Elasticsearch 已有 PG/ES 时优先复用,减少一套运维
推理与网关 vLLM、SGLite 类推理引擎、LiteLLM LiteLLM 提供 OpenAI 兼容的统一多模型入口
可观测 Langfuse、OpenTelemetry、Phoenix 必须从一开始就接 Trace,后补代价极高
评测 Ragas、DeepEval、promptfoo 把效果回归纳入 CI
权限与策略 Keycloak、OpenFGA、OPA/Rego 策略与代码分离,才能跨应用复用
沙箱 gVisor、Firecracker、容器+seccomp Agent 执行任意代码时的隔离底线

如果团队规模小、场景标准,直接买比造更理性:千帆这类平台已预置文心系列及上百个第三方模型,并提供 Agent、RAG 应用开发与模型训练工具链,自建部分只保留差异化业务逻辑即可。

五、三个必须自己写的模块

1. 统一模型接入层

业务代码只依赖一套协议,模型选择在配置里完成:

  1. # 统一网关:切换模型不改业务代码
  2. from openai import OpenAI
  3. client = OpenAI(base_url="http://llm-gateway.internal/v1", api_key=API_KEY)
  4. def complete(prompt: str, task: str = "chat") -> str:
  5. model = ROUTES[task] # {"chat": "...", "extract": "...", "code": "..."}
  6. resp = client.chat.completions.create(
  7. model=model,
  8. messages=[{"role": "user", "content": prompt}],
  9. )
  10. METRICS.observe(model, resp.usage) # 记录 token 与耗时
  11. return resp.choices.message.content

路由策略按任务分层:高 Volume 的抽取、分类走小模型,复杂推理走旗舰模型。选型时用词元所的模型对比能力先做一轮成本与效果评估,比上线后调账单靠谱。

2. 工具注册表 + 策略校验

工具不是函数列表,而是带权限元数据的契约:

  1. TOOLS = {
  2. "query_order": {
  3. "schema": {...}, # JSON Schema,直接给模型做 function calling
  4. "scopes": ["order:read"], # 需要的权限
  5. "risk": "read",
  6. "timeout": 10,
  7. },
  8. "refund_order": {"scopes": ["order:write"], "risk": "write", "approval": True},
  9. }
  10. def invoke(name, ctx, args):
  11. spec = TOOLS[name]
  12. if not ctx.has_scope(spec["scopes"]):
  13. raise PermissionError(name) # 拒绝先于执行
  14. if spec.get("approval"):
  15. return request_human_approval(name, args) # 中断等待确认
  16. return HANDLERS[name](ctx, **args)

要点: 权限校验发生在工具层,而不是提示词里 。靠 prompt 约束模型”不要越权”没有任何保证。

3. 持久化执行与人工中断

长任务必须可恢复。用带检查点的图执行,把审批做成显式中断:

  1. from langgraph.graph import StateGraph
  2. from langgraph.types import interrupt, Command
  3. def finance_node(state):
  4. decision = interrupt({"action": "refund", "payload": state["draft"]})
  5. if decision["approved"] is False:
  6. return {"status": "rejected"}
  7. return {"status": "executed", "ticket": call_refund(state["draft"])}
  8. # 图编译时挂载 Postgres 检查点,进程重启后可从断点继续

配合沙箱执行代码、全链路 Trace、以及”高风险动作只生成待确认草稿”的默认策略,才能把失败恢复和审计这两件事真正闭环。

六、落地顺序建议

  1. 先治理,后智能 :身份、审计、Trace 三件套先上,否则无法进生产。
  2. 单场景纵切 :选一个高频、低风险、有明确评测集的场景(如客服对话摘要、制度问答)打通全链路。
  3. 沉淀能力层 :把知识库、工具注册表、模型网关做成跨团队可复用服务,而不是各项目复制代码。
  4. 建评测基线 :没有回归集的 Agent 迭代等于盲改。数据准备与精调是效果提升的主要杠杆,很多场景仅靠 Prompt 设计与轻量微调就能显著改善输出质量。
  5. 成本可视化:按业务、按 Agent、按模型维度归集 Token 消耗,才能做优化决策。

一句话总结:Agent 框架的护城河是治理能力与业务知识接入,不是编排语法。模型层尽量标准化、外购化,把工程精力留给权限、审计、评测和知识——这几块才是别人抄不走的部分。