企业官网建设流程全解析

1. 为什么我建议你用 Semantic Kernel 跑第一个 Agent

Semantic Kernel 是微软开源的一套智能体（Agent）编排框架，简单说，它能让你用 C#、Python 或 Java 把大语言模型、函数调用、插件（Plugin）串成一个能自己决定"下一步做什么"的智能体。它最核心的能力是 Function Calling 编排：你写好普通函数，打上[KernelFunction]标记，模型就能在对话里主动请求调用它，框架负责把参数解析好、执行、再把结果喂回模型生成最终回答。适合谁？适合已经会一点 C# 或 Python、想快速验证 Agent 编排能力、又不想从零手写 function calling 循环的开发者。

我这次的目标很明确：不折腾多平台账号，用一个统一的 Key 通道把模型 endpoint 指过去，跑通一个最小对话式 Agent，让它能根据我的自然语言指令去调用本地函数改状态。模型通道我用 TaoToken 统一管理，官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 基址是 https://taotoken.net/api 。这样做的直接好处是：Semantic Kernel 里那行AddOpenAIChatCompletion的 endpoint 和 apiKey 只填一次，后面换模型、加模型都不用改业务代码。

很多人卡在第一步不是因为框架难，而是因为"模型从哪来、Key 怎么配、endpoint 填什么"这三件事没理顺。Semantic Kernel 本身对 OpenAI 兼容接口支持得很好，只要你有一个兼容/v1/chat/completions的地址和 Key，就能接上。所以这篇我按"能跟做"的标准来写：先给环境变量和 settings 配置片段，再给完整可复制的 Program.cs，最后给验证步骤和报错排查。你照着敲一遍，大概二十分钟能跑出第一次 Agent 回复。

2. 前置准备：TaoToken 统一 Key 与 Semantic Kernel 环境搭建

先说 TaoToken 这一侧要拿到什么。你需要三样东西：Base URL、API Key、Model ID。Base URL 就是 https://taotoken.net/api ，注意 Semantic Kernel 的 OpenAI 连接器会在后面拼/v1/chat/completions，所以你在代码里填的 endpoint 应该是https://taotoken.net/api/v1这种带/v1的形式，具体以你控制台里显示的接入地址为准。API Key 在控制台的 API Keys 页面创建，入口是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 。Model ID 就是你要调用的模型名，比如gpt-4o-mini这类，填你在模型列表里看到的那个字符串。

这里有个我踩过的坑：Semantic Kernel 的AddOpenAIChatCompletion方法签名里，endpoint参数是Uri类型，很多人直接把https://taotoken.net/api填进去，结果请求打到了https://taotoken.net/api/chat/completions，少了/v1，直接 404。正确做法是确认你的接入地址带/v1。如果你不确定，可以先在终端用 curl 测一下：

curl https://taotoken.net/api/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -d '{ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "ping"}] }'

能返回 JSON 就说明 Base URL 和 Key 没问题，再往 Semantic Kernel 里填。

环境这边，我用的 .NET 8。先建项目、装包：

dotnet new console -n SkFirstAgent cd SkFirstAgent dotnet add package Microsoft.SemanticKernel dotnet add package Microsoft.Extensions.Logging dotnet add package Microsoft.Extensions.Logging.Console

Microsoft.SemanticKernel是核心包，后面两个是日志包，方便你在调试时看到模型请求和函数调用的 trace。装完之后，我建议把 Key 和 endpoint 放到环境变量里，别硬编码。Linux/macOS 下：

export TAOTOKEN_API_KEY="sk-你的key" export TAOTOKEN_BASE_URL="https://taotoken.net/api/v1" export TAOTOKEN_MODEL_ID="gpt-4o-mini"

Windows PowerShell 用$env:TAOTOKEN_API_KEY="sk-..."。这样做的原因是：你后面如果把代码提交到仓库，不会把 Key 泄露出去；换模型时也只改环境变量，不动代码。Semantic Kernel 的 builder 里读环境变量就行。

如果你更习惯用配置文件而不是环境变量，也可以在项目根目录建一个appsettings.json，但要注意把它加进.gitignore。我个人的习惯是：本地开发用环境变量，CI 里用 secrets 注入，两边都不落盘。这一步做完，前置就齐了，接下来进代码。

3. 可复制配置：settings 片段与 Kernel Builder 写法

这一节给你可以直接抄的配置。先给一个appsettings.json的样例，如果你走配置文件路线，路径放在项目根目录，和.csproj同级：

{ "TaoToken": { "BaseUrl": "https://taotoken.net/api/v1", "ApiKey": "sk-你的key", "ModelId": "gpt-4o-mini" }, "Logging": { "LogLevel": { "Default": "Information", "Microsoft.SemanticKernel": "Trace" } } }

注意BaseUrl带/v1，ModelId填你实际要用的模型。如果你不想用 JSON，用环境变量也行，代码里Environment.GetEnvironmentVariable("TAOTOKEN_BASE_URL")读出来即可。

