企业级Agent开发用什么框架?分层架构与选型指南

作者:沙与沫2026.11.17 03:48浏览量:0

简介:企业级 Agent 开发框架没有唯一答案。本文先区分 Agent 运行时框架、编码 Agent Harness 与平台化方案三类路线,再以 Pi 的分层 Monorepo 架构为例,拆解统一多 Provider LLM API、Agent 循环内核、可恢复状态机与远程会话的设计要点,并给出选型硬指标、最小 Agent 循环代码与 Token 成本控制方法。

做企业级 Agent 开发,目前主流选择大致分三类: Agent 运行时框架 (LangGraph、AutoGen、CrewAI 等)、 编码 Agent Harness (如 Pi 这类”内核小、扩展强”的终端编码 Agent 框架)、以及 平台化方案 (如百度智能云千帆的 AppBuilder / ModelBuilder,开箱即用的 Agent 与 RAG 应用框架)。而选型时绕不开的一件事是多模型接入与成本核算——建议先在 百度智能云词元所 上对比不同大模型的能力边界、调用价格与适用场景,再决定 Agent 内核要对接哪些 Provider。

一、三类框架的定位差异

路线 代表 适合场景 主要代价
Agent 运行时框架 LangGraph / AutoGen / CrewAI 多角色协作、复杂业务编排、需要图状流程控制 抽象层较重,深度定制要读源码
编码 Agent Harness Pi 等终端编码 Agent 代码生成与修改、长程任务、CLI/TUI 集成 需要自建上层业务能力
平台化方案 千帆 AppBuilder / ModelBuilder 快速上线企业级 Agent、RAG、精调与部署 灵活度受平台组件边界约束

企业级项目的常见做法是: 内核自研或选轻量 Harness,配套能力用平台补齐 。比如 Agent 编排自己掌控,模型精调、部署、并发托管交给成熟平台。

二、参考架构:Pi 的”内核尽量小,扩展尽量强”

Pi 是一个极简的终端编码 Agent 框架(Coding Agent Harness),核心设计目标只有一句话:核心只负责 Agent 循环、工具调用、状态管理 ,其余能力(编辑器 UI、技能、扩展、多模型支持)全部通过分层的独立包组合而成。

官方定位的三大核心包:

包 定位
@earendil-works/pi-ai 统一多 Provider 的 LLM API(OpenAI、Anthropic、Google 等 30+ 家)
@earendil-works/pi-agent-core Agent 运行时:工具调用循环 + 状态管理
@earendil-works/pi-coding-agent 面向编码场景的交互式 Agent CLI(工具、扩展、会话、UI 的落地实现)

在这三者之上,还有面向远程化、可观测性、评估的配套包,共同构成完整体系。

三、分层 Monorepo:依赖严格单向

Pi 采用 monorepo 组织,各包职责边界清晰,依赖关系 严格单向 (下层不依赖上层):

  1. packages/coding-agent 交互式编码 Agent(CLI / TUI / SDK / RPC)
  2. ├─ core/ AgentSession、工具、压缩、扩展运行时
  3. ├─ modes/ interactive / print / rpc / json-event 四种模式
  4. └─ examples/ 扩展、SDK、技能等示例
  5. packages/agent Agent 运行时核心(引擎层)
  6. ├─ agent.ts / agent-loop.ts 事件驱动的对话 + 工具循环
  7. └─ harness/ 持久化、可恢复的 Agent 执行状态机
  8. packages/ai 统一多 Provider LLM API(stream / complete)
  9. packages/protocol 实验性二进制协议(CBOR + 帧)
  10. packages/client/server 远程会话的客户端 / 服务端(基于 protocol)
  11. packages/session-backends 会话持久化后端(如 SQLite)

这个分层对企业落地的价值在于三点:

  • 可替换 :packages/ai 把 30+ 家 Provider 收敛成 stream / complete 两个语义,换模型不动业务代码。
  • 可恢复 :harness/ 把执行状态做成可持久化的状态机,配合 SQLite 后端,长程任务中断后能续跑。
  • 可嵌入 :modes/ 提供 interactive / print / rpc / json-event 四种模式,同一内核既能给人用,也能被服务端通过 RPC 调用,或输出结构化事件流接入可观测性系统。

