1. 项目概述一个基于多智能体协作的创意写作助手最近在做一个挺有意思的项目叫“Contoso创意写作助手”。简单来说这玩意儿能帮你写文章但不是那种简单的文本生成。它的核心思路是模仿一个专业的写作团队把一个大任务拆解成几个小任务交给不同的“专家”也就是AI智能体去完成最后再整合起来。比如你想写一篇关于“阿拉斯加露营”的文章你只需要告诉它主题和具体要求比如“需要详细说明所需装备”它就能自动调用不同的智能体去网上搜索资料、查找相关产品信息、撰写初稿最后再润色编辑给你一篇结构完整、内容详实的文章。这个项目本质上是一个多智能体Multi-Agent应用的实战案例。它基于微软的Azure AI生态构建核心驱动力是Azure OpenAI的GPT-4o模型并整合了Azure AI Agent Service中的Bing联网搜索工具和Azure AI Search向量数据库。整个流程就像一个流水线研究智能体负责用Bing搜索获取最新、最相关的背景信息产品智能体负责从预设的产品库比如一个户外用品数据库里通过语义搜索找出与主题最匹配的商品写作智能体负责综合前两者的信息生成结构化的文章草稿编辑智能体则负责最后的语言润色和风格统一。我之所以花时间研究这个项目是因为它清晰地展示了如何将大语言模型LLM从单纯的“聊天机器人”或“文本补全工具”升级为一个可以执行复杂、多步骤任务的自动化工作流。对于开发者、内容创作者甚至是一些需要自动化报告生成的企业场景这种架构思路非常有借鉴意义。它不仅仅是调用一次API而是设计了一套完整的、可观测的、可评估的协作系统。2. 核心架构与设计思路拆解2.1 为什么选择多智能体架构单次调用一个大模型比如GPT-4来生成一篇长文效果往往不稳定。模型可能会遗漏关键信息结构可能混乱或者陷入“车轱辘话”的循环。多智能体架构的核心优势在于“分而治之”和“专业分工”。分而治之将一个复杂的“写文章”任务拆解为“研究”、“找产品”、“写作”、“编辑”四个相对独立且更简单的子任务。每个子任务的目标明确给模型的指令Prompt也可以设计得更精准、更具体从而大幅提升每个环节的输出质量。专业分工我们可以为每个智能体定制专属的“人设”和工具。例如研究智能体被赋予“资深研究员”的角色并配备了Bing搜索工具它的唯一目标就是高效、准确地搜集信息。产品智能体则被设计为“产品专家”专注于从向量数据库中检索最相关的商品。这种角色扮演Role-Playing能更好地引导模型的行为。这种架构的另一个巨大好处是可观测性Observability和可调试性。在传统单次调用中如果结果不理想你很难定位问题出在哪里是Prompt写得不好还是模型“开小差”了而在多智能体流程中你可以清晰地看到每个智能体的输入和输出。如果最终文章的产品信息有误你可以直接去检查产品智能体的搜索结果和它接收到的指令从而进行针对性优化。2.2 技术栈选型背后的考量这个项目选择微软Azure全家桶并非偶然而是一套经过深思熟虑的、能保证生产环境可靠性的组合拳。Azure OpenAI Service这是整个系统的“大脑”。选择它而不是直接使用OpenAI的公有API主要出于几点考虑数据安全与合规对于企业级应用数据不出境、符合当地法规是硬性要求。Azure OpenAI服务运行在Azure云上提供了明确的数据处理协议和合规性认证。与企业现有系统集成可以方便地使用Azure Active Directory进行身份验证和权限管理与Key Vault等密钥管理服务无缝对接。稳定的API与SLA保障Azure提供了服务等级协议SLA对于需要7x24小时运行的生产应用来说至关重要。项目指定使用gpt-4o和gpt-4o-mini前者负责需要强推理和复杂任务编排的环节如研究、写作后者负责一些轻量级或辅助性任务以优化成本。Azure AI Agent Service Bing Grounding Tool这是实现“联网搜索”能力的关键。普通的GPT模型知识有截止日期且无法获取实时信息。Bing Grounding Tool相当于给模型装了一个“浏览器”。当研究智能体需要信息时它可以通过这个工具发起Bing搜索并将返回的网页摘要作为上下文喂给模型。这确保了文章内容的时效性和事实依据。选择Azure AI Agent Service内置的工具而不是自己调用搜索API再拼接Prompt好处在于服务层已经做好了工具调用的标准化封装、错误处理和上下文管理开发更省心。Azure AI Search这是实现“产品推荐”的基石。项目预先把Contoso公司的产品目录比如帐篷、睡袋、炉具等转换成了向量Embedding并存储在了Azure AI Search的向量索引中。当产品智能体工作时它会将用户主题如“阿拉斯加露营”也转换成向量然后在索引中进行语义相似度搜索。这意味着即使搜索词和产品描述没有完全相同的字眼只要语义相近比如“极寒环境睡眠解决方案”匹配到“抗零下30度羽绒睡袋”也能被检索出来。这比传统的关键词匹配要强大和智能得多。Prompty这是一个管理Prompt的框架。它将Prompt从代码中分离出来保存为独立的.prompty文件。这样做有几个显著优势版本控制Prompt可以和代码一样用Git管理清晰地看到每次修改的历史和差异。集中管理所有智能体的Prompt都放在/agents目录下结构清晰便于查找和修改。参数化与复用Prompty文件支持变量注入使得同一个Prompt模板可以根据不同输入动态变化提高了复用性。评估与追踪Prompty与评估框架集成更好便于对不同的Prompt版本进行A/B测试查看哪个版本生成的结果质量更高。实操心得模型选择与区域坑点项目文档特别强调推荐使用East US 2区域并需要至少80 TPM每分钟令牌数的gpt-4o配额。这不是随便说的。在项目初期我曾在另一个区域部署结果Bing Grounding Tool调用一直失败排查很久才发现是该区域当时还未支持gpt-4o模型与Agent Service的特定集成。所以严格按照推荐的区域和模型规格进行部署能避开很多隐形的兼容性大坑。部署前务必去Azure OpenAI的模型可用性页面再确认一次。3. 项目部署与本地运行全流程解析纸上得来终觉浅绝知此事要躬行。下面我就带大家走一遍从零部署和运行这个项目的完整流程并穿插一些我踩过的坑和总结的技巧。3.1 环境准备三种方式的抉择项目提供了三种启动方式GitHub Codespaces、VS Code Dev Containers和本地环境。对于新手或想快速体验的开发者我强烈推荐GitHub Codespaces。GitHub Codespaces这是最无痛的方式。点击项目页面的“Open in Codespaces”按钮云端会自动为你创建一个预装好所有依赖Python, Node.js, Azure CLI等的完整开发环境。你只需要在终端里登录Azure并执行部署命令即可。它完美解决了“在我机器上能跑”的环境问题特别适合快速验证和演示。VS Code Dev Containers如果你更喜欢在本地VS Code中开发但又不希望污染本机环境这是次优选择。它利用Docker容器在本地创建一个隔离的、与环境定义文件完全一致的空间。需要注意Windows用户可能会遇到行尾序列CRLF vs LF导致的脚本执行错误文档中已给出解决方案。纯本地环境适合对自身开发环境有完全控制需求的高级用户。你需要手动安装Azure Developer CLI (azd)、Python 3.10、Docker和Git。Windows用户需要注意项目的一些部署后钩子hooks脚本是Shell脚本建议使用Git Bash来执行azd命令避免PowerShell或CMD可能带来的路径和语法问题。我的选择与建议初次接触时毫不犹豫地用Codespaces。当你需要深度定制或进行二次开发时再考虑迁移到Dev Containers或本地环境。这能帮你把精力集中在理解项目逻辑上而不是折腾环境。3.2 使用Azure Developer CLI (azd) 一键部署无论选择哪种环境核心部署命令都是azd up。这个命令背后做了大量工作是Azure为简化应用部署而提供的“大杀器”。身份认证首先需要执行azd auth login和az login --use-device-code。这里有个细节azd和azAzure CLI的认证是独立的都需要做。--use-device-code参数适用于无头环境如Codespaces它会给你一个链接和代码让你去浏览器登录非常适合云端开发环境。执行azd up这个命令会触发一个完整的流程资源预配Provision根据项目根目录下的infra/文件夹里的Bicep模板一种Azure的声明式基础设施即代码语言在指定的Azure订阅中创建所有需要的资源。这包括Azure OpenAI服务部署gpt-4o和gpt-4o-mini模型、Azure AI Search服务创建contoso-products索引并导入向量数据、Azure Container Apps用于托管Web前端和API后端、Application Insights用于监控、Key Vault用于安全存储密钥等。代码部署Deploy将本地的应用代码src/目录打包成容器镜像推送到Azure Container Registry并部署到上一步创建好的Container Apps中。交互式配置过程中CLI会交互式地询问你一些配置比如环境名称Environment Name给你的这次部署起个名字如dev或test。所有资源都会以这个名为前缀方便管理。Azure区域Azure Location这里务必输入eastus2除非你确认其他区域支持所有所需服务。是否配置GitHub Actions它会问你是否要设置CI/CD流水线。对于初次体验建议输入N否。这个配置过程较慢且会涉及GitHub仓库权限的设置我们可以先跳过专注于核心功能。获取访问地址部署成功后在终端输出的最后部分你会看到类似Ingress Updated. Access your app at https://your-app-name.region.azurecontainerapps.io/的信息。这个就是你的应用公网访问地址记下来。避坑指南azd up常见问题权限不足确保你登录的Azure账号在目标订阅中拥有“所有者Owner”或“贡献者Contributor”以及“用户访问管理员User Access Administrator”角色否则创建某些资源如分配托管标识时会失败。配额限制Azure OpenAI的gpt-4o模型可能需要单独申请提升配额TPM。如果部署时卡在创建Azure OpenAI资源这一步并报错需要去Azure门户手动提交配额提升请求。Bing Grounding访问权限这是一个预览功能可能需要单独申请加入允许列表。如果后续测试时研究智能体报错提示无权访问Bing Grounding需要去Azure AI Studio中检查相应Azure OpenAI资源的“模型部署”部分确保Bing Grounding已启用。3.3 本地运行与深度测试部署到云端后应用已经可以访问。但为了开发和调试我们经常需要在本地运行。项目包含一个FastAPI后端和一个React或类似框架前端。启动后端APIcd ./src/api # 确保虚拟环境已激活依赖已安装 (pip install -r requirements.txt) fastapi dev main.py这会在本地8000端口启动FastAPI开发服务器。关键一步如果你在Codespaces里运行需要去VS Code的“端口PORTS”标签页将8000和5173前端端口的“可见性”从“私有”改为“公共”否则浏览器无法访问。你可以直接测试API端点在浏览器打开http://localhost:8000/get_article?context阿拉斯加露营instructions重点介绍必备的防寒装备和安全性建议。如果看到返回了一篇JSON格式的文章说明后端智能体工作流完全正常。启动前端Web界面# 新开一个终端窗口 cd ./src/web npm install # 首次运行需要安装依赖 npm run dev前端通常会在5173端口启动。打开浏览器访问http://localhost:5173你就会看到一个简洁的UI界面。在这里输入主题和指令点击“Start Work”就能直观地看到整个多智能体流水线是如何一步步执行并最终生成文章的。界面中通常还有一个“调试”按钮可以展开查看每个智能体的具体输入和输出这对于理解工作流和调试问题至关重要。直接运行编排器Orchestrator进行脚本测试 有时你不想启动整个Web服务只想快速测试智能体链的逻辑。可以运行cd ./src/api python -m orchestrator这个脚本会使用预设的参数直接调用整个智能体工作流并在控制台打印出最终文章。这是进行批量测试或集成到其他自动化脚本中的好方法。4. 核心代码与智能体工作流剖析理解了怎么跑起来我们再来深入代码看看这四个智能体具体是怎么协作的。代码主要位于src/api/agents/目录下。4.1 研究智能体Research Agent获取实时信息的“侦察兵”这个智能体的核心文件是research_agent.prompty和research_agent.py。它的使命是利用Bing Grounding Tool获取关于用户主题的最新、最可靠的网络信息。Prompt设计在.prompty文件中你会看到类似这样的角色定义你是一个专业的研究员。你的任务是根据用户提供的主题进行深入的网络搜索并整理出关键、准确、最新的信息。请忽略过时或不可靠的来源。你的输出应该是一个结构清晰的信息摘要包含主要事实、数据和观点。这个Prompt明确了智能体的角色、任务和输出格式要求引导模型专注于“信息搜集与整理”而不是自由发挥。工具调用在Python代码中智能体被配置为可以使用bing_grounding工具。当模型认为需要搜索时它会生成一个工具调用的请求框架会实际执行Bing搜索并将搜索结果返回给模型模型再基于这些结果组织答案。输出研究智能体的输出是一段整理好的文本作为后续写作的“事实依据”。4.2 产品智能体Product Agent精通商品的“导购员”核心文件是product_agent.prompty和product_agent.py。它不搜索互联网而是查询内部的Azure AI Search向量索引。向量搜索流程编码Embedding将用户输入的主题如“阿拉斯加露营”通过Azure OpenAI的Embedding模型如text-embedding-3-small转换为一个高维向量。检索Retrieval在Azure AI Search的contoso-products索引中执行向量相似度搜索通常使用余弦相似度找出与查询向量最接近的若干个产品向量。生成响应将检索到的产品信息如名称、描述、特点、价格作为上下文连同Prompt一起发送给大模型。Prompt会要求模型以“产品专家”的口吻筛选并介绍最相关的几款产品。关键配置在product_agent.py中你会看到如何初始化Azure AI Search的客户端以及如何构建向量查询。search_top_k这个参数比如设为3决定了返回多少个最相关的产品需要根据实际产品库大小和需求来调整。4.3 写作智能体Writer Agent与编辑智能体Editor Agent从草稿到成品的“作家”与“主编”写作智能体它接收来自研究智能体的“事实依据”和产品智能体的“产品推荐”结合用户最初的“指令”如“详细说明装备”负责撰写文章的初稿。它的Prompt会强调文章结构如引言、装备详解、安全建议、总结、内容的整合以及语言的流畅性。编辑智能体它接收写作智能体生成的初稿负责进行最后的润色。它的任务可能包括检查并修正语法错误、统一全文语气和风格、优化段落衔接、确保没有事实性矛盾虽然主要事实已由研究智能体保证并让文章读起来更专业、更吸引人。这是一种典型的“链式思考Chain-of-Thought”或“迭代优化”策略让模型自己检查和完善自己的输出通常能显著提升最终质量。工作流编排Orchestratororchestrator.py是这个交响乐团的“指挥”。它定义了智能体之间的执行顺序和数据流向用户输入 - 研究智能体并行- 产品智能体 - 写作智能体 - 编辑智能体 - 最终输出研究智能体和产品智能体可以并行执行以提高速度它们的结果汇聚后传递给写作智能体。这种编排逻辑清晰易于理解和扩展。如果你想增加一个“图片建议智能体”只需要在编排器中插入到合适的位置即可。5. 高级功能追踪、评估与持续集成一个成熟的生产级AI应用绝不能只停留在“能跑通”的层面。这个项目模板还提供了用于监控、评估和自动化部署的高级功能这些往往是实战中价值最高的部分。5.1 使用Prompty Tracing进行可视化调试当文章生成效果不佳时如何定位是哪个环节出了问题Prompty框架内置了追踪Tracing功能。启用追踪在运行orchestrator.py之前设置环境变量LOCAL_TRACINGtrue。export LOCAL_TRACINGtrue # Linux/macOS # 或 set LOCAL_TRACINGtrue # Windows (CMD) # 或 $env:LOCAL_TRACINGtrue # Windows (PowerShell) cd ./src/api python -m orchestrator查看追踪结果运行后在src/api目录下会生成一个.runs文件夹里面包含.tracy文件。用支持该格式的工具如VS Code的Prompty扩展打开你能看到一个清晰的调用链图。图中会显示每个智能体被调用的耗时、输入/输出的Token数量、具体的Prompt内容、工具调用的请求和响应甚至模型思考的中间过程。实操心得Tracing是优化Prompt的利器我曾经遇到产品推荐总是不太精准的问题。通过Tracing我打开了产品智能体的调用详情发现模型在生成回复前内部推理Reasoning步骤里对用户查询的理解出现了细微偏差。于是我去修改了product_agent.prompty在开头更加强调了“从给定的产品列表中选取”并提供了更明确的输出格式示例。修改后再次运行并对比Tracing看到了模型推理路径的变化最终输出果然更符合预期了。没有Tracing优化Prompt就像蒙着眼睛调试。5.2 构建自动化的质量评估体系如何衡量每次代码或Prompt修改后AI应用的整体输出质量是变好还是变差了不能只靠人肉看。项目中的evaluate.py脚本和eval_inputs.jsonl文件构建了一个简单的自动化评估管道。评估指标脚本定义了四个评估维度由专门的“评估智能体”来打分1-5分连贯性Coherence文章逻辑是否通顺段落衔接是否自然。流畅性Fluency语言是否地道有无语法错误或生硬表达。相关性Relevance文章内容是否紧扣用户提供的主题和指令。有据性Groundedness文章中的事实陈述特别是来自研究智能体的部分是否与提供的来源材料一致有无“幻觉”Hallucination。运行评估cd ./src/api python -m evaluate.evaluate脚本会读取eval_inputs.jsonl文件中的多条测试用例每条包含主题、指令、以及预先准备好的“标准答案”或参考材料依次运行整个智能体工作流然后调用评估智能体对输出结果进行打分最后输出一个平均分报告。集成到CI/CD这才是评估的终极价值所在。你可以配置GitHub Actions使得每次向主分支main推送代码时自动运行这个评估脚本。如果评估分数低于某个阈值比如平均分低于4.0流水线可以标记为失败阻止有质量倒退风险的代码被部署。这为AI应用的“质量门禁”提供了可量化的手段。通过运行azd pipeline config命令可以快速生成对应的GitHub Actions工作流文件。5.3 安全与成本考量安全项目模板默认使用了Azure的托管标识Managed Identity。这意味着运行在Azure Container Apps中的应用无需在代码或环境变量中硬编码任何API密钥、连接字符串等敏感信息。应用通过其自身的身份向Azure OpenAI、Azure AI Search等服务请求令牌权限通过Azure RBAC进行管理这是云原生应用安全的最佳实践。同时项目也推荐启用GitHub的密钥扫描防止意外将密钥提交到代码库。成本主要成本来自三部分Azure OpenAIgpt-4o和gpt-4o-mini的Token消耗费用。gpt-4o更贵但能力更强用于研究、写作等核心环节gpt-4o-mini成本低可用于一些辅助任务。需要根据流量预估费用。Azure AI Search根据所选层级如基本版、标准版收取费用与数据存储量和搜索操作量相关。Bing Grounding根据搜索交易次数收费。 在部署前强烈建议使用 Azure定价计算器 根据预估的用户请求量进行成本测算。对于测试环境可以选择最低配置以控制成本。这个“Contoso创意写作助手”项目远不止是一个Demo。它是一个企业级AI应用的标准样板展示了从架构设计、开发部署、到监控评估的完整闭环。通过拆解和学习它你不仅能学会如何用Azure构建多智能体应用更能掌握一整套构建可靠、可维护、可评估的生产级AI系统的工程化思维和方法。