agent-framework-builder-dotnet

.NET Agent Framework 构建指南

将此技能作为开展 .NET Agent Framework 应用开发的入口。选择能够保留所需行为的最简单框架模式，只加载相关参考资料，并根据当前 API 验证实现，而不是依赖对预览版语法的记忆。

工作流

1. 检查现有解决方案：目标框架、SDK 版本、包管理方式（集中式包管理或按项目管理），以及已安装的 Microsoft.Agents.AI.* 包和版本。
2. 从下表中选择最简单的匹配方案。
3. 仅在设计问题会实质性改变实现时，才解决这些问题。
4. 只阅读所选方案的链接参考资料。
5. 实施最小且完整的变更，并运行能覆盖该变更的最精简验证。

核心抽象

• 聊天客户端是一个 Microsoft.Extensions.AI.IChatClient。它向模型提供方发送消息和选项，并返回聊天响应或流式更新。Agent Framework 基于 Microsoft.Extensions.AI 的类型构建，例如 ChatMessage、AIFunction 和 ChatOptions，而不是重新定义这些类型。
• Agent 派生自 AIAgent，并提供 RunAsync(...) 和 RunStreamingAsync(...)。ChatClientAgent 是标准实现：它将 IChatClient 与指令、工具、上下文提供方、聊天历史提供方和会话处理封装在一起。提供方包通常通过 AsAIAgent(...) 扩展方法创建一个实例。
• Harness Agent 是来自 Microsoft.Agents.AI.Harness 的 HarnessAgent。它将 ChatClientAgent 与一组特定的上下文提供方和 Agent 装饰器封装在一起；它仍然是一个 AIAgent。
• 工作流（Microsoft.Agents.AI.Workflows）负责协调执行器和 Agent 之间的显式执行路径。AgentWorkflowBuilder 基于 AIAgent 参与者提供标准的顺序、并发、交接、群聊和 Magentic 模式。当调用方需要 Agent 契约时，工作流可以作为 AIAgent 暴露。

用户界面选项

• DevUI（Microsoft.Agents.AI.DevUI）是一个本地开发、测试和调试工具，用于与 Agent 和工作流交互。切勿将 DevUI 作为生产应用程序主机运行或部署。
• AG-UI 是面向应用程序的协议集成，用于将 Agent 或工作流连接到兼容 AG-UI 的前端。当产品需要流式 UI 事件、工具交互、共享状态、中断或恢复行为时，请使用 Microsoft.Agents.AI.Hosting.AGUI.AspNetCore（服务端）。

选择构建路径

路径	适用场景	详情
普通 Agent	由单个模型驱动的参与者负责任务，且工具、会话、上下文和中间件已足够。	普通 Agent
Harness Agent	产品需要一个包含待办事项、模式、记忆、审批、技能、可选文件访问、后台 Agent、Shell、压缩或重复执行的运行循环。	Harness Agent
工作流或编排	显式阶段、路由、并行处理、多个参与者、检查点、人类输入或中间输出是确保正确性的关键。	工作流
声明式定义	YAML 应作为受支持的 Agent 或工作流的事实来源。	声明式定义
评估	主要关注预期输出、工具调用、失败运行或质量回归。	评估
可观测性	任务是通过跟踪记录、日志和指标诊断或监控运行时行为。	可观测性
可扩展性	应用需要自定义聊天客户端、Agent、上下文提供程序、聊天历史记录提供程序或中间件。	可扩展性
集成	任务是选择或接入提供程序、协议、记忆存储、工具服务、UI 或平台扩展。	集成
托管和部署	需要为 Agent Framework 代码配置进程宿主、协议端点、身份契约或部署方案。	托管和部署

默认设置

• 面向当前受支持的 .NET 版本。软件包面向当前及近期的 LTS .NET 版本进行多目标构建，部分软件包还支持 .NET Standard 2.0 和 .NET Framework 4.7.2。除非项目指定了特定版本，否则优先使用最新的受支持 SDK。
• 仅添加应用所需的最精简软件包（例如 Microsoft.Agents.AI 和一个提供程序软件包），而不要添加所有 Microsoft.Agents.AI.* 软件包。
• 各软件包的成熟度有所不同：有些已正式发布，有些仍处于 -preview 或 -alpha 阶段。依赖软件包前，请检查其当前状态；只有在确有需要时才允许使用预发布版本。
• 某些 API 标记为 [Experimental]，并会显示诊断 ID（例如 MAAI001）。只有在确认该功能可能发生变化后，才有意地在使用该 API 的代码范围内抑制诊断。
• Agent Framework 不会代你读取配置。请通过 IConfiguration、用户机密或环境变量读取端点、模型和密钥，并将其显式传递给客户端。优先使用 DefaultAzureCredential 等令牌凭据，而非 API 密钥，且绝不要将机密硬编码。
• DefaultAzureCredential 会探测多个凭据来源，这会增加延迟，并在生产环境中带来风险。如果已知托管身份（例如托管标识），请改用相应的特定凭据。

当前文档查询

对于稳定决策和常见模式，请参考本地指南。对于提供商矩阵、软件包成熟度、托管工具、部署详情或不熟悉的 API，请先查阅当前资料，再生成代码。

参考页面有意说明了选择规则、不变量和不明显的注意事项。有关签名和选项详情，请使用 XML 文档或 API 参考页面；有关端到端流程，请使用 Learn 或维护中的示例。

当编码 Agent 支持 MCP 时，请将 Microsoft Learn MCP Server 配置为 Streamable HTTP 服务：

https://learn.microsoft.com/api/mcp

请参阅 Microsoft Learn MCP Server setup，了解客户端配置。该端点供 MCP 客户端使用，直接在浏览器中打开时会返回错误。

1. 使用 microsoft_docs_search 搜索 Microsoft Learn。
2. 使用 microsoft_docs_fetch 获取相关页面。
3. 需要当前实现示例时，使用 microsoft_code_sample_search。
4. 如果 Learn MCP 不可用，且已安装可信的 mslearn CLI，请使用等效命令：

MCP 工具	预装 CLI
microsoft_docs_search(query="...")	mslearn search "..."
microsoft_docs_fetch(url="...")	mslearn fetch "..."
microsoft_code_sample_search(query="...", language="csharp")	mslearn code-search "..." --language csharp

请勿在编码会话期间获取并执行未固定版本的 CLI 软件包。请通过官方 Microsoft Learn MCP/CLI setup 按需安装或更新。

权威起点：

• Agent Framework overview
• Your first agent
• .NET SDK samples
• Foundry-hosted Agent Framework samples