AI Agent / 系统课时
设计模型接入层
设计模型接入层
本节解决 Agent 业务逻辑直接依赖具体模型 API 导致难以替换、测试和扩展的问题。通过设计统一 ModelClient 与 Provider Adapter,将鉴权、请求格式、流式输出和工具调用能力封装起来,让 Agent Core 面向稳定接口开发。
学习目标
- 理解模型接入层在 Agent 架构中的职责边界。
- 掌握 ModelClient 与 Provider Adapter 的分层设计方式。
- 能够实现支持多模型切换的基础调用接口。
分离 Agent Core 与模型实现
Agent Core 关注任务规划、状态管理和工具编排,不应该知道当前使用的是哪一家模型服务。
如果核心代码直接调用某个 SDK,会产生以下问题:
- 更换模型需要修改大量业务代码。
- 不同模型的鉴权和参数处理散落在各处。
- 测试时难以替换真实模型。
模型接入层的目标是提供稳定抽象:上层只关心发送消息和获取结果,下层负责适配不同 Provider。

定义统一 ModelClient 接口
ModelClient 是 Agent 使用的统一入口,它隐藏不同模型服务之间的差异。
一个基础接口可以包含消息发送、流式响应和工具调用参数。
python
from abc import ABC, abstractmethod
class ModelClient(ABC):
@abstractmethod
def chat(self, messages: list[dict]) -> str:
"""发送消息并返回模型文本结果"""
pass
class AgentService:
def __init__(self, client: ModelClient):
self.client = client
def run(self, task: str) -> str:
return self.client.chat([
{"role": "user", "content": task}
])预期输出
text
AgentService 只依赖 ModelClient 接口,不依赖具体模型 SDK接口定义后,Agent Core 可以稳定运行,模型替换只影响实现层。
使用 Provider Adapter 适配模型差异
不同模型服务通常存在请求字段、鉴权方式和返回结构差异,因此需要 Adapter 转换。
例如某个 Provider 返回:
json
{
"response": "hello"
}另一个 Provider 可能返回:
json
{
"choices": [
{
"text": "hello"
}
]
}Adapter 负责把这些差异转换成统一结果。
python
class ProviderAdapter(ModelClient):
def __init__(self, api_client):
self.api_client = api_client
def chat(self, messages: list[dict]) -> str:
result = self.api_client.generate(messages)
return result["text"]预期结果
text
上层收到统一字符串结果,不感知 Provider 返回格式处理流式输出与工具调用
Agent 场景中,模型能力不仅是文本生成,还包括流式输出和工具调用。
因此接口设计时需要预留扩展能力:
- 普通对话返回完整结果。
- 流式模式返回增量内容。
- 工具调用返回结构化动作请求。
不要把所有能力强行塞进一个简单字符串接口,否则后续扩展会重新修改核心代码。
推荐将结果封装为统一对象:
python
from dataclasses import dataclass
@dataclass
class ModelResponse:
content: str
tool_calls: list[dict]
finished: bool预期输出
text
ModelResponse(content='...', tool_calls=[], finished=True)验证模型接入层设计
完成抽象后,可以通过模拟 Provider 测试 Agent Core,而无需调用真实模型服务。
python
class FakeModel(ModelClient):
def chat(self, messages: list[dict]) -> str:
return "test response"
agent = AgentService(FakeModel())
print(agent.run("hello"))预期输出
text
test response如果未来更换模型,只需要新增新的 Adapter,并保持 ModelClient 接口不变。
本课总结
- ModelClient 负责提供稳定调用协议,Provider Adapter 负责隐藏模型差异。
- Agent Core 不应直接依赖具体模型 SDK,否则会降低扩展能力。
- 流式输出和工具调用需要在接口设计阶段预留扩展空间。
下一课预告
下一节将继续完善 Agent 工程架构,设计工具调用与执行模块,让模型能够安全访问外部能力。
按自己的节奏,确认真正理解。