Agent 模型接入层设计：从 SDK、MCP 到记忆系统

很多 Agent 项目一开始都会把"模型接入"理解成一件很简单的事：封装一个 callLLM() 方法，把用户输入传给模型，再把模型输出返回给业务层。

这在 Demo 阶段足够，但在真正的 Agent 系统里远远不够。

因为 Agent 不是单轮问答系统。它需要规划、调用工具、读取外部数据、维护任务状态、在多个专家 Agent 之间切换，并在多步任务中持续修正自己的行动。OpenAI 官方对 Agents SDK 的描述也明确指出：Agent 是能够规划、调用工具、协作并保持足够状态以完成多步工作的应用。

因此，模型接入层的本质不是"调用模型"，而是：

在模型、工具、上下文、Prompt、记忆和任务运行时之间建立一层可控、可观测、可替换的工程边界。

一、为什么模型接入层不能只是 API Wrapper？#

最简单的模型调用可能长这样：

async function callModel(input: string) {
  return await openai.responses.create({
    model: "gpt-4.1",
    input,
  });
}

这类封装解决的是"怎么调用模型"，但没有解决 Agent 系统真正会遇到的问题。

例如：

• 这个任务应该用哪个模型？
• 这次调用是否允许使用工具？
• 工具返回结果如何进入下一轮上下文？
• 用户历史偏好是否应该注入？
• RAG 检索结果放在哪里？
• Prompt 模板如何版本化？
• 模型失败是否需要 fallback？
• 调用链路如何 trace？
• 成本和 token 如何统计？
• 多 Agent handoff 如何表达？

当系统从"聊天"走向"执行任务"时，模型接入层必须承担更多职责。

它至少要覆盖：

模型路由 / Prompt 构建 / 上下文组装 / 工具注册
工具调用结果注入 / 短期状态维护 / 长期记忆读取
运行时 trace / 失败重试 / 成本统计 / 安全边界

也就是说，模型接入层不是一个薄薄的 HTTP 客户端，而是 Agent 系统的认知边界层。

二、OpenAI Agents SDK 给出的工程抽象#

OpenAI Agents SDK 的价值不只是"更方便调用 OpenAI 模型"，而在于它把 Agent 工程中的几个核心概念显式化了：Agent、Tool、Handoff、Session、Guardrail、Trace。

其中最值得关注的是三个抽象。

1. Tool：让模型拥有行动能力#

OpenAI Agents SDK 的工具文档把工具定义为让 Agent 能够采取行动的能力，例如获取数据、运行代码、调用外部 API，甚至使用计算机。

这意味着模型接入层不仅要接收自然语言输入，还要知道：

有哪些工具可用？
每个工具的参数 schema 是什么？
哪些工具允许当前用户调用？
工具调用是否需要人工确认？
工具返回值如何被模型继续使用？

在架构上，工具不应该散落在业务代码里，而应该通过统一的 Tool Registry 暴露给模型：

Tool Registry
├── search_docs(query)
├── get_user_profile(userId)
├── create_issue(title, body)
├── run_code(language, source)
└── publish_article(articleId)

每个工具都应该有 name、description、input_schema、output_schema、permission_policy、timeout、retry_policy、audit_log。如果缺少这些信息，模型虽然"能调用工具"，但系统无法保证调用是否安全、是否可追踪、是否可恢复。

2. Handoff：让 Agent 协作成为一等概念#

在复杂任务中，一个 Agent 很难同时擅长所有事情。更合理的方式是将任务拆给不同专家 Agent：

Research Agent → Writer Agent → Reviewer Agent → Citation Checker

OpenAI Agents SDK 中的 handoff 机制将 handoff 建模为一种运行时能力，使一个 Agent 可以把任务交给另一个更合适的 Agent 处理。

这对模型接入层有重要启发：模型接入层不应该只管理"一个模型的一次调用"，而要管理一个任务在多个模型/Agent/工具之间的流转。

3. Tracing：让 Agent 的失败可解释#

Agent 系统的失败通常不是单点失败，而是一条链路失败。

如果没有 trace，开发者只能看到最后的错误输出，很难知道问题发生在哪一步。

OpenAI Agents SDK 内置 tracing，用于记录 Agent run 中的模型生成、工具调用、handoff、guardrails 和自定义事件，并支持开发和生产环境中的调试、可视化和监控。

这说明模型接入层必须内建可观测性。一次 Agent 调用至少应该产生 trace_id、run_id、model_call_span、tool_call_span、handoff_span、retrieval_span、memory_span、guardrail_span 和 final_output。