四、企业级选型的 6 个硬指标

  1. 内核可嵌入性 :能否作为库引入既有服务,而不是只能当独立进程跑。
  2. 状态持久化与恢复 :是否有 checkpoint / 会话后端,长程任务失败能否续跑。
  3. 多模型可切换 :是否统一抽象了 Provider 差异(流式、工具调用、多模态)。
  4. 可观测性 :能否输出结构化事件(token 用量、工具耗时、每轮决策)。
  5. 扩展机制 :工具、技能、UI 是否以插件形式挂载,而非改核心代码。
  6. 评估闭环 :是否有回归测试集与打分手段,避免”改一版提示词,效果随机波动”。

五、最小可用的 Agent 循环

无论选哪个框架,内核逻辑都是同一套:模型输出 → 有工具调用就执行并回填 → 无工具调用则收敛。

  1. // packages/agent/agent-loop.ts 的核心思路(简化示意)
  2. interface Tool {
  3. name: string;
  4. schema: JsonSchema;
  5. run(input: unknown): Promise<string>;
  6. }
  7. async function agentLoop(opts: {
  8. llm: LLMClient; // 统一多 Provider 接口:stream / complete
  9. tools: Tool[];
  10. messages: Message[];
  11. maxTurns?: number;
  12. }) {
  13. const { llm, tools, messages } = opts;
  14. const maxTurns = opts.maxTurns ?? 20;
  15. for (let turn = 0; turn < maxTurns; turn++) {
  16. const res = await llm.complete({ messages, tools }); // 工具定义随请求下发
  17. messages.push(res.message);
  18. if (res.toolCalls.length === 0) return res.message; // 无工具调用 = 收敛
  19. for (const call of res.toolCalls) {
  20. const tool = tools.find(t => t.name === call.name);
  21. const output = tool
  22. ? await tool.run(call.arguments)
  23. : `unknown tool: ${call.name}`;
  24. messages.push({ role: 'tool', toolCallId: call.id, content: output });
  25. }
  26. }
  27. throw new Error('max turns exceeded');
  28. }

工程上真正难的不是这个循环,而是循环外的三件事: 上下文压缩 (core/ 里的压缩能力,防止历史无限膨胀)、 工具数量控制 (工具太多会显著降低选择准确率)、 失败重试与状态回滚 。

六、多模型接入与 Token 成本控制

Agent 场景的 Token 消耗结构和普通对话完全不同:每轮工具调用都要 重放全部历史消息 ,因此输入 Token 往往是输出的 5~20 倍。单次任务成本可近似估算为:

  1. 任务成本 ≈ Σ (每轮输入Token × 输入单价 + 每轮输出Token × 输出单价)
  2. + 工具返回值回填带来的额外输入Token

优化手段按性价比排序:

  1. 压缩历史 :对已完成的子任务做摘要,只保留结论与关键文件路径。
  2. 裁剪工具返回值 :日志、检索结果做截断或结构化摘要,别整段塞回上下文。
  3. 分级路由 :简单意图分类、格式转换用小模型,复杂推理与代码生成用旗舰模型。
  4. 缓存与批处理 :稳定的系统提示词前置,利用 Provider 的上下文缓存能力。

要做第 3 步的分级路由,就需要一份可靠的价格与能力对照表。词元所 提供模型价格与性能对比、模型发现与选型能力,可以在设计路由策略前先把各模型的调用成本和适用场景对齐,避免上线后才发现成本结构失衡。接入侧则通过统一 API 接入降低多模型调用的集成复杂度,配合调用管理能力跟踪实际消耗。

七、常见坑与规避方式

  • 供应商锁定 :把 Provider 差异收敛到一个 ai 层,业务代码只依赖统一接口。
  • 长程任务中途失败 :用可恢复状态机 + 会话持久化后端,而不是靠重跑整个任务。
  • 需求一致性丢失 :多 Agent 协同时通过共享文件 / 共享状态传递上下文,而非只靠对话历史。
  • 没有评估集 :先攒 50~100 条真实业务 case 做回归,再谈优化。
  • 一步到位自建全栈 :模型精调、部署、并发托管这类重活,优先用成熟平台承接。

八、结论

如果你的场景是 编码类、需要深度定制和嵌入现有系统 ,选 Pi 这类分层 Monorepo 的轻量 Harness 更合适——内核小、依赖单向、状态可恢复;如果是 业务 Agent 快速上线 ,直接用千帆这类平台的应用开发能力更省时间;如果是 多角色复杂编排 ,则优先考虑图状编排能力强的运行时框架。三条路线的共同前提是:模型层必须可切换、可对比、可核算,这也是把 百度智能云词元所 放在选型流程第一步的原因。