Vercel 推出了其 AI SDK 的第 7 版本，引入了作用域工具上下文 (scoped tool context) 功能，强制要求 AI agent 中的每个工具只能接收其明确声明的密钥 (secrets)。通过限制暴露范围，开发者可以防止第三方工具意外获取其环境中存储的所有凭据。
为什么这一变化至关重要
AI agent 通常需要整合多个外部服务——订单查询、工单创建、支付处理——每个服务都需要自己的 API 密钥或 URL。常见的做法是直接将整个 process.env 对象传递给每个工具：
execute(input, { context: process.env })
这种模式会造成隐式权限扩张 (implicit privilege expansion)：添加一个新工具会立即授予其访问所有现有密钥的权限（包括数据库密码或支付令牌），而无需任何代码审查提醒。风险在于，一个被攻破或存在 Bug 的工具可能会突然泄露那些它根本不需要的凭据。
作用域工具上下文的工作原理
在 SDK 7 中，工具需要声明一个上下文模式 (context schema)——即使用 Zod 定义的、该工具所需的精确字段。当 agent 调用工具时，调用方会提供一个仅包含这些已声明字段的 toolsContext 对象。SDK 会在执行前验证其结构，任何缺失或多余的键都会导致错误。
一个简单的演示展示了两个需求不同的工具：
- lookupOrder – 需要
baseUrl来调用内部订单服务。 - createTicket – 需要
supportToken来创建支持工单。
每个工具都导出了一个列出其唯一必需键的 contextSchema。当 agent 运行时，它会传递：
{
lookupOrder: { baseUrl: "https://orders.internal" },
createTicket: { supportToken: "s3cr3t-token" }
}
只有 lookupOrder 能看到 baseUrl；createTicket 永远无法触及它，反之亦然。SDK 在运行时强制执行这一边界，将隐藏的依赖关系转变为可供审查人员审计的显式能力列表。
安全优势
- 限制数据暴露 – 凭据仅保留在需要的地方。
- 验证上下文 – 字段不匹配或缺失时会中止执行。
- 使能力显式化 – 审查人员可以清楚地看到每个工具可以访问哪些内容。
- 减小爆炸半径 (blast radius) – 如果一个工具被攻破，攻击者只能获得该工具被允许访问的密钥。
该功能并不能取代传统的沙箱机制 (sandboxing)。开发者仍需采用日志脱敏 (log redaction)、网络出口控制 (network egress controls) 以及定期的令牌轮换 (token rotation)。作用域上下文是一个边界；它并不能完全封闭房间。
开发者需要进行哪些调整
- 为每个工具定义模式 (schema) – 使用 SDK 自带的 Zod 库。
- 传递精简的
toolsContext– 避免使用全能型的process.env。 - 审查现有 agent – 识别并移除工具调用中可以剔除的密钥。
- 添加自动化测试 – 确保在注入额外数据时，上下文验证会失败。
快速入门示例如下：
mkdir scoped-tools && cd scoped-tools
npm init -y
npm install ai zod
npm install -D typescript tsx @types/node
创建 demo.ts，声明每个工具的 contextSchema，然后使用 tsx demo.ts 运行。如果你尝试给工具提供它未请求的密钥，SDK 将会抛出错误。
反方观点
一些团队可能会认为额外的模式定义增加了样板代码 (boilerplate) 并减慢了原型设计速度。虽然这确实是事实，但成本很低——每个工具只需增加几行代码——而且随着集成服务数量的增加，安全收益也会随之增长。在处理支付数据或个人信息的环境中，这种权衡是不容忽视的。
后续关注点
- 采用率指标 – 早期采用者报告的密钥泄露事件正在减少。
- 社区工具 – 可以从配置文件自动生成上下文模式的插件。
- 未来的 SDK 版本 – 有迹象表明 Vercel 可能会扩展作用域上下文，以包含网络权限和速率限制 (rate-limit) 限制。
如果你已经在利用 Vercel 的 SDK 构建 AI agent，第一步就是审计当前的 process.env 使用情况。识别出可以从所有工具调用中剔除的单个值，并将全能型模式替换为作用域化的 toolsContext。这样做可以在不牺牲 AI agent 强大灵活性的前提下，实现更严密的安全性。