三、MCP：把模型接入扩展为上下文接入#

如果 OpenAI Agents SDK 更像一个 Agent 运行时框架，那么 MCP 更像一个连接协议。

MCP 官方文档将 Model Context Protocol 定义为一个开放协议，用于让 LLM 应用与外部数据源和工具无缝集成；协议使用 JSON-RPC 2.0 在 Host、Client、Server 之间通信。

它试图解决的是 Agent 工程中的一个结构性问题：每个模型应用都要为每个工具或数据源写一套自定义集成，导致连接关系呈 N × M 复杂度增长。

MCP 的目标是把这种关系标准化：

Before MCP:
Agent App A → GitHub Integration
Agent App A → Notion Integration
Agent App A → Database Integration
Agent App B → GitHub Integration
...

After MCP:
Agent App A → MCP Client → MCP Servers
Agent App B → MCP Client → MCP Servers

这使得"模型接入层"的范围进一步扩大：它不只是接模型，还要接上下文生态。

四、MCP 的三类核心能力：Prompts、Resources、Tools#

MCP Server 侧的能力可以概括为三类。MCP 规范文档将它们分别描述为：Prompts 是指导语言模型交互的预定义模板或指令；Resources 是提供给模型的结构化数据或内容；Tools 是允许模型执行动作或获取信息的可执行函数。

这三类能力的关键区别在于：控制权不同。

Prompts：用户控制
Resources：应用控制
Tools：模型控制

这个控制权划分非常重要，因为它直接决定了 Agent 系统的安全边界。

1. Prompts：用户控制的任务模板#

MCP Prompts Specification 说明，MCP 为服务器向客户端暴露 prompt templates 提供了标准方式；客户端可以发现可用 prompts、获取其内容，并传入参数进行定制。

这意味着 Prompt 不再只是代码里的字符串，而可以成为协议层的可发现能力：

prompts/list
prompts/get

例如，一个技术博客 Agent 可以暴露这些 prompts：

write_technical_article(topic, references, style)
review_mdx_article(article_path)
generate_seo_description(title, content)
summarize_paper(arxiv_url, depth)

这带来三个工程收益：Prompt 可以被发现、可以被参数化、可以被版本化。

2. Resources：应用控制的上下文材料#

MCP Resources 用于让服务器向客户端共享能提供上下文的数据，例如文件、数据库 schema 或应用特定信息；每个 resource 通过 URI 唯一标识。

Resources 的关键是"应用控制"。模型不一定能自己任意读取所有资源。应用可以决定哪些资源可见、哪些默认注入、哪些需要用户选择、哪些只用于检索不直接进入上下文。

一个合理的资源接入层应该支持：resource discovery、filtering、preview、permission、summarization 和 citation。

3. Tools：模型控制的外部动作#

MCP Tools 允许服务器暴露可被语言模型调用的工具，使模型能够与外部系统交互；每个工具都有名称和描述其 schema 的元数据。

Tools 是最危险也最有价值的能力。一旦工具开放给模型，模型就具备了改变系统状态的能力。因此工具层必须有严格边界：只读工具和写工具分离、高风险工具需要人工确认、工具参数必须 schema 化、工具调用必须记录审计日志。

这里有一个重要原则：能用 Resource 解决的问题，不要过早设计成 Tool；能由用户触发的模板，不要让模型自动调用。

五、MCP Prompts 对 Prompt 工程的重新定义#

传统 Prompt 工程往往是散落的：某个页面里写一个 prompt、某个接口里拼一个 prompt、某个任务里复制一份 prompt。

问题是：无法发现、无法复用、无法版本化、无法参数补全、无法在多个客户端之间共享。

MCP Prompts 把 Prompt 模板变成协议能力。规范明确指出，Prompts 设计为用户控制，通常通过用户界面里的显式命令触发，例如 slash commands。

这给 Agent 产品设计带来一个很好的模式：

用户不是直接输入一大段自然语言
而是选择一个结构化任务模板
再填写参数
最后由 Agent 执行

例如：

/write-article
参数：
- topic: Agent 模型接入层设计
- depth: 深度技术分析
- references: OpenAI Agents SDK, MCP, MemGPT
- output: MDX

这种方式比"请帮我写一篇文章"稳定得多。

六、MemGPT：模型接入层必须面对上下文窗口的物理限制#

