multi-agent-orchestrator TypeScript 本地快速上手用 MultiAgentOrchestrator 构建多智能体编排应用【免费下载链接】agent-squadFlexible and powerful framework for managing multiple AI agents and handling complex conversations项目地址: https://gitcode.com/GitHub_Trending/mu/agent-squad本文是 TypeScript 本地 Demo 的实战指南围绕multi-agent-orchestrator框架讲解如何在一个普通 Node.js 项目中通过MultiAgentOrchestrator初始化编排器、注册多个专业化BedrockLLMAgent、调用routeRequest完成意图分类与智能体路由最终在本地终端跑通第一个多智能体问答应用。读完本文你将掌握编排器的配置项含义、默认模型与默认存储行为并能对照仓库中的交互式 Demo 扩展出流式输出、工具调用Function Calling与多类型智能体Lex、Lambda、Bedrock Agent混编的完整方案。一、这份指南解决什么问题多智能体应用的关键难点在于如何把哪个智能体来回答这件事交给系统自动决策。multi-agent-orchestrator给出的答案是编排器 意图分类器 智能体注册表三层结构用户输入先经过分类器判定意图并选出最合适的智能体再由该智能体生成回答。本文对应的官方入门文档typescript-local-demo.md给出了一个最小可运行示例只用两个BedrockLLMAgentTech Agent 与 Health Agent通过默认的 Bedrock 分类器实现科技问题找技术智能体、健康问题找医疗智能体的路由效果。仓库中的 本地交互式 Demo 则是该示例的超集版本额外演示了流式输出、天气工具调用以及 Lex/Lambda/Bedrock Agent 的混编两相结合即可从能跑走向能用于生产场景。二、前置条件在开始之前请确保本地环境满足以下条件与入门文档一致并补充说明Node.js 与 npm本示例通过npm initnpm install搭建工程并依赖ts-node运行 TypeScript 文件需要可用的 Node.js 环境。AWS 账户与相应权限分类器与智能体都通过 Amazon Bedrock 的Converse API发起推理请求因此需要配置 AWS 凭证如环境变量AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_REGION或本机~/.aws/credentials并确保账户已开通所需模型anthropic.claude-3-5-sonnet-20240620-v1:0与anthropic.claude-3-haiku-20240307-v1:0的访问权限。TypeScript 与 async/await 基础示例大量使用async function、await与异步迭代器for await需要对此有基本了解。三、快速初始化项目按照入门文档在本地任意目录新建工程并安装依赖mkdir test_multi_agent_orchestrator cd test_multi_agent_orchestrator npm init npm install multi-agent-orchestrator安装完成后在package.json的dependencies中会出现multi-agent-orchestrator依赖。仓库中的 examples/local-demo/package.json 使用了multi-agent-orchestrator: ^0.0.17并额外引入了dotenv用于从.env文件加载环境变量。如果希望运行本文后面的交互式 Demo建议同样安装dotenv与ts-nodenpm install dotenv npm install -D ts-node typescript四、编写第一个多智能体应用4.1 初始化编排器新建quickstart.ts首先初始化MultiAgentOrchestratorimport { MultiAgentOrchestrator } from multi-agent-orchestrator; const orchestrator new MultiAgentOrchestrator({ config: { LOG_AGENT_CHAT: true, LOG_CLASSIFIER_CHAT: true, LOG_CLASSIFIER_RAW_OUTPUT: false, LOG_CLASSIFIER_OUTPUT: true, LOG_EXECUTION_TIMES: true, } });config是OrchestratorConfig的部分配置未显式给出的项会与DEFAULT_CONFIG合并。对照 orchestrator.ts 中的默认配置可梳理出每个开关的真实含义与默认值配置项默认值作用LOG_AGENT_CHATfalse是否记录与智能体的对话交互日志LOG_CLASSIFIER_CHATfalse是否记录与分类器的对话交互日志LOG_CLASSIFIER_RAW_OUTPUTfalse是否记录分类器未加工的原始输出LOG_CLASSIFIER_OUTPUTfalse是否记录分类器处理后的输出即最终意图判定结果LOG_EXECUTION_TIMESfalse是否记录分类耗时智能体处理耗时等各阶段执行时间MAX_RETRIES3分类器返回异常 XML 时的最大重试次数USE_DEFAULT_AGENT_IF_NONE_IDENTIFIEDtrue分类器未识别出任何智能体时是否回退到默认智能体为false时向用户返回提示语NO_SELECTED_AGENT_MESSAGEIm sorry, I couldnt determine how to handle your request...未选中任何智能体时展示给用户的兜底消息GENERAL_ROUTING_ERROR_MSG_MESSAGE未定义路由过程中发生异常时的通用错误消息MAX_MESSAGE_PAIRS_PER_AGENT100每个智能体保留的最大用户-助手消息对数实际存储量为该值 × 2 条消息需要说明的是USE_DEFAULT_AGENT_IF_NONE_IDENTIFIED只有在通过setDefaultAgent或构造参数defaultAgent设置了默认智能体时才生效该回退逻辑可在 orchestrator.ts 的 classifyRequest 方法 中看到。4.2 添加专业化智能体随后注册两个负责不同领域的BedrockLLMAgentimport { BedrockLLMAgent } from multi-agent-orchestrator; orchestrator.addAgent( new BedrockLLMAgent({ name: Tech Agent, description: Specializes in technology areas including software development, hardware, AI, cybersecurity, blockchain, cloud computing, emerging tech innovations, and pricing/costs related to technology products and services., }) ); orchestrator.addAgent( new BedrockLLMAgent({ name: Health Agent, description: Focuses on health and medical topics such as general wellness, nutrition, diseases, treatments, mental health, fitness, healthcare systems, and medical terminology or concepts., }) );description不是装饰性字段它同时服务于两条链路分类阶段分类器把全部智能体的namedescription注入系统提示词据此把用户输入路由到语义最匹配的智能体生成阶段BedrockLLMAgent的默认系统提示词模板为You are a ${this.name}. ${this.description} ...即智能体在回答时也会携带该描述作为角色设定见 bedrockLLMAgent.ts 的构造函数。addAgent会以智能体name生成唯一 ID去除非字母数字字符、空格转连字符、转小写重复注册相同 ID 会抛出异常见 orchestrator.ts 的 addAgent。BedrockLLMAgent除name/description外还支持以下常用选项bedrockLLMAgent.ts 的类型定义modelId使用的 Bedrock 模型 ID默认anthropic.claude-3-haiku-20240307-v1:0常量定义见 types/index.tsregionBedrock 服务区域缺省时使用默认凭证链streaming是否流式返回默认falseinferenceConfigmaxTokens、temperature、topP、stopSequences等推理参数guardrailConfigBedrock Guardrails 的guardrailIdentifier与guardrailVersionretriever接入向量检索器自动把检索上下文拼入系统提示词toolConfigtool工具定义、useToolHandler工具执行回调、toolMaxRecursions工具调用最大轮数默认 20customSystemPrompt自定义系统提示词模板与模板变量。4.3 实现主逻辑并路由请求接下来编写入口逻辑向编排器提交一条用户查询const userId quickstart-user; const sessionId quickstart-session; const query What are the latest trends in AI?; console.log(\nUser Query: ${query}); async function main() { try { const response await orchestrator.routeRequest(query, userId, sessionId); console.log(\n** RESPONSE ** \n); console.log( Agent ID: ${response.metadata.agentId}); console.log( Agent Name: ${response.metadata.agentName}); console.log( User Input: ${response.metadata.userInput}); console.log( User ID: ${response.metadata.userId}); console.log( Session ID: ${response.metadata.sessionId}); console.log( Additional Parameters:, response.metadata.additionalParams); console.log(\n Response: ${response.output}); } catch (error) { console.error(An error occurred:, error); } } main();这里值得展开说明routeRequest的完整调用链实现在 orchestrator.ts 的 routeRequestclassifyRequest先从存储中取出该userId sessionId的聊天历史再调用分类器classifier.classify(userInput, chatHistory)agentProcessRequest把分类结果selectedAgent交给dispatchToAgent后者从存储取回该智能体的历史对话后调用selectedAgent.processRequest(...)生成回答结果封装若智能体返回的是异步可迭代对象流式响应则返回{ metadata, output: AccumulatorTransform, streaming: true }否则返回{ metadata, output: string, streaming: false }并在智能体saveChat开启时把本次问答写入存储异常兜底分类失败时metadata.agentId为no_agent_selected、agentName为No Agent输出为NO_SELECTED_AGENT_MESSAGE。response.metadata携带agentId、agentName、userInput、userId、sessionId、additionalParams等字段接口定义见 orchestrator.ts 的 RequestMetadata便于上层 UI 展示由哪个智能体回答。4.4 运行应用npx ts-node quickstart.ts运行后终端会依次打印User Query→ 分类与路由日志取决于LOG_*开关→RESPONSE块含 Agent ID / Agent Name / 最终回答。由于示例查询 What are the latest trends in AI? 属于技术话题分类器应将其路由给 Tech Agent。五、默认行为与底层机制解读入门文档的Implementation Notes部分点明了三条默认行为这里结合源码给出更完整的解释。5.1 默认分类器BedrockClassifier Claude 3.5 Sonnet未显式传入classifier时编排器使用new BedrockClassifier()见 orchestrator.ts 构造函数。该分类器的默认模型为anthropic.claude-3-5-sonnet-20240620-v1:0见 bedrockClassifier.ts。分类器的判定并非纯文本提示而是通过工具调用Function Calling约束结构化输出它把analyzePrompt工具输入 schema 含userinput、selected_agent、confidence三个必填字段注入ConverseCommand强制模型返回结构化的分类结果再据此查表定位智能体并解析置信度见 bedrockClassifier.ts 的 processRequest。若使用 Anthropic 或 Mistral Large 模型还会额外设置toolChoice强制命中该工具。这解释了LOG_CLASSIFIER_RAW_OUTPUT查看原始输出与LOG_CLASSIFIER_OUTPUT查看解析后的意图结果两个开关的差异来源。5.2 默认智能体BedrockLLMAgent Claude 3 Haiku示例中的BedrockLLMAgent未指定modelId因此使用默认的anthropic.claude-3-haiku-20240307-v1:0见 bedrockLLMAgent.ts 的构造函数。其底层通过 AWS SDK 的ConverseCommand/ConverseStreamCommand与 Bedrock 交互非流式模式下会循环处理模型输出 → 若含toolUse则执行工具 → 结果回填 → 再次调用直到end_turn或达到toolMaxRecursions上限流式模式下则逐 chunkyield文本增量见 bedrockLLMAgent.ts 的 processRequest 与 handleStreamingResponse。5.3 默认存储InMemoryChatStorage未传入storage时使用new InMemoryChatStorage()见 orchestrator.ts 构造函数。它的实现基于内存Map以${userId}#${sessionId}#${agentId}为键保存按时间戳排序的消息列表并提供连续消息去重、maxHistorySize截断、跨智能体历史合并供分类器参考等能力见 memoryChatStorage.ts。这意味着服务重启后对话历史即丢失生产环境应按需替换为 DynamoDB 或 SQL 存储。六、进阶仓库中的交互式本地 Demo入门文档只覆盖了单次请求而仓库的 local-orchestrator.ts 是一个完整的终端交互式版本通过readline循环接收用户输入直到键入exit退出。它在快速入门示例基础上叠加了四类能力非常适合作为下一步的参考实现。6.1 多类型智能体混编Demo 同时注册了四类智能体展示了编排器对异构智能体的统一抽象它们都继承自 agent.ts 的 Agent 基类BedrockLLMAgentTech Agent开启streaming: true并设置inferenceConfig.temperature: 0.1以获得更确定性的回答LexBotAgent接入 Amazon Lex 机器人需要botId、botAliasId、localeId必填缺失会抛异常底层通过RecognizeTextCommand调用 Lex Runtime V2见 lexBotAgent.tsAmazonBedrockAgent接入 Bedrock 中已创建的 Agent需要agentId与agentAliasId支持enableTrace与streaming见 amazonBedrockAgent.tsLambdaAgent把请求转发给 AWS Lambda 函数支持自定义inputPayloadEncoder/outputPayloadDecoder编解码载荷见 lambdaAgent.ts。Lex、Bedrock Agent、Lambda 三者的占位符{{REPLACE_WITH_...}}需要替换为你实际的 AWS 资源 ID 才能运行。6.2 工具调用天气智能体Demo 中最具实战价值的是 Weather Agent它通过toolConfig注册了一个Weather_Tool输入为 WGS84 经纬度并配套weatherToolHanlder回调与自定义系统提示词const weatherAgent new BedrockLLMAgent({ name: Weather Agent, description: Specialized agent for giving weather condition from a city., streaming: true, inferenceConfig: { temperature: 0.1 }, toolConfig: { tool: weatherToolDescription, useToolHandler: weatherToolHanlder, toolMaxRecursions: 5, } }); weatherAgent.setSystemPrompt(WEATHER_PROMPT); orchestrator.addAgent(weatherAgent);其中WEATHER_PROMPT明确约束只调用 Weather_Tool、绝不编造数据、按经纬度推断城市位置等行为见 weather_tool.ts而weatherToolHanlder在收到模型的toolUse请求后调用 Open-Meteo 公共天气 API并把结果以toolResult消息回填给模型。这正是BedrockLLMAgent内部工具调用循环见 5.2 节的完整落地样例。6.3 流式响应的消费方式Demo 通过response.streaming标志区分两种响应流式时用for await (const chunk of response.output)逐块写出文本并先打印 metadata 再输出内容流非流式时直接打印response.output字符串见 local-orchestrator.ts。该判断与编排器内部输出是否为异步可迭代对象的判定一一对应。6.4 智能体注册表与重叠分析Demo 还演示了两个实用 APIorchestrator.getAllAgents()遍历已注册智能体的name与descriptionorchestrator.analyzeAgentOverlap()调用AgentOverlapAnalyzer对智能体描述做语义重叠分析帮助开发者发现描述过于相似的智能体可能引发错误路由实现位于 agentOverlapAnalyzer.ts。6.5 运行交互式 Demo在仓库 examples/local-demo 目录下执行npm install # 配置 AWS 凭证与 REGION可通过 .env 文件 npx ts-node local-orchestrator.ts启动后会打印全部已注册智能体并进入对话循环输入问题后回车即可看到对应智能体的流式回答。注意除 Tech Agent 与 Weather Agent 外其余智能体需先替换占位符为真实 AWS 资源 ID分类器所在区域通过REGION环境变量读取见 bedrockClassifier.ts 构造函数。七、下一步从 Demo 走向生产入门文档的Next Steps给出了四条演进路径这里补充对应的仓库依据添加更多专业化智能体继续用addAgent注册新的BedrockLLMAgent并通过analyzeAgentOverlap()验证描述区分度描述写得越具体、越不重叠分类准确率越高实现持久化存储将默认的InMemoryChatStorage替换为 DynamoDB 存储storage/dynamoDbChatStorage.ts或 SQL 存储storage/sqlChatStorage.ts在构造MultiAgentOrchestrator时通过storage参数注入即可在服务重启后保留对话上下文自定义错误处理通过config中的CLASSIFICATION_ERROR_MESSAGE、NO_SELECTED_AGENT_MESSAGE、GENERAL_ROUTING_ERROR_MSG_MESSAGE定制面向用户的兜底文案并借助MAX_RETRIES、USE_DEFAULT_AGENT_IF_NONE_IDENTIFIED调节容错行为实现流式响应为BedrockLLMAgent开启streaming: true按 6.3 节的模式在服务端逐 chunk 消费response.output即可向前端提供类打字机效果。若想对比 Python 侧的实现可参考仓库中的 python-local-demo.md其 API 设计与 TypeScript 版本一一对应。至此从入门文档的最小示例到仓库的交互式 Demo你已经掌握了multi-agent-orchestrator在 TypeScript 本地环境下的完整实践路径。【免费下载链接】agent-squadFlexible and powerful framework for managing multiple AI agents and handling complex conversations项目地址: https://gitcode.com/GitHub_Trending/mu/agent-squad创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考