然后是 Kernel Builder 的核心写法。Semantic Kernel 1.0+ 的推荐方式是用Kernel.CreateBuilder()，然后AddOpenAIChatCompletion。关键三件套是 Base URL、Key、Model ID，一个都不能少：

using Microsoft.SemanticKernel; using Microsoft.SemanticKernel.ChatCompletion; using Microsoft.SemanticKernel.Connectors.OpenAI; var baseUrl = Environment.GetEnvironmentVariable("TAOTOKEN_BASE_URL") ?? "https://taotoken.net/api/v1"; var apiKey = Environment.GetEnvironmentVariable("TAOTOKEN_API_KEY") ?? throw new InvalidOperationException("TAOTOKEN_API_KEY 未设置"); var modelId = Environment.GetEnvironmentVariable("TAOTOKEN_MODEL_ID") ?? "gpt-4o-mini"; var builder = Kernel.CreateBuilder(); builder.AddOpenAIChatCompletion( modelId: modelId, endpoint: new Uri(baseUrl), apiKey: apiKey, serviceId: "TaoToken" ); builder.Services.AddLogging(s => s.AddConsole().SetMinimumLevel(LogLevel.Trace)); Kernel kernel = builder.Build(); var chatService = kernel.GetRequiredService<IChatCompletionService>();

这里serviceId我填了"TaoToken"，它只是个标识，方便你在多模型场景下区分。endpoint必须是Uri类型，所以用new Uri(baseUrl)包一下。日志级别设成Trace是为了让你在控制台看到完整的请求和函数调用过程，调试完可以调回Information。

如果你用的是 Cline MCP 或者 Codex 这类工具，它们的配置逻辑是一样的：Base URL 填https://taotoken.net/api/v1，Key 填你的 TaoToken Key，Model ID 填模型名。三件套对齐，任何 OpenAI 兼容客户端都能接。Semantic Kernel 的好处是它把这套东西抽象成了AddOpenAIChatCompletion，你只要保证这三个参数对，剩下的编排逻辑框架帮你处理。

配置写完后，先别急着加插件，跑一个纯对话验证通道是否通。下一节给完整代码。

4. 验证请求：跑通第一个带插件的对话式 Agent

这一节给完整可复制的Program.cs。我加了一个LightsPlugin，模拟三盏灯的状态，让 Agent 能根据"帮我关一下灯"这种自然语言去调用change_state函数。这是 Semantic Kernel 最典型的 Agent 编排场景：模型负责理解意图，框架负责把意图翻译成函数调用。

using System.ComponentModel; using System.Text; using System.Text.Json.Serialization; using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Logging; using Microsoft.SemanticKernel; using Microsoft.SemanticKernel.ChatCompletion; using Microsoft.SemanticKernel.Connectors.OpenAI; var baseUrl = Environment.GetEnvironmentVariable("TAOTOKEN_BASE_URL") ?? "https://taotoken.net/api/v1"; var apiKey = Environment.GetEnvironmentVariable("TAOTOKEN_API_KEY") ?? throw new InvalidOperationException("TAOTOKEN_API_KEY 未设置"); var modelId = Environment.GetEnvironmentVariable("TAOTOKEN_MODEL_ID") ?? "gpt-4o-mini"; var builder = Kernel.CreateBuilder(); builder.AddOpenAIChatCompletion( modelId: modelId, endpoint: new Uri(baseUrl), apiKey: apiKey, serviceId: "TaoToken" ); builder.Services.AddLogging(s => s.AddConsole().SetMinimumLevel(LogLevel.Trace)); Kernel kernel = builder.Build(); var chatService = kernel.GetRequiredService<IChatCompletionService>(); kernel.Plugins.AddFromType<LightsPlugin>("Lights"); var settings = new OpenAIPromptExecutionSettings { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto() }; var history = new ChatHistory(); history.AddSystemMessage("你是一个家居助手，可以帮用户查询和切换灯光状态。"); string? userInput; do { Console.Write("User > "); userInput = Console.ReadLine(); if (string.IsNullOrWhiteSpace(userInput)) break; history.AddUserMessage(userInput); var result = await chatService.GetChatMessageContentAsync( history, executionSettings: settings, kernel: kernel ); Console.WriteLine("Assistant > " + result.Content); history.AddMessage(result.Role, result.Content ?? string.Empty); } while (true); public class LightsPlugin { private readonly List<LightModel> lights = new() { new LightModel { Id = 1, Name = "台灯", IsOn = false }, new LightModel { Id = 2, Name = "门廊灯", IsOn = false }, new LightModel { Id = 3, Name = "吊灯", IsOn = true } }; [KernelFunction("get_lights")] [Description("获取所有灯及其当前状态")] public Task<List<LightModel>> GetLightsAsync() { return Task.FromResult(lights); } [KernelFunction("change_state")] [Description("切换指定灯的开关状态")] public Task<LightModel?> ChangeStateAsync(int id, bool isOn) { var light = lights.FirstOrDefault(l => l.Id == id); if (light == null) return Task.FromResult<LightModel?>(null); light.IsOn = isOn; return Task.FromResult<LightModel?>(light); } } public class LightModel { [JsonPropertyName("id")] public int Id { get; set; } [JsonPropertyName("name")] public string Name { get; set; } = string.Empty; [JsonPropertyName("is_on")] public bool? IsOn { get; set; } }

