人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载导读当业务从「回答一个问题」升级为「研究 → 分析 → 写报告 → 跨部门协作」时单个 Agent 已经无法胜任。本文以 VoltAgent基于 TypeScript 的开源 AI Agent 编排框架为主线系统讲解 AI Agent 编排Agent Orchestration的概念、价值、核心模式与落地代码从 Supervisor主管模式、Pipeline流水线模式到客户服务、内容生产等真实业务场景并结合 packages/core/src/agent/subagent/index.ts 等源码级实现带你掌握多 Agent 协调、错误隔离、成本控制与可观测性的一整套实战能力。什么是 Agent 编排Agent Orchestration想象一支交响乐团每位乐手都是自己乐器的专家但没有指挥你听不到优美的音乐。Agent 编排正是如此——每个 Agent 都有自己的职责但需要某种「协调机制」把它们组织起来。在 VoltAgent 中编排的最小单位是一个个Agent实例它们各自持有独立的instructions指令、model模型、tools工具与memory记忆而编排的核心是让一个「主管 Agent」通过内置的subAgents机制把任务委派给多个专业化 Agent并汇总它们的结果。一次典型的编排流程如下为什么需要编排单 Agent 的四个瓶颈从单 Agent 起步业务扩大后你很快会遇到四类问题复杂性Complexity让一个 Agent 干所有事它会「混乱」输出不可预测性能Performance提示词越来越长响应越来越慢维护Maintenance难以调试、代码难以理解一个问题牵一发动全身可扩展性Scalability单体 Agent 体积过大无法水平扩展。为什么 Agent 编排很重要Agent 编排不是赶时髦而是当下 AI 应用的一种刚需。具体体现在七个方面。1. 复杂性管理Complexity Management现实世界的问题远比单个 Agent 能处理的复杂。以一个在线商店为例它需要同时提供商品推荐管理库存做价格分析提供客户支持跟踪订单如果把这些全部塞进一个 Agent结果是超长的输入、不可预测的输出和无法调试的复杂性。编排让每个 Agent 只负责一个领域复杂度被分解为可管理的模块。2. 专业化收益Specialization Benefits当每个 Agent 只精通自己的领域时输出质量会显著提升// 专业化 Agent 表现更好 const sqlExpert new Agent({ name: SQL Expert, instructions: You are an SQL expert. You write complex database queries., // 只挂载与 SQL 相关的工具 }); const reportExpert new Agent({ name: Report Expert, instructions: You are a business analyst. You turn data into meaningful reports., // 只挂载与报表生成相关的工具 });3. 可扩展性Scalability有了编排你可以随系统成长逐步加入新的 Agent从 2~3 个 Agent 起步随着业务增长添加新的专家 Agent每个 Agent 各司其职协调由框架自动完成4. 错误隔离Error Isolation单体 Agent 一旦出错整个流程停摆而在编排中某个 Agent 出错不会影响其他 Agent 继续工作对应的代码非常直观——对单个 Agent 的调用包在try/catch里失败时走兜底路径其他 Agent 不受影响// 如果一个 Agent 失败其他 Agent 继续工作 try { const analysisResult await analysisAgent.generateText(data); } catch (error) { // 分析 Agent 失败了但其他 Agent 仍在工作 console.log(Analysis failed, continuing with other agents); const basicResult await basicAgent.generateText(data); }值得说明的是VoltAgent 的 Supervisor 模式在框架层也内置了错误隔离能力SubAgentManager的handoffTask会捕获子 Agent 的执行错误并把它包装成一条Error in delegating task to xxx的 UIMessage 返回给主管 Agent而不会中断主管自身的运行见 packages/core/src/agent/subagent/index.ts。5. 成本优化Cost Optimization编排可以显著降低成本小任务用小模型如 gpt-4o-mini重活用大模型如 gpt-4o并行处理节省时间避免不必要的 API 调用const cheapAgent new Agent({ name: Classifier, model: openai(gpt-4o-mini), // 便宜的小模型 instructions: Just determine the category, }); const expensiveAgent new Agent({ name: Complex Analyzer, model: openai(gpt-4o), // 昂贵的大模型 instructions: Do detailed analysis, });6. 维护与调试Maintenance Debugging编排让问题定位变得容易每个 Agent 的职责被清晰定义通过 VoltOps 你可以看到到底是哪个 Agent 出了问题修复一个 Agent 不会干扰其他 Agent测试更容易编写7. 贴近真实业务Real-World Business Alignment编排更适合真实业务流程的建模企业有部门划分销售、市场、技术每个部门有专家Agent 也应如此组织业务流程可以被自然映射为 Agent 网络编排模式Orchestration Patterns模式一Supervisor 模式最常用Supervisor 模式中有一个「老板」Agent其他 Agent 向它汇报。在 VoltAgent 里实现非常简单下面是完整的可运行示例。注意这里使用了文档中的经典写法——通过voltagent/vercel-ai的VercelAIProvider接入 AI SDK 的模型该 Provider 将 VoltAgent 的调用标准化为底层模型调用其实现可参考 archive/deprecated-providers/vercel-ai/src/provider.ts在最新架构中模型接入方式已统一收敛到核心运行时请以 packages/core/src 的 Provider 接口为准import { Agent } from voltagent/core; import { VercelAIProvider } from voltagent/vercel-ai; import { openai } from ai-sdk/openai; // 先创建专家 Agent const researchAgent new Agent({ name: Researcher, purpose: Expert in collecting and analyzing data from the web, instructions: You are a research expert. You collect detailed and accurate information., llm: new VercelAIProvider(), model: openai(gpt-4o-mini), }); const writerAgent new Agent({ name: Writer, purpose: Professional content writing expert, instructions: You are a writer. You write clear and effective texts., llm: new VercelAIProvider(), model: openai(gpt-4o-mini), }); // 主管 Agent把专家 Agent 注册为 subAgents const supervisorAgent new Agent({ name: Project Manager, instructions: You are a project manager who coordinates expert agents., llm: new VercelAIProvider(), model: openai(gpt-4o), subAgents: [researchAgent, writerAgent], // 挂载子 Agent supervisorConfig: { customGuidelines: [ Always assign the right task to the right agent, Check the outputs of agents, Give clear and organized answers to the user, ], }, }); // 使用 const response await supervisorAgent.generateText( Can you write a comprehensive article about Bitcoin? );在上面的例子中主管 Agent 会自动完成三步先让 Researcher 调研 Bitcoin再让 Writer 把调研结果写成文章最后把结果呈现给用户。源码视角Supervisor 模式的底层机制。从 packages/core/src/agent/subagent/index.ts 可以看出subAgents并不是装饰——SubAgentManager会把子 Agent 注册到全局AgentRegistry建立父子关系registerSubAgent在运行前调用generateSupervisorSystemMessage把子 Agent 清单名称 purpose与默认编排准则例如「尽量同时联系多个 Agent 以优化通信」「Agent 之间互不知晓对方存在你必须充当唯一中间人」拼装进主管的系统提示词customGuidelines会被追加到默认准则之后自动为主管 Agent 注册一个名为delegate_task的工具见createDelegateTool工具参数为task与targetAgents主管通过它把任务委派给一个或多个专家 Agent未显式设置maxSteps时默认步数按子 Agent 数量放大subAgentConfigs.length 0 ? 10 * length : 10见 packages/core/src/agent/subagent/index.ts。也就是说你只需要声明subAgents编排的「指挥动作」由框架自动注入。supervisorConfig的完整配置项定义见 packages/core/src/agent/types.ts配置项类型默认值说明systemMessagestring无使用内置模板完全自定义的主管系统消息提供后整体替换默认模板仅在includeAgentsMemory为 true 时追加 agents memory 段includeAgentsMemorybooleantrue是否在主管系统消息中包含上一次 Agent 交互的 memory 摘要agents_memory段customGuidelinesstring[][]追加在框架默认准则之后的自定义编排准则fullStreamEventForwarding{ types: StreamEventType[] }{ types: [tool-call, tool-result, input-guardrail-blocked] }控制子 Agent 的哪些流事件如 tool-call、tool-result转发到主管的 fullStreamthrowOnStreamErrorbooleanfalse子 Agent 流式执行出错时是否抛出异常为 false 时错误被捕获并随结果返回includeErrorInEmptyResponsebooleantrue当没有产出文本内容时是否把错误信息写进结果字段仅在throwOnStreamError为 false 时生效进阶createSubagent按需定制子 Agent 调用方式。除了直接传入 Agent 实例默认以streamText方式调用packages/core/src/agent/subagent/types.ts 还提供了createSubagent帮助函数支持四种调用方法并附带类型安全的 optionsimport { createSubagent } from voltagent/core; import { z } from zod; // 1) 直接传入 Agent 实例默认走 streamText const a createSubagent({ agent: myAgent }); // 2) streamText 采样参数 const b createSubagent({ agent: myAgent, method: streamText, options: { temperature: 0.7, maxTokens: 1000 }, }); // 3) generateText const c createSubagent({ agent: myAgent, method: generateText }); // 4) 带 schema 的结构化输出generateObject / streamObject const d createSubagent({ agent: myAgent, method: generateObject, schema: z.object({ result: z.string() }), options: { temperature: 0.2 }, });模式二Pipeline 流水线模式有些场景需要 Agent 按顺序执行前一个 Agent 的输出是后一个 Agent 的输入。例如电商场景中「商品分析 → 价格优化 → 库存管理」对应的 Agent 定义骨架// 电商流水线示例 const productAnalyzer new Agent({ name: Product Analyzer, instructions: Analyze and categorize product information, // ... 其余配置 }); const priceOptimizer new Agent({ name: Price Optimizer, instructions: Do competitive price analysis, // ... 其余配置 }); const inventoryManager new Agent({ name: Inventory Manager, instructions: Check inventory status and provide suggestions, // ... 其余配置 });在 Pipeline 模式下你可以用代码显式控制执行顺序与数据传递例如把前一个 Agent 的generateText结果拼进下一个 Agent 的 prompt也可以让 Supervisor 模式配合自定义准则天然地按步骤委派。VoltAgent 编排的独特优势1. TypeScript 优先TypeScript-First Development虽然 Python 社区在 AI 领域声量最大但对于 JavaScript/TypeScript 开发者VoltAgent 极其务实全程类型安全、IDE 支持出色Agent构造参数、SubAgentConfig联合类型、supervisorConfig等都有完整的 TypeScript 类型定义编译期即可拦截大量配置错误类型定义见 packages/core/src/agent/types.ts 与 packages/core/src/agent/subagent/types.ts。2. 内置可观测性VoltOps「Agent 到底在干什么」是编排场景最棘手的问题之一。通过 VoltOps你可以看到全部 Agent 交互细节const agent new Agent({ // ... 其他配置 voltOpsClient: new VoltOpsClient({ publicKey: your-public-key, secretKey: your-secret-key, }), });哪个 Agent 在什么时间运行、耗时多久、跑了什么流程都会呈现在仪表盘上。从 packages/core/src/voltops/types.ts 可以看到VoltOpsClientOptions还支持baseUrl默认https://api.voltagent.dev、prompts是否启用提示词管理默认 true、promptCache缓存 TTL 与上限以及自定义fetch实现公钥以pk_前缀开头、适合放在客户端密钥以sk_前缀开头、只能保存在服务端。3. 模块化架构Modular Architecture工具可以在多个 Agent 之间共享复用// 工具也可以共享 const sharedTools [weatherTool, searchTool, calculatorTool]; const agents [ new Agent({ name: Agent1, tools: [sharedTools[0], sharedTools[1]] }), new Agent({ name: Agent2, tools: [sharedTools[1], sharedTools[2]] }), ];真实业务场景示例场景一客户服务编排Customer Service Orchestration用编排构建端到端的客户服务流水线请求被自动分类并路由给对应领域的专家 Agent。const classifierAgent new Agent({ name: Ticket Classifier, instructions: Categorize incoming requests: technical, billing, general, // ... }); const technicalAgent new Agent({ name: Technical Support, instructions: Solve technical problems, use documentation, // ... }); const billingAgent new Agent({ name: Billing Expert, instructions: Answer billing questions, // ... }); const customerServiceSupervisor new Agent({ name: Customer Service Coordinator, instructions: Route customer requests to the right department, subAgents: [classifierAgent, technicalAgent, billingAgent], supervisorConfig: { customGuidelines: [ First classify the request, Route to the right expert agent, If theres ambiguity, ask the user for clarification, ], }, });场景二内容生产流水线Content Production Pipeline把内容生产拆成「趋势研究 → 写作 → 编辑」三个环节每个 Agent 只负责其中一段const contentPipeline new Agent({ name: Content Production Manager, instructions: Manage the content production process, subAgents: [ new Agent({ name: Trend Researcher, instructions: Research current trends and suggest topics, }), new Agent({ name: Content Writer, instructions: Write SEO-friendly content, }), new Agent({ name: Editor, instructions: Review and improve content, }), ], });这就构成了一个端到端的内容生产流程Trend Researcher 产出选题Content Writer 写出初稿Editor 审核润色最终由主管汇总输出。编排中的注意事项1. 错误处理Error Handling某个子 Agent 挂了怎么办在 VoltAgent 中可以用try/catch触发兜底逻辑try { const result await supervisorAgent.generateText(prompt); } catch (error) { console.log(Agent orchestration error:, error); // 兜底逻辑 }同时如前面源码分析所述supervisorConfig.throwOnStreamError默认 false决定了子 Agent 流错误是抛出还是随结果返回onHandoff、onHandoffComplete等 hooks 还能让你在委派前后注入自定义逻辑见 packages/core/src/agent/subagent/index.ts。2. 成本管理Cost Management多个 Agent 意味着多个模型调用成本会随之上升。你可以在 VoltOps 仪表盘上按 Agent、按模型追踪 Token 消耗与费用。3. 延迟优化Latency Optimization对于相互独立的并发任务可以用Promise.all让多个 Agent 并行执行大幅压缩端到端耗时// 并行执行示例 const [research, analysis] await Promise.all([ researchAgent.generateText(Research Bitcoin), analysisAgent.generateText(Do crypto trend analysis), ]);实际上SubAgentManager也提供了handoffToMultiple方法支持一次把任务并行委派给多个子 Agent并逐个独立处理错误见 packages/core/src/agent/subagent/index.ts。监控与调试Monitoring and Debug可观测性是 VoltAgent 最强的能力之一。在 VoltOps 仪表盘上你可以查看 Agent 的执行路径谁调用了谁、子 Agent 的执行链跟踪性能指标耗时、Token 数查看错误率优化成本除了 VoltOps还可以用生命周期 hooks 做精细化日志// 详细日志 const agent new Agent({ // ... 配置 hooks: { onStart: (context) console.log(Agent started:, context), onEnd: (result) console.log(Agent completed:, result), onError: (error) console.log(Error occurred:, error), }, });从源码看onStart、onEnd、onError钩子在generateText/streamText的完整执行周期中都会被可靠触发见 packages/core/src/agent/agent.ts、packages/core/src/agent/agent.ts 等处的调用点为排查编排链路提供了粒度级的观测入口。结论AI Agent 编排是从简单聊天机器人走向企业级系统的关键一步。借助 VoltAgent你可以留在熟悉的 TypeScript 生态中通过图形化监控获得全程可见性依托模块化架构构建可水平扩展的系统用 Supervisor 模式优雅地处理复杂工作流从一个 Agent 起步按需演进到编排体系。借助 VoltAgent 的 subAgent 结构你可以在不改变既有代码的前提下持续生长。最后记住一点最好的编排是用户根本感知不到的编排——让 Agent 们在后台自行协调只把最好的结果呈现给用户。赞分享人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载相关推荐ADK Agent 开发速查手册从单智能体到多智能体编排agent-starter-pack 实战指南ADK Agent 开发速查手册从单智能体到多智能体编排agent starter pack 实战指南 本文是一份以 Google Agent Devel人工智能AI Agent开发工具代码生成LLMOpsVoltAgent多智能体系统构建Supervisor与Sub-Agent协调实战VoltAgent多智能体系统构建Supervisor与Sub Agent协调实战 VoltAgent是一个强大的开源TypeScript AI Agent框人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音ActivePieces Chat Personalization聊天内首次引导与个性化用例卡片生成机制解析ActivePieces Chat Personalization聊天内首次引导与个性化用例卡片生成机制解析 本文围绕 ActivePieces 中的 Cha人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音上一篇Argo CD 控制器 RBAC 感知监控深入解析 resource.respectRBAC 资源配置下一篇Windmill 原生触发器Native Trigger服务接入完全指南从 External Trait 到前后端全链路实现创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考