认证代理如何保护 LangSmith 智能体沙盒的网络访问

如果你曾在大企业工作过，很可能见过标准的公司笔记本电脑配置：终端防护、浏览器过滤、设备管理、网络控制、证书存储、密钥扫描器……一长串工具，其职责是阻止本应值得信赖的员工意外泄露凭证、安装恶意软件包或访问错误页面。这些工具之所以存在，是因为开发者拥有广泛权限。他们运行代码、安装依赖、在系统间复制数据，还会认证到内部和外部服务。许多企业安全机制正是围绕让这个强大、开放的环境更安全而构建的。

智能体改变了这个问题的规模和形态。你不再只是给一位开发者一台笔记本。你可能正在生成数千、甚至数百万个“不受信任的开发者”，它们能替你编写代码、运行命令、安装软件包以及发起网络请求。对于人类开发者，环境通常需要默认保持开放——开发者需要探索、调试、安装工具，并在工作变化时访问新的服务。但对于智能体，默认设置可以不同。如果任务是已知的，网络范围就可以缩小。如果智能体只需要 GitHub 和一个 LLM 提供商，它就不应该能够与互联网上的任意随机主机通信。如果需要凭证，那么该凭证根本就不应该存在于运行时内部。这就是沙盒网络成为智能体工具链一等公民的用武之地。

沙盒认证代理介绍

LangSmith 沙盒为智能体提供隔离环境，用于运行代码和操作文件系统，而不会影响你的主要基础设施。但隔离只是故事的一部分。智能体仍然需要调用外部 API，例如模型提供商、GitHub、软件包注册中心、内部服务、数据 API 等等。沙盒认证代理是一种控制智能体生成行为与外界之间边界的方式。它不是将 API 密钥作为环境变量或文件放入沙盒，而是位于出站网络路径上，控制沙盒代码如何与外部服务交互。它可以强制执行策略，规定允许哪些目标、应用何种认证，以及请求在离开沙盒之前如何被整形。沙盒代码向外部 API 发出正常请求，而凭证和访问规则则在沙盒外部的网络层处理。

采用这种模型后，三件事变得容易得多：

• 凭证留在运行时之外。智能体可以使用 API，但无法读取 API 密钥，从而减少了提示注入、恶意依赖、意外日志记录和模型错误造成的损害。
• 网络访问变得明确。如果智能体只应与 OpenAI、Anthropic、GitHub 或内部 API 通信，这应被编码为基础架构策略，而不是留给智能体判断。
• 团队获得更清晰的关注点分离：智能体专注于任务，沙盒提供隔离，代理处理网络授权和凭证注入，而应用或认证服务处理用户范围的访问和令牌刷新。

这种分离很重要，因为智能体是不受信任的，且你无法预先检查它们会走的所有分支。更安全的模式是给它们受限环境，其中可能的行为受基础架构约束，从而认证代理将凭证完全排除在沙盒之外。

工作原理

在较高层面上，认证代理是沙盒出站流量的受控中间人，流程如下：

• 智能体或沙盒代码发出出站请求。
• 请求经过认证代理。
• 认证代理检查针对该目标配置的策略。
• 代理可以阻止请求、允许请求或添加请求头。
• 请求继续前往目标，而不在运行时中暴露凭证。