跑起来后，输入"帮我关一下灯"，你会看到控制台先打印一堆 trace 日志，里面有FunctionChoiceBehavior触发的函数调用记录，然后 Assistant 回复类似"已经帮你把台灯、门廊灯、吊灯都关掉了"。这个过程中，模型并没有直接改灯的状态，而是请求调用change_state，Semantic Kernel 执行后把结果返回给模型，模型再生成自然语言总结。这就是 Agent 编排的本质。

如果你想验证流式输出，把GetChatMessageContentAsync换成GetStreamingChatMessageContentsAsync，用await foreach逐块打印即可。流式在长回答场景下体验更好，但调试函数调用时非流式更清晰，因为你能一次看到完整的 tool call 和结果。

5. 常见报错排查：401、local proxy failed 与 choices 读取失败

这一节我按真实遇到的报错来写，每个都给定位思路。

401 Unauthorized。最常见的原因是 Key 没读到或者填错。先确认环境变量在当前终端生效：echo $TAOTOKEN_API_KEY（Windows 用echo $env:TAOTOKEN_API_KEY）。如果为空，说明你 export 的终端和跑dotnet run的终端不是同一个。另一个原因是 Key 前后带了空格或引号，复制的时候容易带上。还有一种情况是你把Bearer前缀也写进了 apiKey，Semantic Kernel 的AddOpenAIChatCompletion会自动加Bearer，你只需要填sk-xxx本身。

local proxy failed / connection refused。这个报错通常出现在你本地配了 HTTP 代理，但代理没启动或者不支持 HTTPS 隧道。Semantic Kernel 底层用HttpClient，会读系统代理设置。排查方法：先curl https://taotoken.net/api/v1/chat/completions看能不能通，如果 curl 通但代码不通，就是代理配置问题。可以在代码里显式关掉代理：

builder.Services.AddSingleton<HttpClient>(sp => { var handler = new HttpClientHandler { Proxy = null, UseProxy = false }; return new HttpClient(handler); });

注意这段要在AddOpenAIChatCompletion之前注册，否则连接器会用默认的 HttpClient。

reading choices / index out of range。这个报错说明请求发出去了，但返回的 JSON 里没有choices字段，或者choices是空数组。原因通常是：模型名填错了，服务端返回了错误信息而不是正常补全；或者你的 Base URL 少了/v1，打到了别的路由返回了 HTML。定位方法：把日志级别开到Trace，看原始响应体。如果响应体里是{"error": {...}}，那就是模型名或权限问题；如果是 HTML，那就是 URL 路径不对。还有一种情况是模型返回了 tool call 但你的FunctionChoiceBehavior没开，导致框架解析失败，这种会在日志里看到FunctionChoiceBehavior相关的 warning。

OAuth / token 过期类报错。如果你用的是需要 OAuth 的模型通道，Key 可能是短期 token，过期后会返回 401 或 403。TaoToken 的 Key 是长期有效的 API Key，一般不会遇到这个问题。但如果你在别处混用了 OAuth token，记得区分。排查时看响应头里的WWW-Authenticate字段，能看出是哪种认证失败。

函数没被调用。Agent 回复了文字但没执行change_state，通常是FunctionChoiceBehavior没设成Auto()，或者函数的[Description]写得太模糊，模型不知道什么时候该调。把描述写具体，比如"切换指定灯的开关状态，参数 id 是灯编号，isOn 是目标状态"，命中率会高很多。

6. 下一步：把 Agent 接到真实业务与长期编码场景

跑通这个最小示例后，你可以往几个方向扩展。第一是把LightsPlugin换成真实业务函数，比如查订单、发通知、读数据库，只要打上[KernelFunction]就能被 Agent 调用。第二是加多个插件，让 Agent 在多个能力之间自己选，这就是多工具编排。第三是接流式输出和对话历史持久化，做成一个能长期跑的助手。

如果你打算把 Semantic Kernel 用在长期编码或 Agent 项目里，建议把模型通道固定下来，别每次换模型都改代码。TaoToken 的 Coding Plan 就是为这种场景准备的，入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite ，适合需要稳定跑 Agent 编排的开发者。想先验证模型对话效果，可以去 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 直接试。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有各语言的接入示例。Key 管理还是那个入口：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 。

最后说个实用技巧：Semantic Kernel 的 trace 日志在调试函数调用时非常有用，但生产环境记得把级别调回Information或Warning，否则日志量会很大。另外，ChatHistory会随着对话轮次增长，长会话要自己做截断或摘要，不然 token 消耗会线性上升。我一般保留最近 10 轮，更早的用模型摘要成一段系统消息塞回去。这样既保留上下文，又控制成本。