基于Azure AI的多智能体协作系统：从LLM到自动化工作流的实战指南

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全家桶，并非偶然，而是一套经过深思熟虑的、能保证生产环境可靠性的组合拳。

1. Azure OpenAI Service：这是整个系统的“大脑”。选择它而不是直接使用OpenAI的公有API，主要出于几点考虑：

   • 数据安全与合规：对于企业级应用，数据不出境、符合当地法规是硬性要求。Azure OpenAI服务运行在Azure云上，提供了明确的数据处理协议和合规性认证。
   • 与企业现有系统集成：可以方便地使用Azure Active Directory进行身份验证和权限管理，与Key Vault等密钥管理服务无缝对接。
   • 稳定的API与SLA保障：Azure提供了服务等级协议（SLA），对于需要7x24小时运行的生产应用来说至关重要。项目指定使用gpt-4o和gpt-4o-mini，前者负责需要强推理和复杂任务编排的环节（如研究、写作），后者负责一些轻量级或辅助性任务，以优化成本。

2. Azure AI Agent Service & Bing Grounding Tool：这是实现“联网搜索”能力的关键。普通的GPT模型知识有截止日期，且无法获取实时信息。Bing Grounding Tool相当于给模型装了一个“浏览器”。当研究智能体需要信息时，它可以通过这个工具发起Bing搜索，并将返回的网页摘要作为上下文喂给模型。这确保了文章内容的时效性和事实依据。选择Azure AI Agent Service内置的工具，而不是自己调用搜索API再拼接Prompt，好处在于服务层已经做好了工具调用的标准化封装、错误处理和上下文管理，开发更省心。

3. Azure AI Search：这是实现“产品推荐”的基石。项目预先把Contoso公司的产品目录（比如帐篷、睡袋、炉具等）转换成了向量（Embedding），并存储在了Azure AI Search的向量索引中。当产品智能体工作时，它会将用户主题（如“阿拉斯加露营”）也转换成向量，然后在索引中进行语义相似度搜索。这意味着即使搜索词和产品描述没有完全相同的字眼，只要语义相近（比如“极寒环境睡眠解决方案”匹配到“抗零下30度羽绒睡袋”），也能被检索出来。这比传统的关键词匹配要强大和智能得多。

4. 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为简化应用部署而提供的“大杀器”。

1. 身份认证：首先需要执行azd auth login和az login --use-device-code。这里有个细节：azd和az（Azure CLI）的认证是独立的，都需要做。--use-device-code参数适用于无头环境（如Codespaces），它会给你一个链接和代码，让你去浏览器登录，非常适合云端开发环境。

2. 执行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仓库权限的设置，我们可以先跳过，专注于核心功能。

3. 获取访问地址：部署成功后，在终端输出的最后部分，你会看到类似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（或类似框架）前端。

1. 启动后端API：

   cd ./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格式的文章，说明后端智能体工作流完全正常。

2. 启动前端Web界面：

   # 新开一个终端窗口 cd ./src/web npm install # 首次运行需要安装依赖 npm run dev

   前端通常会在5173端口启动。打开浏览器访问http://localhost:5173，你就会看到一个简洁的UI界面。在这里输入主题和指令，点击“Start Work”，就能直观地看到整个多智能体流水线是如何一步步执行，并最终生成文章的。界面中通常还有一个“调试”按钮，可以展开查看每个智能体的具体输入和输出，这对于理解工作流和调试问题至关重要。

3. 直接运行编排器（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向量索引。

• 向量搜索流程：

  1. 编码（Embedding）：将用户输入的主题（如“阿拉斯加露营”）通过Azure OpenAI的Embedding模型（如text-embedding-3-small）转换为一个高维向量。
  2. 检索（Retrieval）：在Azure AI Search的contoso-products索引中，执行向量相似度搜索（通常使用余弦相似度），找出与查询向量最接近的若干个产品向量。
  3. 生成响应：将检索到的产品信息（如名称、描述、特点、价格）作为上下文，连同Prompt一起发送给大模型。Prompt会要求模型以“产品专家”的口吻，筛选并介绍最相关的几款产品。

• 关键配置：在product_agent.py中，你会看到如何初始化Azure AI Search的客户端，以及如何构建向量查询。search_top_k这个参数（比如设为3）决定了返回多少个最相关的产品，需要根据实际产品库大小和需求来调整。

