沙箱服务 URL

通过经过身份验证的 URL，从浏览器或以编程方式访问沙箱内运行的 HTTP 服务。

服务 URL 让你可以访问沙箱内运行的 HTTP 服务（REST API、Streamlit 应用、Jupyter notebook、API 文档），无需隧道、端口转发或 CLI 工具。每个沙箱 + 端口组合都有自己的 URL，你可以在浏览器中打开、从代码中调用，或与队友分享。

快速开始

在沙箱内启动 HTTP 服务器，然后获取用于访问它的 URL：

from langsmith.sandbox import SandboxClient

client = SandboxClient()

with client.sandbox() as sb:
    handle = sb.run("python -m http.server 8000", timeout=0, wait=False)

    svc = sb.service(port=8000)

    # Open in a browser
    print(svc.browser_url)

    # Or make requests programmatically
    resp = svc.get("/")
    print(resp.status_code)

    handle.kill()

使用场景

场景	方法
预览 Web 应用（Streamlit、Jupyter 等）	sb.service(port=<PORT>)，然后打开 browser_url
从代码或 CI 调用 API	svc.get(...) / svc.post(...)，或使用服务 token 执行 curl
与队友分享实时演示	在 UI 中点击 Share Link 并发送 URL

从 UI 打开服务

1. 打开沙箱详情页面。
2. 找到 Open service 小组件。
3. 输入端口号（例如 3000）。
4. 点击 Open 在新标签页中启动，或点击 Share Link 复制可发送给队友的 URL。

任何拥有链接的人都可以访问该服务，即使没有 LangSmith 账户。token 过期后，请从 UI 生成新链接。

从 SDK 打开服务

获取服务 URL

在沙箱实例或客户端上直接调用 service()：

svc = sb.service(port=3000)

# Or from the client, by sandbox name
svc = client.service("my-sandbox", port=3000)

# Customize token lifetime (default: 10 minutes, max: 24 hours)
svc = sb.service(port=3000, expires_in_seconds=3600)

NOTE

在请求服务 URL 之前，服务必须正在运行并监听指定端口。该 URL 只负责路由流量，不会为你启动服务。

发起请求

返回的 ServiceURL 对象内置 HTTP 辅助函数，会为你注入认证标头。

token 是短期的（默认 10 分钟，最长 24 小时），并且没有服务器端刷新机制。token 过期后，请再次调用 sb.service(port=...) 请求新 token。

svc = sb.service(port=8000)

resp = svc.get("/api/items")
resp = svc.post("/api/items", json={"name": "widget"})
resp = svc.put("/api/items/1", json={"name": "updated"})
resp = svc.patch("/api/items/1", json={"status": "active"})
resp = svc.delete("/api/items/1")

使用你自己的 HTTP 客户端

如果你更喜欢其他 HTTP 客户端，请使用原始 URL 和 token：

import httpx

svc = sb.service(port=8000)

resp = httpx.get(
    svc.service_url + "api/items",
    headers={"X-Langsmith-Sandbox-Service-Token": svc.token},
)

在浏览器中打开

使用 browser_url 在浏览器中打开服务。它会自动设置身份验证 cookie，因此后续所有页面加载、图像和 API 调用都会经过身份验证，无需在 URL 中携带 token。

svc = sb.service(port=8000)
print(svc.browser_url)

你可以与队友分享此 URL。访问它不需要登录 LangSmith。

通过 REST API 生成 URL

curl -X POST \
  "$LANGSMITH_ENDPOINT/api/v2/sandboxes/boxes/{sandbox_name}/service-url" \
  -H "x-api-key: $LANGSMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"port": 3000, "expires_in_seconds": 3600}'

响应：

{
  "browser_url": "https://{sandbox-id}--3000.smithbox.dev/_svc/auth?token=ey...",
  "service_url": "https://{sandbox-id}--3000.smithbox.dev/",
  "token": "ey...",
  "expires_at": "2026-04-08T15:30:00Z"
}

示例：提供 FastAPI 应用

from langsmith.sandbox import SandboxClient

client = SandboxClient()

with client.sandbox() as sb:
    sb.write("/app/main.py", """
from fastapi import FastAPI

app = FastAPI()
items = []

@app.get("/items")
def list_items():
    return items

@app.post("/items")
def create_item(item: dict):
    items.append(item)
    return item
""")

    sb.run("pip install fastapi uvicorn", timeout=120)
    handle = sb.run(
        "uvicorn main:app --host 0.0.0.0 --port 8000",
        timeout=0,
        wait=False,
        env={"PYTHONPATH": "/app"},
    )

    import time
    time.sleep(3)

    svc = sb.service(port=8000)

    svc.post("/items", json={"name": "widget", "price": 9.99})
    svc.post("/items", json={"name": "gadget", "price": 24.99})

    resp = svc.get("/items")
    print(resp.json())
    # [{"name": "widget", "price": 9.99}, {"name": "gadget", "price": 24.99}]

    # Open the auto-generated API docs in a browser
    print(svc.browser_url)

    handle.kill()

服务 URL 与 TCP 隧道

	服务 URL	TCP 隧道
协议	HTTP	任意 TCP（数据库、Redis、SSH、HTTP）
设置	零配置——只需一个 URL	需要 SDK 或 CLI
访问来源	浏览器、脚本、CI、任何地方	仅本地机器
共享	复制 URL 并发送	不可共享
多页面 Web 应用	完全支持（子域路由）	完全支持（本地端口）
非 HTTP 服务	不支持	完全支持

对于需要从浏览器访问或与他人分享的 HTTP 服务，请使用服务 URL。对于非 HTTP 协议（如 psql 或 redis-cli），或当你需要仅限本地访问时，请使用 TCP 隧道。

要分享单个文件而不是正在运行的服务，请使用**下载链接**。

故障排查

错误	原因	修复
"Service link has expired"	超出 token 生命周期	从 LangSmith 再次打开服务，或调用 sb.service() 获取新 URL
"Service is not reachable"	该端口上没有服务在监听	验证服务器是否在沙箱内运行
"Authentication required"	标头或 cookie 中没有 token	浏览器访问请使用 browser_url，或设置 X-Langsmith-Sandbox-Service-Token 标头

---