一个简单的规则可能是：当沙盒调用 api.openai.com 时，注入一个 Authorization 请求头，其值来自 LangSmith 工作区密钥。另一个规则可能是：当沙盒调用 api.github.com 上的 /repos/* 或 /user 时，注入一个 GitHub 令牌。由于我们控制了沙盒的网络，这一切完全透明。这并不是通过期望每种语言、包管理器、SDK 或子进程都尊重 HTTP_PROXY 来实现的——并非所有运行时行为都相同，而且智能体经常执行你未编写的任意代码路径。

无需将凭证交给智能体即可完成认证

代理支持许多不同的策略配置。其中一种强大的能力是向匹配特定特征的请求注入请求头。请求头可以配置为不同类型：

• workspace_secret：引用存储在 LangSmith 工作区设置中的密钥
• plaintext：按原样存储和返回，适用于非敏感请求头
• opaque：只写，加密存储，并且 API 从不返回

例如，在 OpenAI 规则的示例中，我们可以注入：

{
  "name": "Authorization",
  "type": "workspace_secret",
  "value": "Bearer {OPENAI_API_KEY}"
}

沙盒代码不需要知道 API 密钥。它不需要 .env 文件。它不需要将密钥挂载到文件系统中。它只需调用 API，当目标与配置的规则匹配时，代理就会添加正确的请求头。

这对智能体系统来说是更好的默认设置。人类开发者可能需要直接访问凭证来调试新的集成，但智能体通常不需要。智能体需要的是凭证的效果——调用特定 API 的能力——而不是凭证本身。随着智能体运行数量的增长，这种区别变得越来越重要。单个沙盒中泄露密钥已经很糟糕，但对于一个沙盒集群，将凭证直接放入运行时是一个重大风险。每个工具调用、包安装、日志行和文件写入都是凭证暴露的可能途径。请求头注入将凭证移出了该爆炸半径。

锁定网络

凭证只是网络问题的一半；智能体还需要出站策略，因为它们可以安装依赖、获取脚本、调用 API 并遵循不受信任内容的指令。如果每个沙盒都能自由访问互联网，那么一个被攻破或被混淆的智能体就可能到达它本不该去的地方。注入请求头的同一个代理边界也可以成为团队定义哪些目标是预期目标的地方，例如：

• 允许模型提供商 API，阻止其他一切
• 允许智能体需要的 GitHub API 路径，但不允许随意的 GitHub 附属域名
• 允许包注册中心，但仅限于内部镜像
• 阻止已知的恶意或不受信任的包注册中心
• 防止意外调用未经授权的第三方服务

这对于包管理尤其重要。如果编码智能体可以运行 pip install、npm install 或 curl | bash，它就可以获取并执行代码。安全问题不仅在于沙盒能否隔离执行，还在于你是否能控制这些代码来自哪里以及它能将数据发送到哪里。

用于真实生产认证的动态凭据

在与 LangSmith Fleet 集成沙盒时，我们意识到对于高级用例，静态配置可能不够用。Fleet 智能体可能需要委派访问和 OAuth 令牌刷新，同时仍将实际的凭证处理保留在智能体运行时之外。其他高级用例包括：

• 短期 OAuth 访问令牌
• 按用户范围的令牌
• 由内部认证服务创建的凭据
• 需要根据目标或当前用户上下文刷新的令牌

针对这些情况，认证代理支持带回调的动态凭证。你不在静态规则中放入所有凭证材料，而是在 proxy_config 下配置一个回调。当沙盒向匹配的主机发出请求且代理没有缓存的凭证时，代理会使用目标主机和端口调用你的回调端点。你的端点返回要注入的请求头，代理将结果缓存一段配置的 TTL。契约很简单：回调返回一个 JSON 对象，如下所示：

{
  "headers": {
    "Authorization": "Bearer <token>",
    "X-Org-Id": "..."
  }
}

代理将这些请求头注入出站请求。如果回调失败、返回格式错误的 JSON 或以非 2xx 状态码响应，代理会安全失败并拒绝沙盒请求，而不是在缺少凭证的情况下发送请求。这种模式让沙盒网络层参与认证流程，而无需向沙盒暴露刷新令牌或长期有效的凭证。

接下来可以实现什么

一旦你控制了沙盒网络路径，代理就可以不仅仅是一个凭证注入器，还有几个自然的扩展方向：

• DNS 重映射：团队可能希望将对公共包注册中心的请求解析到内部的 Artifactory 或包镜像。你可能希望将 LLM API 请求指向内部网关。智能体仍然运行正常的安装命令，但网络层将这些请求指向已批准的基础设施。
• 网络日志记录：如果智能体在长时间范围内执行有意义的工作，团队将希望知道它们调用了哪些服务、获取了哪些包以及尝试访问了哪些域名。网络日志成为智能体行为审计追踪的一部分。
• 请求转换：由于代理能看到出站请求，它最终可以成为应用确定性转换的地方，例如编辑 PII、添加组织元数据、强制执行请求形状或阻止违反策略的负载。

更广泛的观点是，智能体基础设施需要存在于运行时之外且不受智能体指令和决策影响的控制平面。

智能体出站的新默认设置

智能体需要凭证和网络访问才能完成有用工作，但这些能力不应要求将长期有效的密钥或无限制的互联网访问放入运行时内。认证代理通过以下方式为沙盒智能体提供了更安全的默认设置：将凭证保留在环境之外、将出站流量路由经过受控层、以及跨语言、SDK、包管理器和 CLI 一致地应用策略。结果是一种沙盒模型，它给予智能体所需系统的访问权限，同时将凭证和网络策略置于平台控制之下。

尝试 LangSmith 沙盒：https://www.langchain.com/langsmith/sandboxes
阅读文档：https://docs.langchain.com/langsmith/sandboxes