1. 项目概述一个基于多智能体协作的创意写作助手如果你正在寻找一个能帮你撰写高质量、有深度、且经过充分调研的文章的工具那么“Contoso Creative Writer”这个项目绝对值得你花时间深入研究。这不仅仅是一个简单的“AI写作”应用它是一个由多个专业AI智能体Agent协同工作的复杂系统其核心思想是模拟一个专业的写作团队有研究员负责搜集资料有产品专家负责匹配相关产品有写手负责整合成文还有编辑负责最终润色。整个项目基于微软Azure云平台构建巧妙地利用了Azure OpenAI、Azure AI Agent Service、Azure AI Search以及Bing Grounding等前沿服务并通过Python和Prompty框架将这些能力串联起来形成一个端到端的自动化写作流水线。我花了几天时间从零开始部署并深度体验了这个项目。说实话第一次看到它流畅地生成一篇关于“阿拉斯加露营”的详尽文章从装备推荐到安全须知甚至引用了具体的产品信息时我感到非常震撼。这背后不是单一模型的蛮力输出而是一套清晰、可解释、可扩展的智能体工作流。对于开发者、内容创作者或者任何对AI应用架构感兴趣的人来说这个项目都是一个绝佳的学习范本。它不仅展示了如何将大语言模型LLM用于复杂任务分解更提供了在Azure上构建生产级AI应用的完整实践路径从环境搭建、资源部署、代码结构到最终的前后端集成一应俱全。2. 核心架构与设计思路拆解2.1 为什么选择多智能体架构传统的单模型提示工程在处理复杂、多步骤任务时往往会遇到“幻觉”Hallucination、信息遗漏或逻辑断层等问题。比如你让一个模型“写一篇关于阿拉斯加露营的文章并推荐相关装备”它可能会生成看似通顺但缺乏事实依据或具体产品信息的内容。“Contoso Creative Writer”采用的多智能体Multi-Agent架构正是为了解决这个问题。其设计哲学是“分而治之专业分工”。每个智能体被赋予一个明确的、单一的职责并配备最合适的工具Tools。这种设计带来了几个关键优势可控性与可解释性工作流被分解为可观测的步骤。你可以清晰地看到“研究智能体”搜索了哪些资料“产品智能体”检索了哪些商品以及“写作智能体”是如何整合这些信息的。这大大降低了“黑箱”操作的不确定性。专业化与工具优化不同的智能体可以使用不同的底层模型例如研究可能用更强的gpt-4o而编辑润色用更经济的gpt-4o-mini和专属工具Bing搜索、向量检索使每个环节都达到最佳效果。容错与迭代如果一个智能体如研究的输出不理想可以单独调整其提示词Prompty或工具调用逻辑而不影响其他环节。这比调整一个庞大的、综合性的提示要容易得多。2.2 核心组件与数据流全景整个系统的数据流像一条精心设计的生产线。为了让你更直观地理解我将整个流程的核心步骤和组件梳理如下步骤执行者智能体核心工具/服务输入输出关键动作1. 任务触发用户 / Web前端FastAPI 接口用户输入的主题Context和写作要求InstructionsHTTP请求用户通过Web界面或API提交写作任务。2. 研究与资料搜集研究智能体Azure AI Agent Service 的Bing Grounding Tool用户主题经过网络搜索验证的、相关的背景资料摘要。调用Bing搜索API获取最新、可靠的网络信息作为文章的事实基础。3. 产品信息匹配产品智能体Azure AI Search(向量搜索)用户主题、研究资料从预构建的产品向量库中检索出的、语义上最相关的产品列表及详情。将查询转换为向量在contoso-products索引中进行语义相似度搜索找到匹配的露营装备等产品。4. 内容撰写写作智能体Azure OpenAI (gpt-4o)研究资料、产品信息、用户指令一篇结构完整、融合了资料和产品信息的初稿文章。综合所有输入信息遵循指令如风格、细节要求生成文章草稿。5. 内容润色与审查编辑智能体Azure OpenAI (gpt-4o-mini)写作智能体生成的初稿经过语法修正、风格优化、逻辑增强的最终文章。对初稿进行校对、优化表达、确保连贯性提升文章整体质量。6. 结果呈现流程编排器OrchestratorFastAPI / Web前端编辑后的最终文章在Web界面展示文章并可查看每个智能体的中间输出。将最终结果返回给用户并提供调试视图以观察工作流每一步。这个流程的核心是位于src/api/orchestrator.py的编排器Orchestrator。它不直接处理具体任务而是扮演“项目经理”的角色负责按顺序调用上述四个智能体并将上一个智能体的输出作为下一个智能体的输入进行传递直至任务完成。2.3 技术栈选型背后的考量Azure OpenAI Service作为所有智能体的“大脑”。选择Azure而非直接使用OpenAI API主要出于企业级需求考虑数据隐私数据不出Azure、合规性、与Azure其他服务的原生集成、以及稳定的SLA保障。项目中混合使用gpt-4o用于复杂的研究和写作和gpt-4o-mini用于成本更敏感的编辑任务是成本与效果平衡的典型实践。Azure AI Agent Service这是实现智能体的关键框架。它提供了创建、管理和运行智能体的标准化方式特别是内置了工具调用Tool Calling能力。研究智能体使用的Bing Grounding Tool就是该服务提供的一个官方工具它能确保AI的回复基于实时、权威的网络搜索信息极大增强了内容的真实性和时效性。Azure AI Search用于实现产品的语义搜索。这里没有使用简单的关键词匹配而是利用了其向量搜索Vector Search能力。项目在部署时azd up会预先将一个产品目录contoso-products转换为向量并建立索引。当用户查询“阿拉斯加露营”时产品智能体会将查询向量化并找到向量空间中与之最接近的产品如防寒帐篷、羽绒睡袋即使产品描述中没有完全相同的字眼。Prompty这是一个管理提示词Prompt的框架。它将提示词从代码中分离出来存储为独立的.prompty文件。这样做的好处非常明显提示词版本化、易于迭代优化、支持变量注入和环境配置。每个智能体研究、产品、写作、编辑都有自己的.prompty文件你可以像修改配置文件一样调整它们的“工作说明书”而无需触碰核心业务逻辑代码。FastAPI 前端ViteFastAPI提供了高性能、异步的API后端非常适合这种涉及多次网络调用的AI工作流。前端则是一个简单的React应用用于交互和展示。这种前后端分离的架构清晰、易于维护和扩展。实操心得模型选择与成本控制项目中为不同任务分配不同模型的策略非常聪明。gpt-4o能力更强但更贵用于核心的“研究”和“写作”环节确保信息质量和文章骨架。gpt-4o-mini虽然能力稍弱但成本低、速度快用于“编辑”这种对创造性要求相对较低、更偏向于修正和优化的任务性价比极高。在实际自己的项目中你也可以根据任务复杂度进行类似的模型分级使用。3. 环境准备与项目初始化实战3.1 前期准备账号与权限在敲下第一行命令之前有几项关键的Azure资源访问权限需要提前确认和申请这是后续一切顺利的基础。Azure账户与订阅你需要一个有效的Azure账户。如果是新用户可以注册免费账户并获得一定额度的试用金。最重要的是确保你的订阅Subscription有足够的配额Quota特别是用于部署Azure Container Apps和Azure OpenAI服务的配额。Azure OpenAI服务访问权限这是最大的一个门槛。Azure OpenAI服务目前仍是受限访问Limited Access。你需要提交申请并说明你的使用场景。申请时务必确保你的Azure订阅所在区域如East US 2支持你需要的模型gpt-4o和gpt-4o-mini。项目文档强烈推荐使用East US 2因为该区域通常有最全的模型和服务可用性。Bing Grounding 工具权限研究智能体依赖的Bing Grounding Tool也需要单独在Azure AI Agent Service中启用。这通常需要在Azure门户中为你的AI Agent Service资源申请并添加“Bing Search”能力。Azure AI Search 服务创建一个Azure AI Search服务相对简单但需要注意选择支持向量搜索的层级至少是Basic及以上。避坑指南权限申请与区域选择我的经验是在开始部署前最好先登录Azure门户在目标区域如East US 2尝试手动创建一下这些服务看看是否有权限错误。特别是Azure OpenAI如果申请迟迟未通过整个项目将无法运行。另一个常见问题是某些区域可能不支持gpt-4o的80 TPM每分钟令牌数默认配额你需要联系支持团队申请提高配额否则调用Bing Grounding时可能会因速率限制而失败。3.2 三种开发环境部署方式详解项目提供了三种开箱即用的环境设置方式适合不同背景的开发者。方案一GitHub Codespaces最推荐零配置这是最快捷、最无痛的方式特别适合快速体验和评估项目。点击项目README中的“Open in GitHub Codespaces”徽章按钮。等待几分钟一个基于浏览器的完整VS Code开发环境包含预装好的Python、Node.js、Docker、Azure CLI等所有工具就会准备就绪。在终端中依次执行以下命令完成身份认证和部署# 使用Azure Developer CLI登录 azd auth login # 使用Azure CLI登录设备代码流 az login --use-device-code # 一键式部署所有资源并推送代码 azd upazd up是Azure Developer CLI的核心命令它会交互式地让你选择订阅、资源组、部署区域记得选East US 2然后自动执行以下操作根据infra/目录下的Bicep模板在Azure上创建所有必要的资源App Service Plan, Container Registry, Azure OpenAI, AI Search等。构建Docker镜像。将镜像推送到Azure Container Registry。将应用部署到Azure Container Apps。完成后终端会输出应用的访问URL。方案二VS Code Dev Containers本地容器化开发如果你更喜欢在本地VS Code中工作但不想污染本地环境这是最佳选择。确保本地安装了Docker Desktop并正在运行。点击“Open in Dev Containers”按钮VS Code会提示你重新在容器中打开文件夹。容器启动后环境已配置好。你需要在容器内的终端中安装Python依赖cd src/api python -m venv .venv # Windows (在容器内通常为Linux环境但这里按文档说明) source .venv/bin/activate # Linux/macOS # 如果容器是Windows基础镜像则用 .\.venv\Scripts\activate pip install -r requirements.txt后续的azd auth login和azd up步骤与Codespaces相同。注意Windows用户的CRLF问题文档中特别提到了一个Windows下使用Dev Containers的坑。如果部署时遇到关于postprovision.sh脚本的错误exit code 127很可能是行尾序列EOL的问题。解决方法是在VS Code中打开infra/hooks/postprovision.sh文件查看右下角状态栏如果显示CRLF点击它并选择LF然后保存文件。这是因为Linux shell脚本无法正确解析Windows的回车换行符。方案三纯本地环境完全手动控制适合对本地环境有完全控制需求或需要深度定制化部署的开发者。安装所有先决条件Azure Developer CLI (azd)Python 3.10Docker DesktopGit初始化项目不需要git clone直接用azd init模板功能。# 在一个空文件夹中执行 azd init -t contoso-creative-writer这个命令会拉取项目代码并初始化一个新的git仓库。安装Python依赖python -m venv .venv .\.venv\Scripts\activate # Windows Mac/Linux用 source .venv/bin/activate cd src/api pip install -r requirements.txt无论选择哪种方式成功运行azd up并看到部署完成的URL就标志着基础设施层已就绪。接下来我们就可以深入代码和运行逻辑了。4. 核心代码解析与智能体工作流实现4.1 项目目录结构透视理解一个项目先从目录结构开始。部署完成后你的项目根目录大致如下contoso-creative-writer/ ├── .azure/ # azd环境配置包含订阅、资源组等信息 ├── .github/ # GitHub Actions CI/CD工作流定义 ├── infra/ # **基础设施即代码 (Bicep文件)** │ ├── main.bicep # 主部署模板定义所有Azure资源 │ ├── app.bicep # 定义应用服务Container Apps等 │ ├── ai.bicep # 定义AI相关资源OpenAI, AI Search, AI Agent │ └── hooks/ # 部署前后执行的脚本如创建AI Search索引 ├── src/ │ ├── api/ # **后端FastAPI应用核心** │ │ ├── agents/ # **四个智能体的定义** │ │ │ ├── researcher/ │ │ │ │ ├── researcher.prompty # 研究智能体的提示词定义 │ │ │ │ └── researcher.py # 研究智能体的执行代码 │ │ │ ├── product_agent/ # 产品智能体结构同researcher │ │ │ ├── writer/ # 写作智能体 │ │ │ ├── editor/ # 编辑智能体 │ │ │ └── orchestrator.py # **工作流编排器核心调度逻辑** │ │ ├── evaluate/ # 文章质量评估模块Coherence, Fluency等 │ │ ├── shared/ # 共享工具函数如初始化Azure AI客户端 │ │ └── main.py # FastAPI应用入口定义API路由如/get_article │ └── web/ # 前端React应用 │ ├── public/ │ └── src/ ├── tests/ # 测试文件 └── azure.yaml # azd项目配置文件定义服务名称、部署类型等这个结构非常清晰体现了现代云原生应用的典型分层infra/管资源src/api/管业务逻辑src/web/管交互。4.2 智能体的心脏Prompty文件解析让我们深入看看智能体是如何被“定义”的。以src/api/agents/researcher/researcher.prompty为例name: Researcher description: An agent that researches a topic using the Bing Grounding tool. model: api: chat configuration: type: azure_openai azure_deployment: gpt-4o # 指定使用gpt-4o模型 ... # 其他连接配置通常从环境变量读取 # 这是核心提示词System Message Few-shot示例 prompt: | You are a research assistant. Your task is to research the given topic thoroughly using the Bing Grounding tool. Provide a concise and informative summary of your findings. Example: User: Research the history of the internet. Assistant: I will search for information about the history of the internet. Topic: {{topic}} # 定义智能体可以使用的工具 tools: - name: bing_grounding # 工具名称对应Azure AI Agent Service中的工具 type: bing_grounding configuration: ... # Bing Grounding的配置如搜索范围、结果数量 # 输出格式的样本用于指导模型结构化输出 sample: ...这个.prompty文件是一个声明式的配置。它告诉框架我是谁一个研究助手。我用什么模型Azure OpenAI的gpt-4o。我怎么做使用Bing Grounding工具进行搜索并总结发现。我的输入是什么一个名为topic的变量。我输出什么一个简洁的信息性摘要。在代码researcher.py中加载和运行这个智能体变得非常简单import prompty async def run_research(topic: str): # 加载.prompty文件它会自动处理与Azure的连接和工具绑定 researcher_agent prompty.load(researcher.prompty) # 执行智能体传入变量 result await researcher_agent.run(topictopic) return resultPrompty的核心优势在于它将提示词工程Prompt Engineering从代码中解耦。你可以随时修改.prompty文件中的提示文本、调整示例、甚至更换工具而完全不需要重新部署后端代码。这对于快速迭代和A/B测试智能体行为至关重要。4.3 工作流引擎Orchestrator.py 深度剖析orchestrator.py是这个多智能体系统的“总指挥”。它的逻辑清晰而有力import asyncio from agents.researcher.researcher import run_research from agents.product_agent.product_agent import run_product_search from agents.writer.writer import run_writer from agents.editor.editor import run_editor async def generate_article(context: str, instructions: str): 生成文章的主流程 print(f开始处理任务: {context} - {instructions}) # 步骤1: 调用研究智能体 print(调用研究智能体...) research_result await run_research(topiccontext) print(f研究完成: {research_result[:100]}...) # 打印前100字符 # 步骤2: 调用产品智能体 print(调用产品智能体...) product_results await run_product_search(querycontext, research_contextresearch_result) print(f找到 {len(product_results)} 个相关产品。) # 步骤3: 调用写作智能体整合研究和产品信息 print(调用写作智能体...) article_draft await run_writer( topiccontext, instructionsinstructions, researchresearch_result, productsproduct_results ) # 步骤4: 调用编辑智能体进行润色 print(调用编辑智能体...) final_article await run_editor(draftarticle_draft) print(文章生成完成) return { research: research_result, products: product_results, draft: article_draft, final_article: final_article }这个generate_article函数就是整个工作流的蓝图。它有几个关键设计点异步Async/Await所有智能体调用都是异步的这能有效提高I/O密集型任务网络调用AI服务的吞吐量避免阻塞。清晰的输入输出管道每个智能体的输出都成为下一个智能体的输入的一部分数据流一目了然。可观测性通过print语句在生产环境中应替换为结构化日志我们可以清晰地看到流程进行到哪一步便于调试。4.4 前端与后端的协作API接口与状态管理后端通过FastAPI暴露了一个简单的API端点位于src/api/main.pyfrom fastapi import FastAPI, HTTPException from orchestrator import generate_article app FastAPI() app.get(/get_article) async def get_article(context: str, instructions: str): 接收用户输入触发智能体工作流返回结果 try: # 调用编排器 result await generate_article(context, instructions) return result except Exception as e: # 异常处理返回错误信息 raise HTTPException(status_code500, detailstr(e))前端src/web/则是一个React应用它提供了一个表单让用户输入context和instructions然后调用这个/get_article接口。更棒的是前端界面不仅展示最终文章还设计了一个“Creative Team”视图可以点击每个智能体的头像查看其详细的输入和输出。这个功能对于理解多智能体工作流的中间状态、调试提示词效果具有无可估量的价值。5. 本地运行、调试与深度测试5.1 在本地完整运行工作流部署到云端后你完全可以在本地运行后端和前端连接到云端的Azure服务进行测试这样更利于开发和调试。启动后端API服务器cd src/api # 确保虚拟环境已激活且依赖已安装 fastapi dev main.py这会在http://127.0.0.1:8000启动一个带有热重载功能的开发服务器。关键一步如果你在Codespaces或远程环境中需要去VS Code的“端口PORTS”标签页将8000端口的可见性从“私有Private”改为“公共Public”这样才能从前端访问。直接测试API你可以直接在浏览器中访问一个构造好的URL来测试API是否工作例如http://127.0.0.1:8000/get_article?contextWrite an article about camping in alaskainstructionsfind specifics about what type of gear they would need and explain in detail如果一切正常你会看到一个JSON响应包含了research、products、draft和final_article所有字段。启动前端开发服务器# 新开一个终端窗口 cd src/web npm install # 首次运行需要安装依赖 npm run dev前端通常会在http://localhost:5173启动。同样如果在Codespaces中需要将5173端口也设置为“公共”。现在打开浏览器访问前端地址你就可以通过友好的界面与创意写作助手交互了。使用纯Python编排器测试如果你想绕过Web界面快速在命令行测试工作流逻辑可以直接运行cd src/api python -m orchestrator这通常会执行orchestrator.py中预设的示例任务并在控制台打印出每个步骤的结果。这是进行单元测试或批量测试的理想方式。5.2 利用Prompty Tracing进行可视化调试这是项目中最酷的特性之一。Prompty框架内置了追踪Tracing功能可以记录智能体执行的每一步包括模型调用、工具调用、输入输出等。启用追踪在运行orchestrator之前设置环境变量。# Linux/macOS export LOCAL_TRACINGtrue # Windows (PowerShell) $env:LOCAL_TRACINGtrue运行工作流cd src/api python -m orchestrator查看追踪结果运行完成后在src/api目录下会生成一个.runs文件夹里面有一个.tracy文件。用支持该格式的工具如VS Code的Prompty扩展或特定的追踪查看器打开这个文件。你会看到一个时间线视图清晰地展示了四个智能体被调用的顺序、每个智能体内部模型思考的步骤、对Bing Grounding工具的调用详情、耗时、以及每个环节的输入输出。这对于优化提示词、分析性能瓶颈、理解模型“思考过程”至关重要。5.3 文章质量评估不仅仅是生成还要评价一个成熟的AI应用不能只停留在“能运行”还必须能“评估好坏”。项目内置了一个评估模块src/api/evaluate/它使用另一组AI智能体评估器来从四个维度给生成的文章打分连贯性Coherence文章的逻辑是否通顺段落衔接是否自然。流畅性Fluency语言是否流畅用词和语法是否恰当。相关性Relevance文章内容是否与用户给定的主题和指令高度相关。事实依据性Groundedness文章中的事实陈述是否基于研究智能体提供的资料即是否“接地气”减少幻觉。运行评估脚本cd src/api python -m evaluate.evaluate脚本会读取eval_inputs.jsonl文件中预定义的几个测试用例包含主题、指令、以及模拟的研究和产品数据调用完整的智能体工作流生成文章然后调用评估器对结果进行打分通常是1-5分。这为持续监控和优化整个系统的输出质量提供了一个自动化的、量化的手段。实操心得评估的重要性在实际项目中建立这样一个评估循环是至关重要的。你可以定期运行评估跟踪分数变化。当你修改了某个智能体的提示词.prompty文件后重新运行评估就能客观地看到修改是提升了还是降低了文章质量。这是数据驱动的提示词优化的基础。6. 生产化考量与进阶扩展6.1 成本监控与优化策略这个项目运行起来会消耗Azure OpenAI的Token、Bing Search API的调用次数以及Azure AI Search的计算资源。在长期运行或高并发下成本不容忽视。Azure定价计算器在项目启动前务必使用 Azure定价计算器 根据你预估的请求量对Azure OpenAI按Token计费、Azure AI Search按搜索单位和存储计费、Container Apps等服务的成本进行估算。优化策略缓存Caching对于相同或相似的主题查询其研究结果和产品推荐可能是相同的。可以考虑引入缓存层如Redis将(context, instructions)的哈希值作为键将最终文章或中间结果缓存起来短期内相同的请求直接返回缓存大幅降低对昂贵AI服务的调用。异步与批处理前端请求可以异步处理用户提交任务后立即返回一个任务ID文章生成完成后通过WebSocket或轮询通知用户。这样既能提升用户体验也为后台进行可能的请求合并批处理提供了空间。模型降级在非关键环节进一步使用更小、更便宜的模型。例如编辑智能体是否可以用比gpt-4o-mini更经济的模型对于某些简单主题写作智能体是否也能用gpt-4o-mini这需要根据评估结果做权衡。6.2 安全与合规性增强项目模板已经考虑了一些安全最佳实践但在实际生产环境中还需要加强身份认证与授权当前的API端点/get_article是公开的。生产环境必须添加身份验证如Azure AD、JWT令牌和速率限制防止滥用。密钥管理项目使用了Managed Identity或Key Vault这是正确的做法。确保在Azure上所有服务的连接字符串、API密钥都存储在Azure Key Vault中应用程序通过Managed Identity去访问避免在代码或配置文件中硬编码密钥。内容安全过滤器在调用Azure OpenAI之前或之后应集成 内容安全 功能对用户的输入和AI的输出进行过滤防止生成有害、偏见或不当内容。数据隐私确保你的使用场景符合Azure OpenAI的服务条款特别是当用户输入可能包含个人数据时。考虑在调用Bing Grounding和AI Search时对查询进行必要的匿名化处理。6.3 扩展项目更多的可能性这个模板是一个强大的起点你可以基于它构建更复杂的应用增加新的智能体比如一个“SEO优化”智能体在编辑之后对文章进行关键词密度分析、元描述生成。只需创建新的seo_agent.prompty和seo_agent.py然后在orchestrator.py的流程中插入即可。集成更多工具除了Bing搜索和AI SearchAzure AI Agent Service还支持调用自定义API、数据库查询等。你可以让智能体连接公司内部的CRM系统来获取客户案例或连接天气API来为旅行文章添加实时天气信息。实现更复杂的编排逻辑目前的流程是线性的研究-产品-写作-编辑。你可以引入条件逻辑。例如如果研究智能体返回的信息量很少可以触发一个“深度研究”分支或者根据文章初稿的长度决定是否调用一个“精简摘要”智能体。构建领域专属版本将产品向量库换成你公司的产品手册将提示词调整为技术文档风格这个系统就能变成一个“技术文档助手”。或者换成法律案例库和法条调整提示词变成一个“法律文书起草助手”。其多智能体、工具增强的架构是通用的。7. 常见问题与故障排查实录在部署和运行过程中你几乎一定会遇到一些问题。以下是我踩过的一些坑和解决方案问题1部署时azd up失败提示“模型部署gpt-4o在区域xxx不可用”。原因你选择的Azure区域不支持所需的AI模型。解决在运行azd up选择区域时务必选择East US 2或其他明确支持gpt-4o和gpt-4o-mini的区域。可以在Azure门户中创建Azure OpenAI资源时查看可选区域列表。问题2研究智能体调用失败错误信息与Bing Grounding或TPM限制相关。原因A你的Azure AI Agent Service资源未启用Bing Grounding功能。解决A去Azure门户找到你的AI Agent Service资源在“工具Tools”配置部分添加并配置Bing Grounding。原因B你的Azure OpenAI资源中gpt-4o模型的TPM每分钟令牌数配额太低默认可能为40或80。Bing Grounding工具调用需要消耗一定Token可能触发限流。解决B在Azure门户中进入你的Azure OpenAI资源找到“配额Quota”部分为gpt-4o模型申请提高TPM配额例如提高到200或更高。问题3前端能打开但点击“Start Work”后长时间无反应或报错。排查步骤检查后端API首先直接在浏览器访问http://localhost:8000/get_article?contexttestinstructionstest看是否能返回JSON或错误信息。如果报错查看后端终端日志。检查端口转发在Codespaces/Dev Containers中确认8000后端和5173前端两个端口的可见性都已设置为“Public”。检查环境变量后端服务需要正确的Azure端点、密钥等环境变量才能连接云端资源。这些变量通常在azd up部署时自动设置。在本地运行fastapi dev时确保它从.env文件或系统环境变量中读取到了正确的配置。可以检查src/api/shared中的初始化代码看连接客户端是否成功创建。查看后端日志在后端运行的终端中查看详细的错误堆栈信息这是最直接的线索。问题4产品智能体返回空结果找不到相关产品。原因Azure AI Search的索引contoso-products可能没有成功创建或者数据没有正确导入。解决检查部署日志看infra/hooks/postprovision.sh这个钩子脚本是否执行成功。这个脚本负责创建搜索索引并导入数据。你也可以手动去Azure门户进入你的AI Search服务查看是否存在名为contoso-products的索引并检查其中的文档数量。问题5生成的文章质量不佳比如偏离主题或产品推荐不相关。这是提示词优化问题不要修改代码去修改对应的.prompty文件。研究不深入去修改researcher.prompty在提示词中要求“搜索最新、最权威的5条信息并进行综合摘要”。产品推荐不准去修改product_agent.prompty调整其理解查询和产品描述的语义相似度逻辑的提示词部分。文章结构混乱去修改writer.prompty给它一个更清晰的文章大纲模板。记住每次修改.prompty文件后无需重启服务如果使用fastapi dev因为Prompty是动态加载的。这是使用Prompty框架最大的便利之一。这个项目就像一台精密的机器每个智能体是一个功能模块Prompty是控制这些模块的说明书而Orchestrator是传动轴。通过深入理解每个部分你不仅能成功运行它更能掌握定制和构建属于你自己的、更强大的AI智能体应用的能力。从部署到调试从使用到扩展每一步都充满了工程实践的智慧值得反复琢磨。