Github Project - AI Agentic Framework (.NET) 渐进式学习指南

引言：什么是 AI Agentic Framework？在 .NET 生态系统中，AI Agentic Framework 是一个用于构建智能代理（Agent）的开源项目。这些代理能够自主执行任务、做出决策并与外部系统交互。本文将带你从零开始，逐步掌握如何使用这个框架构建一个简单的 AI 代理系统。## 基础概念：理解 Agent 与 Tool### Agent（代理）Agent 是一个能够感知环境并采取行动以实现目标的智能实体。在代码层面，它通常包含一个循环：接收输入 → 思考 → 执行动作 → 观察结果。### Tool（工具）Tool 是 Agent 可以调用的外部能力，比如搜索网页、计算数学问题或发送邮件。每个 Tool 都有明确的输入输出规范。## 第一步：环境搭建首先，确保你安装了 .NET 8 SDK。然后创建一个控制台项目：bashdotnet new console -n MyFirstAgentcd MyFirstAgentdotnet add package Microsoft.SemanticKerneldotnet add package Microsoft.SemanticKernel.Connectors.OpenAI## 第二步：创建你的第一个 Agent让我们从最基础的 Agent 开始——一个能回答问题的助手。### 代码示例 1：基础问答 Agentcsharpusing Microsoft.SemanticKernel;using Microsoft.SemanticKernel.ChatCompletion;using Microsoft.SemanticKernel.Connectors.OpenAI;// 1. 创建 Kernel 构建器var builder = Kernel.CreateBuilder();// 2. 配置 OpenAI 服务（需要替换为你的 API Key）builder.AddOpenAIChatCompletion( modelId: "gpt-4", apiKey: "your-api-key-here");// 3. 构建 Kernelvar kernel = builder.Build();// 4. 获取聊天完成服务var chatCompletion = kernel.GetRequiredService<IChatCompletionService>();// 5. 创建聊天历史var chatHistory = new ChatHistory();chatHistory.AddSystemMessage("你是一个友好的 AI 助手。");// 6. 与 Agent 对话Console.WriteLine("AI Agent 已启动！输入 'exit' 退出。");while (true){ Console.Write("\n你: "); var userInput = Console.ReadLine(); if (userInput?.ToLower() == "exit") break; // 添加用户消息 chatHistory.AddUserMessage(userInput); // 获取 AI 响应 var response = await chatCompletion.GetChatMessageContentAsync(chatHistory); // 添加助手响应到历史 chatHistory.AddMessage(response.Role, response.Content); Console.WriteLine($"Agent: {response.Content}");}代码解析：- Kernel 是框架的核心，负责管理所有组件- ChatHistory 维护对话上下文- IChatCompletionService 处理与 AI 模型的通信## 第三步：为 Agent 添加工具能力基础的问答 Agent 不够强大，让我们给它添加计算器和天气查询工具。### 代码示例 2：带工具的 Agentcsharpusing Microsoft.SemanticKernel;using Microsoft.SemanticKernel.ChatCompletion;using Microsoft.SemanticKernel.Connectors.OpenAI;using System.ComponentModel;// 1. 定义工具类public class MathTool{ [KernelFunction] [Description("计算两个数字的和")] public double Add(double a, double b) { return a + b; } [KernelFunction] [Description("计算两个数字的乘积")] public double Multiply(double a, double b) { return a * b; }}public class WeatherTool{ [KernelFunction] [Description("获取指定城市的天气（模拟数据）")] public string GetWeather(string city) { // 模拟天气数据 var weathers = new Dictionary<string, string> { {"北京", "晴天，25°C"}, {"上海", "多云，28°C"}, {"广州", "阵雨，30°C"} }; return weathers.ContainsKey(city) ? weathers[city] : "暂无该城市天气数据"; }}// 2. 主程序var builder = Kernel.CreateBuilder();builder.AddOpenAIChatCompletion( modelId: "gpt-4", apiKey: "your-api-key-here");// 3. 注册工具到 Kernelbuilder.Plugins.AddFromType<MathTool>("Math");builder.Plugins.AddFromType<WeatherTool>("Weather");var kernel = builder.Build();var chatCompletion = kernel.GetRequiredService<IChatCompletionService>();// 4. 配置自动工具调用var openAIPromptExecutionSettings = new OpenAIPromptExecutionSettings{ ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions};var chatHistory = new ChatHistory();chatHistory.AddSystemMessage("你是一个拥有计算和天气查询能力的 AI 助手。");Console.WriteLine("增强版 AI Agent 已启动！");Console.WriteLine("你可以问：'3 + 5 等于多少？' 或 '北京天气如何？'");while (true){ Console.Write("\n你: "); var userInput = Console.ReadLine(); if (userInput?.ToLower() == "exit") break; chatHistory.AddUserMessage(userInput); // 自动调用工具 var response = await chatCompletion.GetChatMessageContentAsync( chatHistory, openAIPromptExecutionSettings, kernel ); chatHistory.AddMessage(response.Role, response.Content); Console.WriteLine($"Agent: {response.Content}");}代码解析：- KernelFunction 属性标记方法为可调用的工具- Plugins.AddFromType 注册工具集合- ToolCallBehavior.AutoInvokeKernelFunctions 让 AI 自动决定何时调用工具## 高级用法：构建多代理协作系统当任务复杂时，单个 Agent 可能不够用。框架支持创建多个专业 Agent 协同工作。### 创建主管 Agent 和子 Agentcsharp// 主管 Agent：分配任务public class SupervisorAgent{ private readonly Kernel _kernel; public async Task<string> CoordinateTask(string task) { // 分析任务并分配给合适的子 Agent if (task.Contains("计算")) { var mathAgent = new MathTool(); return await mathAgent.ExecuteAsync(task); } else if (task.Contains("天气")) { var weatherAgent = new WeatherTool(); return await weatherAgent.ExecuteAsync(task); } return "无法处理该任务"; }}## 性能优化与最佳实践1. 缓存策略：对频繁查询的结果使用内存缓存2. 错误处理：为每个工具调用添加 try-catch 块3. 日志记录：使用 ILogger 记录 Agent 决策过程4. 超时控制：设置合理的 API 调用超时时间## 实际应用场景- 客服系统：自动处理常见问题，复杂问题转人工- 数据分析：连接数据库，自动生成报表- 代码审查：分析 PR，给出修改建议## 总结我们通过三个渐进步骤学习了 AI Agentic Framework 的核心概念：1. 基础 Agent：掌握 Kernel 和聊天服务的基础使用2. 工具增强：通过 Plugins 为 Agent 添加自定义能力3. 多代理协作：构建更复杂的智能系统这个框架让 .NET 开发者能够轻松地将 AI 能力集成到应用中，而无需深入机器学习细节。建议你从最简单的问答 Agent 开始，逐步添加更多工具和逻辑，最终构建出能解决实际问题的智能代理系统。延伸练习： 尝试添加一个文件读取工具，让 Agent 能够分析本地文本文件的内容。