4.3 写作智能体（Writer Agent）与编辑智能体（Editor Agent）：从草稿到成品的“作家”与“主编”

• 写作智能体：它接收来自研究智能体的“事实依据”和产品智能体的“产品推荐”，结合用户最初的“指令”（如“详细说明装备”），负责撰写文章的初稿。它的Prompt会强调文章结构（如引言、装备详解、安全建议、总结）、内容的整合以及语言的流畅性。

• 编辑智能体：它接收写作智能体生成的初稿，负责进行最后的润色。它的任务可能包括：检查并修正语法错误、统一全文语气和风格、优化段落衔接、确保没有事实性矛盾（虽然主要事实已由研究智能体保证），并让文章读起来更专业、更吸引人。这是一种典型的“链式思考（Chain-of-Thought）”或“迭代优化”策略，让模型自己检查和完善自己的输出，通常能显著提升最终质量。

工作流编排（Orchestrator）：orchestrator.py是这个交响乐团的“指挥”。它定义了智能体之间的执行顺序和数据流向：

用户输入 -> 研究智能体（并行）-> 产品智能体 -> 写作智能体 -> 编辑智能体 -> 最终输出

研究智能体和产品智能体可以并行执行以提高速度，它们的结果汇聚后传递给写作智能体。这种编排逻辑清晰，易于理解和扩展。如果你想增加一个“图片建议智能体”，只需要在编排器中插入到合适的位置即可。

5. 高级功能：追踪、评估与持续集成

一个成熟的生产级AI应用，绝不能只停留在“能跑通”的层面。这个项目模板还提供了用于监控、评估和自动化部署的高级功能，这些往往是实战中价值最高的部分。

5.1 使用Prompty Tracing进行可视化调试

当文章生成效果不佳时，如何定位是哪个环节出了问题？Prompty框架内置了追踪（Tracing）功能。

1. 启用追踪：在运行orchestrator.py之前，设置环境变量LOCAL_TRACING=true。

   export LOCAL_TRACING=true # Linux/macOS # 或 set LOCAL_TRACING=true # Windows (CMD) # 或 $env:LOCAL_TRACING="true" # Windows (PowerShell) cd ./src/api python -m orchestrator

2. 查看追踪结果：运行后，在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. 评估指标：脚本定义了四个评估维度，由专门的“评估智能体”来打分（1-5分）：

   • 连贯性（Coherence）：文章逻辑是否通顺，段落衔接是否自然。
   • 流畅性（Fluency）：语言是否地道，有无语法错误或生硬表达。
   • 相关性（Relevance）：文章内容是否紧扣用户提供的主题和指令。
   • 有据性（Groundedness）：文章中的事实陈述（特别是来自研究智能体的部分）是否与提供的来源材料一致，有无“幻觉”（Hallucination）。

2. 运行评估：

   cd ./src/api python -m evaluate.evaluate

   脚本会读取eval_inputs.jsonl文件中的多条测试用例（每条包含主题、指令、以及预先准备好的“标准答案”或参考材料），依次运行整个智能体工作流，然后调用评估智能体对输出结果进行打分，最后输出一个平均分报告。

3. 集成到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的密钥扫描，防止意外将密钥提交到代码库。

• 成本：主要成本来自三部分：

  1. Azure OpenAI：gpt-4o和gpt-4o-mini的Token消耗费用。gpt-4o更贵但能力更强，用于研究、写作等核心环节；gpt-4o-mini成本低，可用于一些辅助任务。需要根据流量预估费用。
  2. Azure AI Search：根据所选层级（如基本版、标准版）收取费用，与数据存储量和搜索操作量相关。
  3. Bing Grounding：根据搜索交易次数收费。 在部署前，强烈建议使用 Azure定价计算器 ，根据预估的用户请求量进行成本测算。对于测试环境，可以选择最低配置以控制成本。

这个“Contoso创意写作助手”项目，远不止是一个Demo。它是一个企业级AI应用的标准样板，展示了从架构设计、开发部署、到监控评估的完整闭环。通过拆解和学习它，你不仅能学会如何用Azure构建多智能体应用，更能掌握一整套构建可靠、可维护、可评估的生产级AI系统的工程化思维和方法。