在 .NET 中构建 Agentic Workflow：基于 Microsoft Agent Framework 的工具调用与多步推理实战指南

在 .NET 中构建 Agentic Workflow基于 Microsoft Agent Framework 的工具调用与多步推理实战指南【免费下载链接】skillsRepository for skills to assist AI coding agents with .NET and C#项目地址: https://gitcode.com/GitHub_Trending/skills17/skills导读本指南以 skills 仓库中technology-selection技能的 Agentic 分支为骨架完整讲解如何在 .NET 应用中用Microsoft Agent FrameworkMicrosoft.Agents.AI编排多步推理、工具调用function calling与多 Agent 工作流。你将掌握如何判断该用 Agent 还是普通 LLM 调用、如何搭建最小可运行的 Agent、7 条核心护栏Guardrails的具体落地方式以及如何用MaximumIterations、token 预算与可观测性防止 Agent 失控——所有结论均有仓库源码、评估配置与测试夹具作为依据。什么时候需要 Agent Frameworktechnology-selection技能SKILL.md用一张决策树把 AI 任务分类。Agentic 分支的适用条件是任务需要以下任一能力工具 / 函数调用tools / function calling多步推理multi-step reasoningAgent 循环agent loops即多次思考→调用工具→观察结果→再思考的往复多个 Agent 协作multi-agent对应地technology-selection的决策树给出了精确边界任务类型技术选型单次提示词→回复文本生成、摘要、推理无工具LLM viaMicrosoft.Extensions.AIIChatClientAgentic多步工具调用、Agent 循环、多 AgentMicrosoft Agent FrameworkMicrosoft.Agents.AI构建在Microsoft.Extensions.AI之上关键判断如果任务只是输入一段文字、输出一段文字用IChatClient直接完成即可不需要任何编排层一旦任务需要搜索网页→记录笔记→总结结论这类需要调度多个工具、反复迭代的过程就应该交给 Agent Framework绝不手写基于IChatClient的工具循环。配套的评估文件 eval.yaml 中有一个名为Agentic workflow with guardrails的刺激场景其 prompt 是构建一个 .NET 10 控制台应用用 AI Agent 搜索网页研究主题并总结发现Agent 应有网页搜索工具和笔记工具这正是本指南对应的典型任务画像。包依赖Packages原文给出的最小依赖集合如下PackageReference IncludeMicrosoft.Extensions.AI Version9.* / PackageReference IncludeMicrosoft.Agents.AI Version1.*-* / !-- prerelease: dotnet add --prerelease -- PackageReference IncludeAzure.AI.OpenAI Version2.* / !-- or another MEAI provider -- PackageReference IncludeAzure.Identity Version1.* /各包职责说明Microsoft.Extensions.AIMEAI抽象层提供IChatClient、ChatOptions、AIFunctionFactory等核心类型。Agent Framework 的一切都构建在这一层之上因此它是必须的基石。Microsoft.Agents.AIAgent 编排层本体提供AIAgent、ChatClientAgent、ChatClientAgentOptions、ChatClientAgentRunOptions等类型。注意1.*-*是预发布版本通配符dotnet add package时需要加--prerelease参数才能解析。Azure.AI.OpenAI具体的模型提供方适配器也可以换成OpenAI、Azure.AI.Inference或OllamaSharp等其他 MEAI provider——这正是provider 藏在IChatClient后面的设计意图。Azure.Identity提供DefaultAzureCredential等无密钥认证方式配合绝不硬编码密钥的安全护栏使用。仓库中的测试夹具 ResearchAgent.csprojtargetnet10.0引用了Microsoft.Agents.AI、Microsoft.Extensions.AI.OpenAI与OpenAI验证了这一组合的真实可解析性——从源码结构可以推断Agent Framework 的包依赖要求 .NET 8 且以 MEAI 为底层。七条护栏Agent 开发的安全边界原文定义了 7 条 Guardrails是 Agentic 分支agentic.md的灵魂。逐一展开用框架而非裸循环用Microsoft.Agents.AI编排不要手工写LLM 调用→解析→再调用的循环。框架帮你管理工具分发、对话历史与迭代状态裸循环既脆弱又无法获得框架级的护栏能力。以Microsoft.Extensions.AI为地基所有能力最终都落在IChatClient之上这意味着你可以无缝复用 MEAI 生态中的RetryingChatClient重试、中间件管道等设施。限定迭代次数通过MaximumIterations给 Agent 循环设置上限防止跑飞runaway execution。这是评估文件 eval.yaml 中明确要求输出的关键字之一。显式定义工具每个工具/函数都要有清晰的 schema 和描述用AIFunctionFactory.Create创建。清晰的描述直接决定模型能否正确选择工具——这是 function calling 准确性的关键。成本天花板强制执行 token 预算超过即停止。LLM 调用按 token 计费无上限的 Agent 循环可能造成不可控成本。可观测性记录每一步日志选择了哪个工具、输入、输出元数据但绝不记录原始敏感内容。优先单 Agent 工具除非任务确实需要专业化分工否则用一个 Agent 挂多个工具而非多 Agent 编排——多 Agent 带来额外的协调复杂度与成本。这七条护栏与technology-selection技能总纲SKILL.md中 Agentic 分支的 essentials 完全一致Microsoft.Agents.AI编排于IChatClient之上、设置MaximumIterations与 token/成本上限、每个工具用AIFunctionFactory.Create定义清晰 schema、记录每步日志不记录原始敏感内容。最小可运行形态Minimal Shape原文给出的最小形态是一个研究并总结AgentIChatClient chatClient new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential()) .GetChatClient(gpt-4o-2024-08-06).AsIChatClient(); AIAgent agent new ChatClientAgent(chatClient, new ChatClientAgentOptions { Instructions Research the topic, then summarize findings., ChatOptions new ChatOptions { Tools [AIFunctionFactory.Create(WebSearch), AIFunctionFactory.Create(TakeNote)], }, }); var runOptions new ChatClientAgentRunOptions { MaximumIterations 10 }; var result await agent.RunAsync(Research the .NET 10 release highlights., options: runOptions);逐段拆解这段代码的含义创建IChatClient通过AzureOpenAIClientDefaultAzureCredential无硬编码密钥连接到 Azure OpenAIGetChatClient(gpt-4o-2024-08-06)固定了带日期的模型版本——这与 MEAI 分支llm.md的pinned model护栏一致用gpt-4o-2024-08-06而非无版本的gpt-4o别名避免模型行为漂移。.AsIChatClient()把 provider SDK 适配为 MEAI 抽象。ChatClientAgent把IChatClient包装成 Agent。Instructions相当于系统提示词定义 Agent 的行为目标ChatOptions.Tools声明 Agent 可用工具集合工具由AIFunctionFactory.Create从 C# 方法如WebSearch、TakeNote自动生成函数 schema。ChatClientAgentRunOptions.MaximumIterations 10限制 Agent 最多迭代 10 轮每轮可能包含一次工具调用是防失控的核心护栏。RunAsync传入用户任务返回AgentRunResult。让示例可编译、可运行原示例假设WebSearch与TakeNote两个方法已存在。为了让最小形态真正可复制运行需要补全这两处工具的声明符合第 4 条护栏每个工具都要有清晰描述// 工具 1网页搜索——description 会进入模型可见的函数 schema [Description(Searches the web for the given query and returns top result titles and snippets)] static async Taskstring WebSearch(string query) { // 调用搜索服务返回结果文本生产环境应接入真实搜索 API return await Task.FromResult($Search results for: {query}); } // 工具 2记笔记——Agent 在总结前先持久化中间发现 [Description(Appends a note to the research scratchpad)] static async Taskstring TakeNote(string note) { // 追加到本地笔记存储 return await Task.FromResult($Note saved ({note.Length} chars)); }AIFunctionFactory.Create会自动从方法的参数名、类型与[Description]特性生成 OpenAI 兼容的工具 schema这正是第 4 条护栏定义每个工具/函数时带清晰 schema 和描述的底层机制。分层设计从 IChatClient 到编排层technology-selection技能的 Step 1b 把 AI 库划分为四个层级Agentic 分支位于最上层层级库使用时机抽象层Microsoft.Extensions.AIMEAI永远是地基。单次提示词→回复、简单的有界函数调用直接用IChatClient提供方 SDKAzure.AI.OpenAI/OpenAI/Azure.AI.Inference/OllamaSharp通过AddChatClient藏在 MEAI 后面编排层Microsoft.Agents.AI预发布多步工具调用、持久化 Agent 循环、多 Agent 工作流CopilotGitHub.Copilot.SDK仅构建 Copilot 平台扩展时使用两条硬性规则provider 必须通过AddChatClient注册在 MEAI 之后业务逻辑只依赖IChatClient绝不在业务代码里直接newprovider SDK 或裸调HttpClient访问 OpenAI——这会破坏抽象层、让重试/超时/观测等横切能力失效。值得一提的是本仓库的 docs/agentic-workflows.md 展示了另一类Agentic Workflow基于 GitHub Agentic Workflow 的 DevOps 编排其编排者-工作者-整理者架构与本文的 AI Agent 编排属于不同领域但用框架编排、设置边界、记录审计日志的设计哲学是相通的可作为对照阅读。计划模式与实现模式按需决定深度technology-selection技能明确要求先选对技术然后只交付任务要求的内容。针对 Agentic 分支Plan / 比较 / 仅架构或明确不要写代码只依据 SKILL.md 的分支 essentials 作答覆盖 Agent Framework 之于IChatClient的价值、MaximumIterations、工具 schema、token 预算、每步日志等要点即可不要打开 reference 文件也不要擅自搭建项目。写实现代码阅读并遵循 agentic.md 的包与实现指引Hybrid 场景则同时阅读 ML.NET 与 LLM 两个 reference。评估文件 eval.yaml 的Agentic workflow with guardrails场景印证了实现模式的验收标准输出必须包含MaximumIterations、Microsoft.Agents.AI、Microsoft.Extensions.AI并且 rubric 明确要求用 Agent Framework 编排而非裸 LLM 循环基于 MEAI 作为地基定义带描述的显式工具 schema通过记录工具选择、输入、输出实现可观测性提及或实现 token 预算/成本上限——这五条与七条护栏一一对应是从评估端对护栏的强制校验。常见反模式与正确替代technology-selection技能总纲的反模式清单中与 Agentic 分支直接相关的有三条反模式正确做法用IChatClient手写多步工具循环用Microsoft.Agents.AIMaximumIterations 工具分发单次提示词→回复也用 Agent Framework直接用IChatClient不要引入编排开销业务逻辑中裸用HttpClient/OpenAI SDK 与 MEAI 混用统一抽象层只依赖IChatClient反向的边界同样重要不是所有 AI 任务都该 Agent 化。表格分类、回归、聚类等结构化任务应选 ML.NET确定性、无云端依赖、成本低LLM 与 Agent 框架在此类任务上更慢、更贵且非确定纯单轮对话也不该引入 Agent Framework。先分类、再选型、后实现是这套技能体系的整体方法论。小结在 .NET 中落地 Agentic Workflow 的正确路径是先用决策树确认任务确实需要工具调用/多步推理/多 Agent然后以Microsoft.Extensions.AI为地基、Microsoft.Agents.AI为编排层搭建 Agent最后用MaximumIterations、token 预算、显式工具 schema 与逐步日志这四条核心护栏守住执行边界。仓库中的 agentic.md 提供了浓缩的实现要点SKILL.md 提供了决策树与反模式清单而 eval.yaml 则从评估角度把每条护栏固化为可自动校验的标准——三者配合构成了从选型到实现再到验证的完整闭环。【免费下载链接】skillsRepository for skills to assist AI coding agents with .NET and C#项目地址: https://gitcode.com/GitHub_Trending/skills17/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考