【Agent进阶专题】独立 Models Extension

本篇把”选择哪个模型提供方”从 Agent 中抽成独立的 Models Extension:它收集所有 ModelProvider,按配置选定一个,对外统一暴露 ModelService。

能力介绍

Agent 之前自己决定用哪个模型:start 里 context.all(ModelProviders) 取第一个。这带来两个问题:模型选择逻辑埋在生产业务的插件里;将来有多个提供方时无从选择。

现在把”选谁”抽出来。独立的 Models Extension 在启动时收集所有 models.providers 注册的提供方,按配置 defaultProvider 选定一个(没有配置则取第一个),对外统一暴露 ModelService。Agent 只依赖 ModelService,DeepSeek 只实现 ModelProvider。

实现思路

Models 自己不发请求,它是一层选择与转发。数据来源有两个:

  • 扩展点 models.providers:DeepSeek 等提供方在 setup 里注册。
  • 配置 defaultProvider:指定默认使用哪个提供方。

start 时收集提供方列表。列表为空直接启动失败;有 defaultProvider 按 id 查找,找不到也失败;都没有则取第一个。选定后,ModelService.chat 原样转发给这个提供方。

setup 行为

setup 只把 models 能力放入注册表:

1
2
3
setup(context) {
context.add(Hook.Models, models);
}

start 行为

start 收集并选定提供方:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
start(context) {
const providers = context.all<ModelProvider>(Hook.ModelProviders);

if (providers.length === 0) {
throw new Error("Models needs at least one provider.");
}

provider = defaultProvider
? providers.find(({ id }) => id === defaultProvider)
: providers[0];

if (!provider) {
throw new Error(`Model provider "${defaultProvider}" is not registered.`);
}
}

即使只装 Models 而没有提供方,Kernel 也会在启动阶段失败,而不是等第一次聊天才报错。

stop 行为

stop 清空选定的提供方:

1
2
3
stop() {
provider = undefined;
}

Agent 的变化

Agent 不再关心提供方列表,start 只取 Models 能力:

1
2
3
4
5
start(context) {
runtime = context;
workspace = context.get<WorkspaceService>(Hook.Workspace);
models = context.get<ModelService>(Hook.Models);
}

传给模型的消息也只保留 role 和 content:

1
2
3
const messages = (await activeWorkspace.messages()).map(
({ role, content }) => ({ role, content }),
);

抓手

Models 对外暴露一个名为 models 的能力,它的契约是 ModelService:

1
2
3
export interface ModelService {
chat(messages: ModelMessage[], signal?: AbortSignal): AsyncIterable<string>;
}
  • messages:完整的消息历史,只含 role 和 content。
  • signal:可选的取消信号,转发给底层提供方。
  • 返回值:AsyncIterable<string>,按提供方的流式结果逐段返回。

对调用方来说,它不关心背后是哪个模型、怎么发请求。选谁由配置决定:

1
2
3
4
5
6
{
"version": 1,
"extensions": {
"models": { "defaultProvider": "deepseek" }
}
}

到这里,模型能力从”Provider 直接面对业务”变成了”Models 选择、Provider 实现”的两层结构。

发散点:

  • 更多提供方 - 在 models.providers 上注册更多实现,用配置切换默认。
  • 自动回退 - 选中的提供方失败时,回退到下一个可用提供方。
  • 能力区分 - 区分只支持文本和也支持图像、工具调用的提供方。