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

!服务 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()

使用场景

从 UI 打开服务

1. 打开沙盒详情页面。
2. 找到 **打开服务** widget.
3. 输入端口号（例如 3000).
4. 点击 **打开** 在新标签页中启动，或 **分享链接** 复制可以发送给队友的 URL。

拥有链接的任何人都可以访问该服务，即使没有 LangSmith 账户。令牌过期后，从 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)

发出请求

返回的 ServiceURL 对象具有内置的 HTTP 辅助函数，可自动处理身份验证。令牌在过期前透明刷新，因此无需手动管理。

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 和令牌：

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 中使用令牌。

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}'

Response:

{
  "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"},
    )

    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** 访问需要从浏览器访问或希望与他人共享的 HTTP 服务。使用 **TCP 隧道** 用于非 HTTP 协议（如 psql or redis-cli）或当你只需要本地访问时。

故障排除