MCP 解决的是"模型如何连接外部上下文和工具"，但还有一个更底层的问题：LLM 的上下文窗口是有限的。

很多开发者会误以为：只要上下文窗口足够大，记忆问题就消失了。MemGPT 论文反驳了这个直觉。论文指出，LLM 受到有限上下文窗口约束，这限制了它们在长期对话和长文档分析中的能力；MemGPT 提出 virtual context management，借鉴传统操作系统的层级内存系统，通过在不同 memory tiers 之间移动数据，让有限上下文窗口呈现出更大的有效上下文能力。

这对 Agent 模型接入层非常关键。因为模型接入层每次调用模型时，都必须决定：

哪些内容放进当前上下文？
哪些内容只保存在长期记忆中？
哪些历史应该摘要？
哪些信息应该被淘汰？
哪些信息需要重新召回？

这和操作系统内存管理非常像：

CPU register / cache  ≈ 当前 prompt 中的关键上下文
RAM                  ≈ 当前任务状态与短期记忆
Disk                 ≈ 长期记忆、文档库、历史记录
Page fault           ≈ 模型发现缺信息，需要检索或回忆
Eviction             ≈ 从上下文中移除低价值信息

如果模型接入层没有上下文管理策略，Agent 很快会遇到：上下文越来越长、关键事实被淹没、token 成本不可控、模型注意力分散、旧信息与新信息冲突、长期偏好无法稳定保留。

七、从四个资料抽象出模型接入层的职责#

结合 OpenAI Agents SDK、MCP、MCP Prompts 和 MemGPT，可以得到一个更完整的模型接入层职责模型：

Model Access Layer
├── Model Gateway
│   ├── model routing
│   ├── retry / fallback
│   ├── timeout
│   └── cost tracking
│
├── Prompt Layer
│   ├── prompt registry
│   ├── MCP prompts
│   ├── template arguments
│   └── versioning
│
├── Context Layer
│   ├── resources
│   ├── RAG context
│   ├── task state
│   └── user profile
│
├── Memory Layer
│   ├── short-term memory
│   ├── long-term memory
│   ├── summarization
│   └── eviction policy
│
├── Tool Layer
│   ├── tool registry
│   ├── tool schema
│   ├── permissions
│   ├── execution
│   └── audit logs
│
├── Agent Runtime
│   ├── agent loop
│   ├── handoff
│   ├── guardrails
│   └── task lifecycle
│
└── Observability
    ├── traces
    ├── metrics
    ├── logs
    ├── token usage
    └── failure analysis

这才是一个真正面向 Agent 的模型接入层。

八、一个可落地的模型接入层设计#

1. Model Gateway#

模型网关负责屏蔽不同模型供应商差异：

interface ModelGateway {
  run(input: ModelRequest): Promise<ModelResponse>;
}

interface ModelRequest {
  taskType: "chat" | "tool_use" | "reasoning" | "writing" | "review";
  messages: Message[];
  tools?: ToolDefinition[];
  temperature?: number;
  maxTokens?: number;
  metadata?: Record<string, string>;
}

核心职责：统一调用接口、模型路由、失败重试、fallback、token 统计、成本统计、日志记录。

2. Prompt Registry#

Prompt Registry 负责管理所有 Prompt 模板：

interface PromptTemplate {
  name: string;
  version: string;
  description: string;
  arguments: PromptArgument[];
  render(args: Record<string, unknown>): Message[];
}

如果接入 MCP Prompts，则可以将本地 prompt registry 扩展为支持 prompts/list 和 prompts/get，让 Prompt 来自多个 MCP Server。

3. Context Builder#

Context Builder 负责为每次模型调用选择上下文：

interface ContextBuilder {
  build(request: AgentTask): Promise<ContextBundle>;
}

interface ContextBundle {
  taskState: TaskState;
  resources: Resource[];
  memories: MemoryItem[];
  retrievedDocs: RetrievedDoc[];
  constraints: Constraint[];
}

它需要决定哪些资源直接进入 prompt、哪些只作为引用、哪些记忆需要摘要、哪些检索结果需要重排、上下文是否超出预算。必须建立 token budget 意识。

4. Memory Manager#

Memory Manager 可以借鉴 MemGPT 的思路，区分 memory tiers：

Working Memory：当前任务必须立即可见的信息。
Session Memory：当前会话中可复用的信息。
Long-term Memory：跨会话保存的用户偏好、项目事实、历史经验。
Archival Memory：低频但可检索的历史记录、文档、日志。

