常见问题
认证与配置
Q：DefaultAzureCredential 在本地开发时认证失败怎么办？
先确认已经执行过 az login 登录 Azure CLI。如果仍然失败，可以设置环境变量 AZURE_TENANT_ID、AZURE_CLIENT_ID 和 AZURE_CLIENT_SECRET 来使用服务主体认证。也可以在代码中临时换用 AzureCliCredential 来排查问题。
Q：生产环境应该用什么认证方式？
如果你运行在 Azure 托管环境中（Azure App Service、Azure Container Apps、Azure VM），使用 ManagedIdentityCredential。如果运行在自托管的服务器上，使用 ClientSecretCredential。永远不要在生产环境使用 DefaultAzureCredential——它的链式尝试机制会导致不必要的延迟，多个认证来源也会增加安全风险。
Q：必须用 Azure OpenAI 吗？能不能用其他模型？
Microsoft.Agents.AI 支持任何实现了 IChatClient 接口的 AI 提供商。官方支持 OpenAI、Azure OpenAI、Anthropic。你也可以通过自定义 IChatClient 实现来接入 Ollama、DeepSeek、智谱等任何兼容 OpenAI API 的模型。
Agent 行为
Q：Agent 不调用注册的工具，而是自己编答案怎么办？
根本原因通常是工具的 [Description] 写得太模糊。描述应该包含"触发条件"和"返回值格式"两个要素。例如，不要把工具写成 [Description("获取天气")]，而要写成 [Description("根据城市名获取实时天气数据。当用户问天气时调用此工具。返回格式：城市名、温度、天气状况")]。
Q：Agent 在多轮对话中自己纠正之前的回答，这是好是坏？
Agent 有能力在后续对话中纠正自己之前的错误——这是 Agent 的优势，它不像传统程序那样一次执行就固定结果。但这意味着你需要在关键业务场景中对 Agent 的输出做验证。
工具设计
Q：一个 Agent 可以注册多少个工具？
理论上没有硬性限制，但实践中建议控制在 20 个以内。工具越多，LLM 选错工具的概率就越高。如果你有大量工具，考虑分组策略：创建一个"路由 Agent"先判断用户意图，然后路由到专门的子 Agent。
Q：工具函数的参数类型有什么限制？
AIFunctionFactory.Create 支持大部分常见类型：string、int、double、bool、DateTime、枚举类型以及它们的数组和可空版本。不支持复杂的嵌套对象、泛型类型或接口类型。需要复杂参数时，考虑把 JSON 字符串作为参数传入，在工具内部反序列化。
性能与成本
Q：流式响应和非流式响应哪个更贵？
Token 计费是一样的——LLM 按生成的 Token 数量计费，和是否流式无关。流式只是改变了返回方式。从用户体验角度，流式响应几乎是必须的。
Q：多轮对话的 Token 消耗怎么控制？
每轮对话的 Token 消耗 = 用户输入 + Agent 回复 + 历史上下文。控制策略有三种：滑动窗口（只保留最近 N 轮）、摘要压缩（早期对话压缩为摘要）、分段加载（Session 序列化后分段处理）。通常组合使用：保留最近 20 轮完整对话，更早的内容压缩为摘要。
架构设计
Q：AgentSession 和 ChatHistoryProvider 有什么区别？
ChatHistoryProvider 管理底层消息列表的"存储方式"。AgentSession 是更高层次的抽象，除了消息历史还包含会话状态、工具调用上下文等。简单来说：如果你只需要控制"对话历史怎么存"，用 ChatHistoryProvider；如果你需要管理"完整的会话生命周期"，用 AgentSession。
调试技巧
Q：怎么查看 Agent 内部调用了哪些工具？
- 在工具函数内部加
Console.WriteLine或日志输出 - 用 ASP.NET Core 的
ILogger记录每次工具调用 - 检查
AgentResponse中的内容类型——有FunctionCallContent和FunctionResultContent说明工具被调用了
Q：想要中途停止 RunStreamingAsync 怎么办？
RunStreamingAsync 支持 CancellationToken。创建一个 CancellationTokenSource，用户点击"停止"时调用 cts.Cancel()。注意取消流式只停止接收新 Token，不会回滚已经完成的操作。
Q：Agent 在开发环境正常，部署到生产后工具调用不工作了？
最可能的原因：生产环境模型不同导致 Function Calling 行为差异、网络策略阻止了工具调用的 API 请求、认证方式不同、生产环境的 Prompt 模板被修改了。
学习路径建议
第一阶段：巩固基础（1-2 周） 把本教程每个章节的代码亲手敲一遍。不要复制粘贴——亲手敲代码的过程中遇到的那些编译错误，是你真正理解 API 的契机。
第二阶段：探索官方文档（1 周） 通读 Microsoft Learn 上的 Agent Framework 官方文档，重点看 Tools、Conversations、Running Agents、Middleware 等子页面。
第三阶段：企业实战（2-4 周） 选择一个真实业务场景（内部 IT 工单系统、智能客服、文档处理流水线），从头设计并实现一个完整的 Agent 应用。
第四阶段：架构深入（长期） 学习 A2A 协议、多 Agent 协作模式、向量数据库集成、CI/CD 部署流水线。关注 Agent Pipeline、Observability、Evaluation、Agent Safety 等高级主题。
版本兼容性
- NuGet 包的 prerelease 标记：
Azure.AI.Projects和Microsoft.Agents.AI.Foundry当前为 prerelease 版本 - .NET 版本要求：.NET 8 或更高版本
- Workflow 包独立性：
Microsoft.Agents.AI.Workflows是独立的，不使用工作流时可不引用 - A2A 协议包依赖：
Microsoft.Agents.AI.Hosting.A2A.AspNetCore依赖 ASP.NET Core，不能在 Console 应用中使用
参考资源
| 资源名称 | 访问地址 |
|---|---|
| MS Learn 官方文档（中文） | learn.microsoft.com/zh-cn/agent-framework |
| 官方 GitHub 源代码仓库 | github.com/microsoft/agent-framework |
| NuGet 包页面 | nuget.org/packages/Microsoft.Agents.AI |
| Azure AI Foundry 门户 | ai.azure.com |
核心心法
Agent 不是传统的程序，你写的不是控制逻辑，而是行为边界和决策指南。 工具是 Agent 的手脚，Prompt 是 Agent 的大脑，Session 是 Agent 的记忆，Workflow 是 Agent 的行动计划。把这四样设计好，Agent 自然会做出正确的决策。
从简单开始，逐步迭代。 不要试图在第一天就构建一个包含工具、多轮对话、工作流、A2A 协议的完美 Agent。先让一个最简单的 Agent 跑通，验证 LLM 连接正常。然后逐步添加工具、引入会话、加入工作流。每一步都验证前一步的功能不被破坏。
建议在项目初期就建立一套简单的评估机制——准备一组固定的测试问题，每次修改后都跑一遍，对比 Agent 的回答质量。这种"回归测试"在 Agent 开发中比传统单元测试更难做（因为答案不是精确的），但维护一个测试问题集仍然能帮你及早发现退化。
本文作者：比特矩阵 许可协议：CC BY-NC-SA 4.0更新日期：2026 年 4 月（基于 Microsoft Agent Framework 官方文档） 官方文档：learn.microsoft.com/zh-cn/agent-framework