智能体开发实战（Dify）（微课版）课件 项目四 智慧校园智能体能力拓展-工具调用实现

项目四

智慧校园智能体能力拓展--工具调用实现项目背景与目标CONTENTS目录教学目标项目背景项目目标项目分析教学目标01技能目标（1）具备第三方API凭证管理与内置工具集成能力

能够独立完成商业API（如和风天气、高德地图）的开发者账号注册与Key获取；熟练操作Dify工具市场，完成APIHost与鉴权凭证的配置，实现外部成熟服务在智能体中的快速接入。（2）掌握RESTful接口模拟与自定义工具开发技能

能够利用Apifox等接口调试工具构建云端Mock服务，模拟包含鉴权机制（如Header验证）的私有业务接口（如教务查分）；掌握自定义工具的完整开发流程，能够将模拟或真实的HTTP接口封装为智能体可调用的插件。（3）精通OpenAPI规范（Swagger）的Schema编写能够编写符合OpenAPI3.0+标准的接口描述文件（YAML格式），准确定义API的服务器地址（Servers）、路径（Paths）、请求参数（Parameters）及安全方案（SecuritySchemes），确保大模型能精准理解工具的功能边界与调用方式。（4）具备基于思维链（CoT）的多工具协同编排能力

能够设计复杂的系统提示词（SystemPrompt），引导智能体执行多步推理与条件判断（如“成绩不合格则触发辅导规划”）；实现“成绩查询-天气判断-路径规划”等跨场景任务链的自主决策与数据流转，解决复杂的实际业务问题。教学目标知识目标（1）理解智能体“手眼”的工作原理。深刻理解Agent的核心组件中“工具（Tools）”的价值，掌握FunctionCalling（函数调用）从意图识别、参数提取到结果回传的完整运行机制。（2）掌握HTTP协议与接口规范。理解HTTP/HTTPS协议的基本原理，熟悉API鉴权机制（如APIKey）及常见错误码含义，掌握OpenAPI与Swagger的标准规范。（3）熟悉工具调用的架构设计。认识工具定义中Schema的作用，理解为何规范的输入输出结构对于提升大模型推理准确性至关重要。（4）理解API网关与系统对接逻辑。掌握智能体与传统业务系统（如教务系统、物联网设备）交互的底层逻辑，理解同步/异步调用在实际业务中的应用差异。教学目标素养目标（1）培养工程规范与接口契约精神，在编写OpenAPISchema描述文件的过程中，养成严谨的代码编写习惯与文档意识；深刻理解“接口契约”在软件工程中的核心价值，认识到标准化的接口定义是实现大模型与外部系统无缝互操作（Interoperability）的基石。（2）树立数据安全与隐私合规意识，通过模拟“教务查分”这一敏感业务场景，并在配置APIKey鉴权的过程中，强化对用户隐私数据（PII）的保护观念；理解在开发测试阶段使用Mock数据的必要性，以及在生产环境中遵循“最小权限原则”和安全传输协议的职业操守。构建系统思维与计算思维能力，在设计“查分-判断-决策”的多工具协同任务时，锻炼透过自然语言表象挖掘业务逻辑本质的能力；培养将模糊的复杂需求拆解为可执行的原子步骤（Step-by-step）的计算思维，以及运用条件分支解决动态问题的全局规划视角。教学目标项目背景02随着智慧校园建设的不断深入，师生对于校园服务的需求日益呈现出个性化、实时化与复杂化的特征。早期的智能客服或校园助手大多基于预设规则或简单的检索生成增强（RAG）技术，仅能处理政策咨询、信息查询等静态任务。然而，在实际的教务管理与校园生活中，用户往往需要完成更具操作性的任务，例如实时查询教务系统的个人成绩单、预约图书馆研讨室、获取校园一卡通流水或联动控制教室的物联网设备。此类任务具有两个核心挑战：一是数据来源于封闭的第三方业务系统，大模型本身并不具备访问权限；二是任务执行涉及具体的API接口调用、参数传递以及对返回结果的逻辑处理，而非单纯的文本生成。单纯依赖大语言模型自身的知识库无法满足从“信息咨询”向“业务办理”跨越的需求。为了解决这一痛点，赋予智能体（Agent）“使用工具”的能力成为关键技术突破口。通过引入工具调用（ToolCalling）机制，智能体可以像人类一样理解用户意图，自主选择合适的API接口（工具），按照规范构建请求参数，并根据外部系统的反馈完成闭环操作。本项目立足于智慧校园的实际业务场景，旨在通过实现教务系统成绩查询等具体功能，深入探索智能体如何通过标准的OpenAPI规范与外部世界进行交互，从而打破大模型的能力边界，构建具备执行力的智慧校园服务体系。项目背景项目目标03本项目旨在打破大模型的信息孤岛，通过引入工具调用（FunctionCalling）机制，赋予智能体连接外部业务系统的能力。学习者将深入掌握HTTP协议与OpenAPI规范，在Dify平台中完成内置工具的配置及“教务成绩查询”自定义工具的开发。通过本项目实践，实现智能体从“对话交互”向“任务执行”的进阶，构建出具备自主规划与业务处理能力的智慧校园助手。项目目标项目分析04本项目重点解决大语言模型（LLM）在面对封闭业务系统数据时的“能力边界”问题，即如何让仅具备文本生成能力的模型，安全、准确地获取并处理校园教务系统中的实时数据。项目的核心逻辑在于构建智能体与外部世界交互的标准化桥梁，其实施过程包含以下三个层面的深度分析：首先是技术原理层面。智能体之所以能像人类一样使用工具，依赖于FunctionCalling（函数调用）机制。这要求开发者理解模型是如何通过语义分析识别用户意图，进而提取关键参数并匹配相应工具的。项目将深入剖析HTTP协议的请求/响应模型以及API鉴权机制，这是智能体与外部服务器通信的基础物理通道。其次是接口规范层面。为了让智能体“读懂”外部工具的使用说明书，必须引入OpenAPI规范（原Swagger规范）。项目中的难点在于如何将抽象的业务逻辑（如“查询某学期成绩”）转化为机器可读的结构化Schema描述（YAML/JSON）。这不仅涉及接口路径与方法的定义，更关乎参数校验规则与输出数据结构的标准化设计，直接决定了工具调用的成功率与稳定性。最后是工程应用层面。依托Dify开发平台，项目遵循“由浅入深”的实施路径。先通过配置内置工具（如和风天气）快速验证工具调用流程，建立感性认知；进而通过编写自定义HTTP工具（教务成绩查询），攻克参数封装与接口对接的实际难题；最终通过多工具协同配置，模拟真实场景下智能体对复杂任务的自主拆解与执行。这一过程旨在培养学习者解决实际系统集成问题的工程思维，完成从单纯的“提示词编写者”向“智能体架构师”的角色转变。项目分析知识准备HTTP调用工程要点在智能体开发中，工具调用（ToolCalling）的本质是智能体作为客户端，向外部业务系统（Server）发起网络请求并处理响应的过程。掌握HTTP通信协议的工程细节，是构建稳定、可靠智能体应用的技术基石。知识准备超文本传输协议（HTTP,HyperTextTransferProtocol）是智能体与外部世界进行数据交换的通用语言。它基于严格的“请求-响应”模型工作，即智能体发起指令，服务器执行并反馈结果。一个标准的HTTP请求（Request）通常由以下核心要素构成，智能体在执行工具调用时，实质上就是在构建这些参数：（1）请求行（RequestLine）：定义了请求方法与资源地址。GET方法通常用于获取资源（如查询成绩），参数直接拼接在URL中；POST方法用于传输实体数据（如提交选课），数据封装在请求体中，具有更高的安全性与容量。（2）请求头（Headers）：承载元数据。其中Content-Type字段告知服务器发送的数据格式（通常为application/json），Authorization字段则用于携带身份验证凭证。（3）请求体（Body）：这是智能体将用户自然语言需求转化为结构化JSON数据后存放的位置，也是POST请求中业务数据传输的主要载体。服务器在处理请求后会返回HTTP响应（Response）。响应数据包的核心在于状态码（StatusCode）与响应体（ResponseBody）。状态码用于直观告知处理结果，而响应体则包含了具体的业务数据（如JSON格式的成绩列表）。智能体通过解析响应体中的字段，提取关键信息并生成最终回复呈现给用户。HTTP请求与响应模型HTTP请求与响应模型左图展示了HTTP请求包与响应包的内部结构拆解。请求包明确了方法、头域与数据体的层级关系，响应包则突出了状态码与返回数据的对应关系。在智能体开发中，JSON格式的数据体（Body）是信息交互的核心载体。智慧校园场景涉及大量敏感数据，如学生身份证号、家庭住址及考试成绩等，明文传输的HTTP协议存在极大的数据泄露风险。因此，现代智能体应用对接业务系统时，必须强制采用HTTPS协议。HTTPS在HTTP层之下加入了SSL/TLS加密层，主要提供以下安全保障：（1）传输加密：利用非对称加密技术在连接握手阶段安全交换密钥，随后利用对称加密技术在数据传输阶段对内容进行加密。这种“双重保险”确保了通信通道的封闭性。（2）身份认证：通过数字证书（Certificate）验证服务器的真实身份，防止智能体将敏感请求发送给伪造的“钓鱼服务器”。（3）完整性校验：协议包含的校验算法能确保数据在传输过程中未被恶意篡改。HTTPS协议的安全机制HTTPS协议的安全机制左图展示了HTTPS协议下的安全传输通道。通过在传输层加入SSL/TLS加密盾牌，原始的明文数据（JSON）被转化为无法识别的密文流进行传输，只有通信双方的终端才能进行解密复原，从而确保了校园数据的隐私安全。在配置智能体工具时，开发者应严格检查接口地址是否以“https://”开头。鉴权（Authentication）是外部系统识别智能体身份并控制其访问权限的关键关卡。大多数承载核心业务数据的API均不开放匿名访问，智能体必须在请求中携带合法的身份凭证。常见的鉴权方式包括：（1）APIKey（密钥认证）：系统管理员分配一个唯一的字符串密钥。推荐采用Header传参的方式，即把Key放入HTTP请求头中（如“Authorization:Bearer<Key>”）。这种方式比将Key直接拼接到URL参数中更为安全，能有效避免密钥在服务器日志中泄露。（2）Token（动态令牌）：适用于安全性要求更高的场景（如OAuth2.0）。智能体需先通过账号密码换取一个具有时效限制的访问令牌（AccessToken）。令牌过期后，智能体必须调用刷新接口重新获取。API鉴权机制API鉴权机制左图展示了基于APIKey的鉴权交互流程。API网关作为守门人，会拦截智能体发出的每一个请求，通过比对Header中的密钥与数据库记录来决定是否放行。若密钥无效或缺失，请求将被直接拒绝并返回401错误。由于网络环境的波动性，工具调用并非总能成功。智能体需要通过解析HTTP状态码来判断调用的结果，并据此决定后续动作。常见的状态码类别如下：（1）2xx系列（成功）：如200OK，表示工具调用成功，服务器已正常处理并返回数据，智能体可继续执行后续逻辑。（2）4xx系列（客户端错误）：如400BadRequest（参数错）、401Unauthorized（鉴权失败）。此类错误通常由配置不当或输入非法引起，不可重试，应直接向用户反馈错误信息。（3）5xx系列（服务器错误）：如500InternalError、502BadGateway。此类错误通常代表服务端出现了临时性故障，可以尝试重试。智能体在工具调用时针对不同状态码的有不同的响应机制：对于不可恢复的客户端错误（4xx），直接报错；对于可恢复的服务端错误（5xx），则引入指数退避策略进行有限次重试。即每次重试的等待时间按指数级增加（例如等待1秒、2秒、4秒...），若超过预设的最大重试次数仍未成功，智能体应终止重试并判定任务失败。错误码处理与重试策略在智能体开发中，要实现“工具调用”功能，仅有HTTP协议是不够的。智能体（Agent）需要一份标准化的“说明书”来理解外部工具有什么功能、需要什么参数以及返回什么数据。OpenAPI规范正是这样一种全球通用的接口描述标准，它构成了智能体连接外部世界的语义基础。OpenAPI规范OpenAPI文档通常采用YAML或JSON格式编写，具有严格的层级结构。一个标准的OpenAPI文档主要由以下根对象（RootObjects）组成：（1）openapi：声明规范的版本号（如3.0.0或3.1.0），确保解析器能正确识别文件格式。（2）info（元数据）：提供API、的基本信息，包括标题（title）、描述（description）和版本（version）。智能体通常依赖description字段中的自然语言描述来判断何时调用该工具。（3）servers（服务器）：指定API的基础URL（BaseURL），即请求发送的目标服务器地址。（4）paths（路径）：文档的核心部分，定义了API的各个端点（Endpoint）及其支持的操作（GET,POST等）。每个路径下详细描述了输入参数（parameters）和请求体（requestBody）。（5）components（组件）：定义可复用的数据模型（Schema）。例如，将“学生成绩单”的数据结构定义为一个组件，可以在多个接口中重复引用，简化文档编写。OpenAPI规范基本信息OpenAPI规范基本信息OpenAPI文档通过树状层级清晰地定义了接口的各个要素。这种结构化数据使得智能体可以精准地提取参数并构建HTTP请求。在API开发领域，Swagger是一个广泛使用的术语，它代表了一套围绕OpenAPI规范构建的开源工具集。这套工具集旨在帮助开发者设计、构建、记录和使用RESTfulWeb服务。主要的Swagger工具包括：（1）SwaggerEditor：一个基于浏览器的编辑器，支持实时编写和预览OpenAPI规范文件。（2）SwaggerUI：将OpenAPI规范文件渲染为交互式的API文档页面，允许用户直接在网页上测试接口调用。在智能体开发调试阶段，SwaggerUI是验证接口可用性的重要工具。（3）SwaggerCodegen：根据OpenAPI规范自动生成不同编程语言的客户端SDK或服务器存根（Stub）代码。什么是Swagger初学者常混淆Swagger和OpenAPI，理清二者的关系对于准确理解技术生态至关重要。（1）规范与实现的区别：OpenAPI是规范（Specification）。它规定了API应该如何描述，类似于HTML标准。Swagger是工具（Tools）。它是实现和使用该规范的一系列软件，类似于Chrome浏览器或VSCode编辑器。（2）历史演变：OpenAPI规范的前身是Swagger规范。2015年，Swagger规范的维护组织SmartBear将其捐赠l给Linux基金会，并成立了OpenAPI倡议（OpenAPIInitiative）。为了区分“规范”与“工具品牌”，规范被重命名为OpenAPISpecification，而Swagger则继续作为工具集的品牌名称存在。Swagger2.0版本对应的是OpenAPI2.0规范，从3.0版本开始，正式统称为OpenAPI3.0。Swagger和OpenAPI的关系Swagger和OpenAPI的关系OpenAPI是处于核心地位的行业标准，而Swagger则是基于该标准构建的一系列应用工具。在现代智能体开发中，我们通常说“遵循OpenAPI规范编写文档”，并使用“SwaggerUI进行接口调试”。大语言模型（LLM）本身是一个封闭的文本生成系统，其知识仅限于训练截止日期之前的数据。要构建能够处理实时业务（如查询当前学期成绩）的“智慧校园智能体”，必须引入Agent（智能体）架构与工具调用（ToolCalling）技术。这使得模型从单纯的“大脑”进化为具备“手眼”的完整智能系统。Agent与工具调用智能体（AIAgent）被定义为能够感知环境、进行推理规划并采取行动以实现特定目标的智能实体。在基于大模型的应用开发中，Agent的核心不再仅仅是文本生成，而是自主决策与执行。传统的Chatbot（聊天机器人）侧重于基于预训练知识进行问答，本质是“信息检索与生成”。而Agent侧重于解决实际问题，它具备将复杂的用户需求拆解为一系列步骤，并主动调用外部工具去完成任务的能力。例如，当用户询问“我这学期通过了吗？”Chatbot可能会回答“我不知道你的成绩”，而Agent会判断需要调用“教务系统查询接口”，并根据返回结果回答具体情况。Agent的核心FunctionCalling（函数调用）是连接大模型与外部工具的“桥梁技术”。它允许开发者在发送给模型的请求中描述一组可用的函数（工具），模型在处理用户提问时，如果判断需要使用工具，会输出一个包含函数名称和参数的结构化数据（通常是JSON），而不是普通的文本回复。FunctionCalling的完整工作流程包含以下四个关键步骤：（1）意图识别与工具选择：用户输入自然语言指令（如“帮我查一下张三的成绩”）。大模型分析语义，判断该请求无法直接回答，需要使用外部数据。模型检索可用的工具列表（SystemPrompt中定义的ToolSchema），并选中最匹配的工具（如query_grade）。（2）参数提取与结构化生成：模型根据工具定义的Schema，从用户的自然语言中提取关键信息作为参数（如name:"张三"）。此时，模型并不直接执行代码，而是生成一个包含函数名和参数的JSON对象返回给应用程序。示例输出：{"tool":"query_grade","parameters":{"student_name":"张三"}}（3）本地执行与结果回传：应用程序（如Dify平台或后端服务）拦截到模型返回的FunctionCall指令，解析其中的参数，在本地环境中实际发起HTTP请求调用外部API。外部系统（教务系统）执行业务逻辑后，返回执行结果（如JSON格式的成绩单）。（4）结果合成与最终响应：应用程序将API返回的执行结果再次作为输入（Message）发送给大模型。大模型结合用户的原始问题和工具返回的客观数据，生成最终的自然语言回复（如“张三的成绩如下：数学85分，英语90分...”）反馈给用户。FunctionCalling工作机制FunctionCalling工作机制FunctionCalling本质上是一个“模型决策->系统执行->模型总结”的闭环过程。在此过程中，大模型充当了“路由与翻译”的角色，将自然语言翻译为机器指令，再将机器数据翻译回自然语言。工具定义（ToolDefinition）的质量直接决定了智能体能否准确识别意图、正确提取参数。一套严谨、规范的定义标准是实现高质量工具调用的前提。工具定义规范工具Schema是对工具功能、参数及行为的元数据描述，通常遵循OpenAPI标准。它是LLM理解工具的唯一依据。一个完整的Schema设计包含三个核心维度：（1）标识与描述：工具名称必须语义明确，功能描述是决定模型“何时调用”的关键。（2）参数对象：定义输入变量的名称、类型及必要性。（3）鉴权配置：明确鉴权类型及存放位置。工具Schema的设计工具Schema的设计工具Schema的各个字段都承担着特定的指引作用。精准的名称和详细的描述能显著提升模型检索工具的准确率，而规范的参数定义则是成功调用的保障。为了确保模型能生成符合要求的请求并理解返回数据，必须对输入和输出进行严格定义。（1）输入参数（Inputs）的设计原则语义化命名：使用清晰的英文单词。类型约束：明确指定String、Integer等类型。枚举值（Enum）：对于有限选项参数使用枚举，降低模型幻觉风险。（2）输出结构（Outputs）的定义虽然HTTP传输文本，但通常约定返回JSON格式。工具定义中应声明返回数据的关键字段及其含义，以便模型解析。输入参数与输出结构的定义在构建多工具协同系统时，设计统一输出结构（UnifiedOutputStructure）具有重要的工程意义：（1）降低模型理解成本：模型可形成稳定的上下文学习模式。（2）便于错误统一处理：系统可通过通用字段拦截错误。（3）支持链式调用：结构化输出使得数据流转可编程。统一输出结构的设计意义统一输出结构的设计意义统一的输出结构避免了格式混乱带来的解析难题。当所有工具都遵循一致的数据包裹规范时，智能体在处理复杂任务链时能更高效地提取和传递信息，从而提升整体系统的稳定性。项目实施CONTENTS目录任务4.1在Dify里添加内置工具任务4.2自定义HTTP工具—教务系统成绩单查询任务4.1在Dify里添加内置工具01【任务描述】本任务旨在验证智能体开发平台（Dify）对外部服务的集成能力。任务要求在Dify本地化开发环境中，为一个基础的对话型智能体接入“和风天气”这一内置工具。实施过程涵盖三个主要环节：首先，在和风天气开放平台完成开发者账号注册，并创建项目以获取APIKey（WebAPI认证密钥）；其次，在Dify平台的“工具”模块中定位该插件，通过输入密钥完成平台级的鉴权配置与授权；最后，在具体的智能体应用编排界面中挂载该工具，并通过自然语言指令（如“查询当前北京的天气”）进行交互测试，验证智能体是否具备自主调用工具获取实时气象数据并解析反馈的能力。任务4.1在Dify里添加内置工具【任务实现】1.获取和风天气API凭证在使用任何第三方商业API之前，必须先获取合法的身份鉴权凭证。和风天气作为国内领先的气象服务提供商，提供了免费的开发者订阅额度。（1）注册与登录：访问和风天气开发者控制台（“”），完成账号注册与实名认证。（2）创建项目：在控制台首页点击“项目管理”或“创建项目”。在项目创建表单中，填写项目名称（如“智慧校园智能体”），“订阅方式”选择“免费订阅”（Free），“Key类型”选择“APIKey”。（3）获取Key：项目创建成功后，进入项目详情页。在“KEY管理”区域，可以查看并复制生成的“APIKey”（认证密钥）。此字符串是后续在Dify中配置工具的唯一凭证，需妥善保管，避免泄露。任务4.1在Dify里添加内置工具2.在Dify中配置内置工具Dify平台内置了工具市场，集成了大量常用服务，开发者需在此处输入凭证以激活工具。（1）访问工具市场：登录Dify平台，点击顶部导航栏的“工具”（Tools）标签页。（2）安装工具：在工具列表的搜索框中输入“和风天气”或“QWeather”。找到对应的工具卡片后，点击“安装”按钮，将该工具插件部署到本地环境中。任务4.1在Dify里添加内置工具（3）授权配置：点击工具卡片上的“APIKey授权配置”按钮打开配置窗口。在此处填入步骤1获取的APIKey，同时打开和风天气控制台“设置”页面中提供的API请求地址，将正确的APIHost（通常为）填入对应输入框。任务4.1在Dify里添加内置工具（4）保存状态：点击“保存”按钮。若鉴权通过，界面将不会弹出任何错误提示，且在配置窗口右侧会新增一条“已保存的凭据”记录，表明Dify平台已具备调用该服务的能力。任务4.1在Dify里添加内置工具3.在智能体应用中启用工具完成平台级的工具配置后，还需将其绑定到具体的智能体应用中，模型才能感知并使用该工具。（1）进入应用编排：如图413所示，新建一个Agent类型应用，进入“工作室”（Studio）编排页面。任务4.1在Dify里添加内置工具（2）添加工具：在“上下文”或“工具”配置区域，点击“添加工具”按钮。（3）选择工具：在弹出的工具选择面板中，找到已授权的“和风天气”，点击添加。此时，可以看到该工具包含的具体功能列表（如“实时天气”、“未来3天预报”等）。开发者可根据需求勾选全部或部分功能。（4）发布更新：添加完成后，工具图标将显示在应用配置栏中。点击右上角的“发布按钮，使配置生效。任务4.1在Dify里添加内置工具4.调试与验证最后，通过实际对话测试智能体是否能够正确触发工具调用（FunctionCalling）。（1）发起对话：在右侧的“预览与调试”窗口中，输入具有明确地理位置和意图的指令，例如：“查询一下深圳的天气情况。”（2）观察过程：观察对话窗口的出流。系统应首先显示“正在使用工具...”或类似的思维链（ChainofThought）提示，点击展开，可看到具体的JSON请求参数及接口返回的原始数据。任务4.1在Dify里添加内置工具（3）验证结果：确认智能体最终输出的自然语言回复是否包含了准确的气温、天气状况（如“晴”、“多云”）等信息。若能准确回答，则说明内置工具集成成功。任务4.1在Dify里添加内置工具【任务小结】本任务通过Dify平台与“和风天气”服务的集成实践，完整验证了智能体利用内置工具扩展能力的标准化流程。学习者在此过程中掌握了从第三方平台获取APIKey鉴权凭证，到Dify工具市场进行配置授权，再到智能体编排界面挂载调试的全链路操作，直观观测了模型识别意图、触发FunctionCalling机制并解析实时数据的闭环过程，为后续构建更复杂的自定义工具应用奠定了坚实的工程基础。任务4.1在Dify里添加内置工具任务4.2自定义HTTP工具—教务系统成绩单查询02在实际的智慧校园场景中，大量的核心业务数据（如教务系统、一卡通系统）运行在私有网络或内部服务器中，并未在Dify工具市场中预置。为了使智能体具备访问这些私有数据的能力，必须掌握“自定义工具”的创建方法。本任务以“教务系统成绩单查询”为例，演示从零构建一个符合OpenAPI规范且具备安全鉴权机制的HTTP工具的全过程。任务4.2自定义HTTP工具—教务系统成绩单查询【任务分析】本任务是智能体开发进阶的关键环节，主要解决“通用模型”与“私有数据”的安全连接问题。从技术原理来看，自定义工具的构建包含两个核心维度：一是业务语义的映射，即通过OpenAPISchema让模型理解接口功能；二是安全通道的建立，即通过配置鉴权机制确保只有合法的智能体请求被受理。Dify平台支持多种标准鉴权方式（如APIKey、OAuth），本任务通过模拟最通用的APIKey鉴权，阐明凭证在智能体与外部服务间传递的机理。从工具链来看，利用Apifox的“Mock服务”不仅能模拟正常的数据返回，还能模拟“鉴权失败（401Unauthorized）”等异常场景。这使得在隔离的环境中完整测试智能体的异常处理能力成为可能，实现了前后端开发的解耦与安全隔离。通过本任务的实施，能够建立从“接口定义、鉴权配置”到“工具封装”的完整技术闭环，从而具备对接企业级受保护API的能力。任务4.2自定义HTTP工具—教务系统成绩单查询【任务实现】1.使用Apifox模拟带鉴权的教务API为了模拟真实的生产环境，需在Apifox中配置一个既响应业务请求又校验身份凭证的接口。（1）创建项目与接口：访问Apifox软件Web端(/)新建名为“智能体实战教学”的项目。在项目中新建一个GET方法的接口，路径设为/grades。（2）定义Header参数：在“请求参数”的“Header”标签页中，添加必要字段Authorization，示例值设为Bearer123456，参数说明为“访问令牌”。此步骤用于模拟服务端对请求头中身份凭证的校验要求。（3）定义Query参数：在“Query参数”标签页添加业务字段student_name（类型String，说明：学生姓名）和semester（类型String，说明：学期标识，如2025-fall）。任务4.2自定义HTTP工具—教务系统成绩单查询（4）定义Mock返回值：在“返回响应”区域，设置HTTP状态码为200，数据格式选择JSON。编辑响应的根节点结构，构建示例数据模型，以便系统生成Mock数据：（5）开启云端Mock：保存接口配置，开启界面的“云端Mock”服务开关。复制系统生成的BaseURL（通常以“”结尾），该地址将作为后续在Dify中配置的服务器地址。任务4.2自定义HTTP工具—教务系统成绩单查询2.编写含鉴权配置的OpenAPISchema在编写工具描述文件时，除了定义路径和参数，必须显式声明安全方案。（1）定义安全组件：在YAML文件的components节点下增加securitySchemes定义，指定鉴权类型为apiKey，位置在header，参数名为Authorization。（2）应用安全限制：在全局或特定paths下添加security字段以应用该方案。（3）编写Schema文件：参考代码编写完整的描述文件：任务4.2自定义HTTP工具—教务系统成绩单查询openapi:3.0.0info:title:教务系统API(Mock)version:1.0.0servers:-url:h/m1/xxxxx#此处需替换为步骤1实际获取的Mock地址components:securitySchemes:ApiKeyAuth:#自定义安全方案名称

type:apiKeyin:header#指定凭证位置：header,query或cookiename:Authorization#指定传递凭证的字段名security:#全局应用该安全方案

-ApiKeyAuth:[]paths:/grades:get:description:根据姓名和学期查询成绩单

operationId:get_student_gradesparameters:-name:student_namein:queryrequired:trueschema:type:string-name:semesterin:queryrequired:trueschema:type:stringresponses:"200":description:成功返回数据

content:application/json:schema:type:objectproperties:data:type:object3.在Dify中配置工具与凭证Dify平台会自动解析Schema中的安全定义，并在界面上生成对应的鉴权填写框。（1）创建工具条目：登录Dify平台，进入“工具”模块，点击“创建自定义工具”。（2）导入Schema：将步骤2编写的YAML内容粘贴至Schema输入区。系统会自动识别出“APIKey”鉴权类型，并显示参数名为Authorization。任务4.2自定义HTTP工具—教务系统成绩单查询（3）配置鉴权值：在“鉴权方法”设置区域，将鉴权类型选择为“请求头”，鉴权头部前缀选择为“Bearer”。