沙箱下载链接

将沙箱中的单个文件作为无需 LangSmith 凭据的链接分享。

下载链接将一个沙箱文件交给无法携带 LangSmith 凭据的对象：浏览器标签页、电子邮件中的 <a href>、webhook 消费者，或获取你提供的 URL 的第三方服务。

链接自带 token。使用 SDK 的 read() 读取文件需要在每个请求中提供工作区 API 密钥；而下载链接除了 URL 本身之外不需要任何其他内容。

快速开始

from langsmith.sandbox import SandboxClient

client = SandboxClient()

with client.sandbox() as sb:
    sb.run("python -c \"open('/app/report.csv','w').write('a,b\\n1,2\\n')\"")

    link = sb.generate_download_url("/app/report.csv")
    print(link.download_url)

然后任何人都可以在没有凭据的情况下获取它：

curl -LO "<download_url>"

链接固定到的内容

token 编码了沙箱、租户、确切文件路径和响应标头，因此无法编辑链接使其指向其他文件或其他沙箱。每个链接只提供一个路径。

链接固定到该路径，而不是文件的快照。生成链接时不会捕获或复制文件本身。

WARNING

为文件生成链接后，请勿修改该文件。之后对该路径的写入可能会也可能不会反映在链接提供的内容中，因此请在该链接的整个生命周期内将该文件视为不可变。内容发生变化时，请写入新文件并为其生成新链接。

链接由沙箱服务域提供，位于沙箱自己的主机上，绝不会来自 LangSmith API 主机。因此，下载的内容与你的 LangSmith 会话隔离。

创建链接

Python

# Never expires
link = sb.generate_download_url("/app/report.csv")

# Expires in an hour
link = sb.generate_download_url("/app/report.csv", expires_in_seconds=3600)

# Rendered in the browser instead of downloaded
link = sb.generate_download_url(
    "/app/page.html",
    content_type="text/html",
    content_disposition="inline",
)

print(link.download_url)
print(link.expires_at)  # None when the link never expires

TypeScript

// Never expires
let link = await sandbox.generateDownloadURL("/app/report.csv");

// Expires in an hour
link = await sandbox.generateDownloadURL("/app/report.csv", {
  expiresInSeconds: 3600,
});

// Rendered in the browser instead of downloaded
link = await sandbox.generateDownloadURL("/app/page.html", {
  contentType: "text/html",
  contentDisposition: "inline",
});

console.log(link.download_url);
console.log(link.expires_at); // null when the link never expires

在客户端而不是沙箱实例上调用它，以按沙箱名称生成链接：

Python

link = client.generate_download_url("my-sandbox", "/app/report.csv")

TypeScript

const link = await client.generateDownloadURL("my-sandbox", "/app/report.csv");

选项

选项	默认值	效果
expires_in_seconds	省略，因此链接永不过期	链接有效期（秒）
content_type	根据文件扩展名推断	链接响应使用的 Content-Type
content_disposition	attachment	attachment 下载文件；inline 在浏览器中呈现

从 CLI 创建链接

langsmith sandbox generate-download-url my-sandbox --path /app/report.csv

langsmith sandbox generate-download-url my-sandbox \
  --path /app/page.html \
  --expires-in-seconds 3600 \
  --content-disposition inline

通过 REST API 创建链接

curl -X POST \
  "$LANGSMITH_ENDPOINT/api/v2/sandboxes/boxes/{sandbox_name}/download-url" \
  -H "x-api-key: $LANGSMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "/app/report.csv", "expires_in_seconds": 3600}'

响应：

{
  "download_url": "https://{sandbox-id}--dl.smithbox.dev/ey...",
  "token": "ey...",
  "expires_at": "2026-04-08T15:30:00Z"
}

当省略 expires_in_seconds 时，expires_at 为 null。

生成链接需要 sandboxes:exec 权限，与带凭据的下载所需的访问权限相同。请参阅沙箱权限。

获取链接

支持 GET 和 HEAD，以及 Range（用于可恢复和部分下载）、If-Range 和 If-None-Match。不需要也不接受任何标头、查询字符串或正文。

获取链接会唤醒已停止的沙箱，因此空闲停止后的第一个请求耗时与启动相同。生成链接时，沙箱不需要正在运行。

安全注意事项

WARNING

下载链接是嵌入 URL 中的 bearer 凭据。任何获得它的人都可以在链接过期前读取那一个文件。请像对待密码一样对待链接：通过你信任的渠道发送，并对任何敏感内容优先使用较短的 expires_in_seconds。

• 链接无法撤销。 已生成的链接在过期前始终保持有效，即使创建它的 API 密钥被删除或失去 sandboxes:exec 权限。需要时请设置过期时间。
• 链接会随沙箱一起失效。 删除沙箱会使指向它的所有链接失效。
• 文件不得发生变化。 链接固定到路径，因此生成链接后对该路径的写入可能会也可能不会反映在链接提供的内容中。
• 访客标头会被丢弃。 响应会根据内容、范围和验证器标头的允许列表重建。沙箱内代码设置的 cookie 或其他标头永远不会被转发。
• 呈现的内容处于沙箱中。 每个响应都带有 X-Content-Type-Options: nosniff 和 Content-Security-Policy: sandbox，因此以 content_disposition=inline 提供的文件会在没有任何能力且无法访问你的 LangSmith 会话的情况下呈现。

下载链接与其他文件访问方式

	下载链接	read()	服务 URL
所需凭据	无	工作区 API 密钥	服务 token 或浏览器 cookie
范围	一个文件，一个路径	任意文件	沙箱中的任意 HTTP 服务
沙箱必须正在运行	否（获取时会唤醒它）	否（按需唤醒）	否（获取时会唤醒它）
可共享	是	否	是
过期前可撤销	否	是（轮换密钥）	否

使用下载链接将一个文件交给外部消费者。使用 read() 将文件字节拉取到你自己的代码中。使用服务 URL 访问沙箱内运行的 HTTP 服务器。

故障排查

错误	原因	修复
生成时返回 501	此部署未配置下载链接	自托管部署需要配置沙箱服务域；请参阅沙箱服务 URL
获取时返回 403	链接已过期、被篡改或在错误的主机上访问	重新生成链接；原样复制 URL
获取时返回 404	该路径下文件已不存在	链接固定到路径，而不是文件内容。为存在的路径生成链接
浏览器下载而不是呈现	默认处置方式为 attachment	使用 content_disposition="inline" 和显式的 content_type 生成
内容过时或不完整	链接生成后文件被写入或替换	不要修改链接指向的文件。写入新文件并生成新链接

---