每次模型调用前，Memory Manager 做三件事：retrieve（召回相关记忆）、compress（压缩冗余历史）、evict（从上下文中移除低价值信息）。

5. Tool Runtime#

Tool Runtime 负责执行工具，不应该让模型直接接触底层系统：

interface ToolRuntime {
  listTools(context: UserContext): Promise<ToolDefinition[]>;
  execute(call: ToolCall, context: ExecutionContext): Promise<ToolResult>;
}

必须包含：权限校验、参数校验、执行超时、错误包装、审计日志、人工确认、结果结构化。高风险工具必须加入人工确认：delete_file、send_email、publish_article、deploy_production、charge_payment。

6. Trace Runtime#

每一次 Agent Run 都应该有 trace：

trace_id
├── prompt_render_span
├── memory_retrieve_span
├── model_call_span
├── tool_call_span
├── handoff_span
├── guardrail_span
└── final_output_span

九、一个典型任务如何流经模型接入层？#

假设用户输入：

请根据 ReAct、MCP 和 MemGPT，写一篇关于 Agent 模型接入层设计的技术文章。

一个合理的执行过程是：

1. Orchestrator 创建 AgentTask
2. Prompt Registry 选择 write_technical_article prompt
3. Context Builder 读取用户给定主题
4. Resources 加载资料清单与引用链接
5. Memory Manager 召回用户偏好：文章要严谨、逻辑缜密
6. Tool Runtime 暴露 web_search、paper_fetch、citation_check 工具
7. Model Gateway 调用模型生成提纲
8. Agent 判断资料不足，调用搜索工具
9. Context Builder 注入新检索结果
10. 模型生成正文
11. Guardrail 检查引用与事实
12. 输出 MDX
13. Trace 记录全过程

如果没有模型接入层，这些逻辑会散落在业务代码中；有了模型接入层，它们可以成为可复用的运行时能力。

十、设计模型接入层时最容易犯的错误#

1. 把 Prompt 写死在业务代码里#

难复用、难版本化、难测试、难替换。应该建立 Prompt Registry、支持 MCP Prompts 和 Prompt versioning。

2. 把所有上下文都塞进 prompt#

导致 token 成本高、模型注意力分散、旧信息污染新任务。应该使用 Context Builder、Memory tiers、Retrieval + compression 和 Token budget。

3. 工具没有权限边界#

模型误调用危险工具、用户越权操作、敏感数据泄露。应该建立 Tool permission、Human approval、Audit log 和 Sandbox。

4. 没有 trace#

失败不可解释、成本不可分析、工具调用质量不可评估。每次 Agent Run 必须有 trace_id，每次模型调用和工具调用必须有 span。

5. 忽略长期记忆治理#

记忆污染、隐私风险、过期信息被误用。应该建立记忆分类、记忆过期、用户可见、用户可删除、引用可追溯机制。

十一、一个推荐的实现路线#

第一阶段：统一模型调用#

所有模型调用通过 Model Gateway，记录 token、latency、cost、error，支持 retry 和 fallback。先不要急着做复杂 Agent。

第二阶段：Prompt Registry#

把 prompt 从业务代码里抽出来，支持模板参数、版本号、测试样例。这一步完成后，Prompt 才能被管理和评估。

第三阶段：工具与上下文接入#

建立 Tool Registry、Resource Loader、Context Builder 和权限控制。可以开始参考 MCP 的 Prompts、Resources、Tools 三层模型。

第四阶段：记忆与运行时#

引入短期记忆、长期记忆、摘要压缩、任务状态、trace、handoff 和 guardrails。这一步才真正进入 Agent Runtime。

十二、结论：模型接入层是 Agent 系统的操作系统边界#

如果把大模型看成"推理核心"，那么模型接入层就像操作系统边界：它负责资源调度、上下文管理、工具权限、状态维护、错误处理和观测。

OpenAI Agents SDK 提供了 Agent 运行时的工程抽象；MCP 提供了模型应用连接外部上下文、工具和 prompt 的开放协议；MCP Prompts 让 Prompt 模板从代码字符串变成可发现、可参数化的协议能力；MemGPT 则提醒我们，LLM 上下文窗口有限，必须像操作系统管理内存一样管理上下文和记忆。

所以，Agent 模型接入层的终极目标不是"让业务代码能调用模型"，而是：

让模型在可控上下文中使用可控工具，基于可管理记忆完成可观测任务。

这是 Agent 从 Demo 走向生产的第一道工程边界。

参考资料#