一句话:项目 .NET 后端的整个 Agent 层是搭在微软 2026 主推的官方 SDK Microsoft.Agents.AI 1.4.0 上,自己只写了一个 303 行的桥 把 SDK 连到内网 LMStudio。这份附录讲清楚:SDK 是啥、桥怎么搭、能不能换、踩过什么坑。
Microsoft Agent Framework(MAF) = 微软 2026 主推的官方 Agent 开发框架 · 2026-04-03 发布 1.0 GA · 吸收合并了原来的 Semantic Kernel 和 AutoGen(两者进入维护模式)。
读法:上层调用下层。项目业务代码 只认最上面两层的 SDK API · 底下换 provider 只需改配置,不改代码。303 行的桥 是唯一连接点。
如果不用 SDK · 下面这些都得自己写。
上面 7 类活儿 · 每一类拆开都是几百行代码。项目整层没写,只写了 303 行的路由桥。
SDK 默认只认 Azure OpenAI · 项目要连内网 LMStudio + 5 pool 路由 · 靠 PoolRoutingChatClient.cs(303 行)。
poolId="lmstudio-chat" · kbId · runIdnew ChatClientAgent(_chatClient, options) · SDK 一等公民 APIPickBackend() 拿到 endpointOpenAIClient.GetChatClient(x).AsIChatClient() 发真请求到 http://192.168.1.223:1234/v1SDK 只认标准字段。项目的 poolId / kbId / runId 全塞进 AdditionalProperties(SDK 留的口子):
chatOptions.AdditionalProperties["poolId"] = "lmstudio-chat"; chatOptions.AdditionalProperties["kbId"] = "kb_707811..."; chatOptions.AdditionalProperties["runId"] = "run_a1b2c3";
var openAiClient = new OpenAIClient(credential, new OpenAIClientOptions {
Endpoint = new Uri("http://192.168.1.223:1234/v1"),
NetworkTimeout = TimeSpan.FromMinutes(40), // 本地 GPU ~2 tok/s
});
return openAiClient.GetChatClient("ornith-1.0-35b-mtplx").AsIChatClient();
services.AddScoped<IChatClient, PoolRoutingChatClient>(); // 之后所有 SDK 需要 IChatClient 的地方都会自动拿到桥
2026 年 Agent 框架格局:除 MAF 外还有 7 个主流方案 · 但都是 Python/TS · .NET 上 MAF 几乎唯一。
数据来源:LangChain 官方评测(2026-06)· Turing.com 综述 · AliceLabs Production Ranking Q2 2026 · Speakeasy 2026 综述。
这是关键 —— 项目在 .NET 10 · 要换 = 要么离开 .NET 生态 · 要么在 .NET 圈里找 · 但选择极少:
合理 · 且几乎唯一。
已知负债:MAF 1.0 只有几个月 · 生产战伤远少于 LangGraph(2 年+)。这个负债项目自己也清楚。
留在 MAF · 跟着微软路线图升级 1.5 / 2.0。推荐。
改用 LangGraph 1.0(最稳)或 LlamaIndex Workflows(强化 RAG)。整套 .NET Agent 层重写。
项目本身已有 Python 后端跑 pikerag · Agent 编排可以留在 Python 侧上 LangGraph · .NET 侧继续 MAF。
症状:Playground 发消息就报这个错。
根因:MVR Agent 的 model_pool_id 应该是 lmstudio-chat · 被 docker compose stop → start 触发的 db-init 重置成了 default(不存在)。
修:UPDATE agent SET model_pool_id='lmstudio-chat' WHERE id=12;
症状:日志频繁 duplicate key value violates uq_token_bucket。
根因:同秒并发调用相同 pool · INSERT 撞 unique 约束。
修(未做):改成 INSERT ... ON CONFLICT DO UPDATE SET tokens = tokens + EXCLUDED.tokens。
症状:首次连 LMStudio 打到 /chat/completions(而非 /v1/chat/completions)· 404。
根因:OpenAI SDK 只会自动追加 /chat/completions · 不加 /v1。Azure 部署路径是 deployments/{name}/chat/completions · 社区 endpoint 都要手动加 /v1。
修:桥里 L199 加了 var suffix = protocol == "azure-inference" ? "" : "/v1";