文档定价博客开源

AI SDK + MCP：生产级智能体系统的实战集成指南

2026年4月7日Lin Ivan

核心要点

AI SDK + MCP 集成不只是“接上就能调”。真正困难的是能力边界、传输方式、重试、认证和可观测性。
最安全的默认做法，是窄 discovery、显式 tool allowlist，以及针对每次请求的硬性运行预算。
MCP 改善了 discovery 和 invocation 边界，但你的应用仍然需要决定：每个 workflow 到底该看到哪些工具。
生产级智能体系统必须在第一个事故发生前，就把 timeout、fallback 和 logging 设计清楚。
当同一个 workflow 既需要受治理的上下文，又需要 MCP 提供的工具时，puppyone 会处在一个很有价值的位置上。

为什么 demo 看起来很轻松，生产环境却难得多

理想化 demo 的路径通常都很简单：

把 AI SDK 连到一个 MCP server
暴露几个工具
让模型自己调用

这适合做第一个 demo，但还不是生产环境的集成方案。

一旦进到生产，增加的并不是代码行数，而是你必须自己承担的判断：

这个智能体到底能看到哪些工具？
在这个环境里，什么 transport 才可接受？
凭证怎么鉴权，怎么轮换？
MCP server 变慢时怎么办？
工具调用失败后的 fallback 是什么？
哪些调用需要人工审批？
出了问题之后，如何把这次运行解释清楚？

最短但足够真实的生产架构

user request
  -> app 内的 agent runtime
  -> workflow-specific tool policy
  -> MCP client
  -> 一个或多个 MCP server
  -> 外部系统或 governed context
  -> 结果组装
  -> logs、approvals、traces

很多团队最容易漏掉的一层，就是 tool policy。

Discovery 是协议能力，Exposure 是产品决策。

五个真正决定成败的集成判断

1. Discovery 不是 permission

AI SDK 能列出 20 个工具，并不意味着当前 workflow 就应该看到这 20 个工具。

更合理的做法是：把 discovery 视为能力上限，把 runtime allowlist 视为真正的执行边界。

2. Transport 本质上是可靠性选择

当前 AI SDK 文档建议生产环境优先使用 HTTP transport，而 stdio 更适合本地 server。它听起来像协议细节，但实际上会影响防火墙、重试、代理和运维责任归属。

最稳妥的规则通常很朴素：

选择你的环境最容易稳定运维的 transport
明确限制 retry
明确 timeout 行为

3. Tool description 会直接影响模型行为

这是“集成”开始变成“产品设计”的地方。

如果工具描述很模糊，模型的调用行为也会变得模糊。如果两个工具能力重叠，模型会把 token 浪费在“选哪个”上，而不是解决任务。

好的工具描述应该像一个谨慎的操作员写出来的：

它做什么
它不做什么
什么时候该调用
输入要求是什么
失败会长什么样

4. 每次 tool call 都应该有预算

模型不应该被放任去：

两个工具就能完成的事，却调用十个
无限重试
把巨大 payload 拉进 prompt
随意混用只读工具和写入工具

预算必须存在于 runtime 里，而不是只存在于系统提示词的愿望里。

5. Logs 本身就是 feature 的一部分

如果某次工具调用导致糟糕回答或错误动作，你需要的绝不只是“模型判断错了”。

至少应该有：

request ID
本次运行暴露了哪些工具
最终实际调用了哪个工具
发送了什么参数
延迟和失败信息
必要时还要有审批状态

一张能挡掉很多坑的表

选择	团队为什么喜欢它	会在哪里出问题
把发现到的工具全部加载进来	原型速度快，也能自动跟 server 同步	对生产来说暴露面太宽，控制力太弱
显式定义 schema 和 tool set	类型更稳、审查更容易、控制更强	维护成本更高

更实用的规则通常是：