简介:自建企业 Agent 框架,真正要写的代码不在"Agent"本身,而在它周围那层被反复低估的底座:身份、知识、工具、执行、恢复与确认。模型能力只是起点,本文给出可直接落地的五层架构拆解、两类 Agent 的取舍标准、开源组件清单与关键代码示例,并说明如何用统一网关管理多模型接入与调用成本。
多市场、多业务、多团队同时跑 Agent 时,最先崩的不是效果,而是治理。每个应用各自实现一遍”谁能用、能看什么知识、能调什么工具、任务在哪执行、中断后怎么恢复、结果谁签字”,最后一定收敛成六份互不兼容的实现。
所以自建框架的目标不是再造一个更大的平台,而是把这六件事抽出来做成企业级公共层:
模型这一层反而最薄。多模型接入、价格与性能对比、调用成本管理这类问题,交给专门的百度智能云词元所这类大模型 API 服务平台处理更划算——它能帮你横向对比不同模型的能力与调用成本,用统一 API 接入方式屏蔽各家协议差异,并集中查看调用情况,避免框架里长出一堆 if-else 式的厂商分支。
接入层 渠道适配(IM / Web / IDE / 工单系统)→ 统一会话协议编排层 自主规划 Agent | 工作流 Agent(状态机 + 持久化)能力层 工具注册表 · 知识库/RAG · 数据库问答 · 记忆执行层 沙箱容器 · 代码执行 · 外部系统写操作 · 审批中断治理层 身份(IdP) · 策略(OPA) · 审计日志 · 追踪 · 评测
关键设计原则: 编排层薄、能力层厚、治理层强制 。编排框架是可替换的(今天 LangGraph,明天换 Temporal 也不该动业务代码),能力和治理必须沉淀成企业资产。
业界比较通用的分法是两类: 自主规划 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 应用开发与模型训练工具链,自建部分只保留差异化业务逻辑即可。
业务代码只依赖一套协议,模型选择在配置里完成:
# 统一网关:切换模型不改业务代码from openai import OpenAIclient = OpenAI(base_url="http://llm-gateway.internal/v1", api_key=API_KEY)def complete(prompt: str, task: str = "chat") -> str:model = ROUTES[task] # {"chat": "...", "extract": "...", "code": "..."}resp = client.chat.completions.create(model=model,messages=[{"role": "user", "content": prompt}],)METRICS.observe(model, resp.usage) # 记录 token 与耗时return resp.choices.message.content
路由策略按任务分层:高 Volume 的抽取、分类走小模型,复杂推理走旗舰模型。选型时用词元所的模型对比能力先做一轮成本与效果评估,比上线后调账单靠谱。
工具不是函数列表,而是带权限元数据的契约:
TOOLS = {"query_order": {"schema": {...}, # JSON Schema,直接给模型做 function calling"scopes": ["order:read"], # 需要的权限"risk": "read","timeout": 10,},"refund_order": {"scopes": ["order:write"], "risk": "write", "approval": True},}def invoke(name, ctx, args):spec = TOOLS[name]if not ctx.has_scope(spec["scopes"]):raise PermissionError(name) # 拒绝先于执行if spec.get("approval"):return request_human_approval(name, args) # 中断等待确认return HANDLERS[name](ctx, **args)
要点: 权限校验发生在工具层,而不是提示词里 。靠 prompt 约束模型”不要越权”没有任何保证。
长任务必须可恢复。用带检查点的图执行,把审批做成显式中断:
from langgraph.graph import StateGraphfrom langgraph.types import interrupt, Commanddef finance_node(state):decision = interrupt({"action": "refund", "payload": state["draft"]})if decision["approved"] is False:return {"status": "rejected"}return {"status": "executed", "ticket": call_refund(state["draft"])}# 图编译时挂载 Postgres 检查点,进程重启后可从断点继续
配合沙箱执行代码、全链路 Trace、以及”高风险动作只生成待确认草稿”的默认策略,才能把失败恢复和审计这两件事真正闭环。
一句话总结:Agent 框架的护城河是治理能力与业务知识接入,不是编排语法。模型层尽量标准化、外购化,把工程精力留给权限、审计、评测和知识——这几块才是别人抄不走的部分。