> ## Documentation Index > Fetch the complete documentation index at: https://cndoc-langchain.site/llms.txt > Use this file to discover all available pages before exploring further. # 沙箱 > 为由沙箱环境支持的编码代理构建类似 IDE 的用户界面 export const PatternEmbed = ({pattern, theme, height, minHeight = 400, maxHeight = 700, className, defaultView = "preview", defaultSdk = "react", defaultLanguage = "js", showCodeTab = true, agentServer = "prod", onError, onReady}) => { var VALID_GUEST_TYPES = new Set(["READY", "RESIZE", "ERROR", "RUN_STARTED", "TRACE_URL", "THREAD_CLEARED"]); function stub() { return { safeParse: data => ({ success: true, data }), optional: () => stub(), min: () => stub(), url: () => stub() }; } var z = { object: _shape => stub(), literal: _value => stub(), string: () => stub(), number: () => stub(), boolean: () => stub(), enum: _values => stub(), array: _el => stub(), union: _schemas => stub(), record: (_key, _value) => stub(), discriminatedUnion: (_key, _schemas) => ({ safeParse(data) { if (data != null && typeof data === "object" && ("type" in data) && typeof data.type === "string" && VALID_GUEST_TYPES.has(data.type)) { return { success: true, data }; } return { success: false }; }, optional: () => stub(), min: () => stub(), url: () => stub() }) }; var SetThemeMessageSchema = z.object({ type: z.literal("SET_THEME"), theme: z.enum(["light", "dark"]) }); var SetPatternMessageSchema = z.object({ type: z.literal("SET_PATTERN"), slug: z.string() }); var ResetMessageSchema = z.object({ type: z.literal("RESET") }); var SetViewMessageSchema = z.object({ type: z.literal("SET_VIEW"), view: z.enum(["preview", "code"]) }); var SetLanguageMessageSchema = z.object({ type: z.literal("SET_LANGUAGE"), language: z.enum(["js", "python"]) }); var CodeFileSchema = z.object({ filename: z.string(), content: z.string() }); var UpdateCodeMessageSchema = z.object({ type: z.literal("UPDATE_CODE"), files: z.array(CodeFileSchema).min(1), entryFile: z.string() }); var TrackEventMessageSchema = z.object({ type: z.literal("TRACK_EVENT"), name: z.string(), properties: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional() }); var HostToGuestMessageSchema = z.discriminatedUnion("type", [SetThemeMessageSchema, SetPatternMessageSchema, ResetMessageSchema, UpdateCodeMessageSchema, SetViewMessageSchema, SetLanguageMessageSchema, TrackEventMessageSchema]); var ReadyMessageSchema = z.object({ type: z.literal("READY"), framework: z.enum(["react", "vue", "angular", "svelte"]) }); var ResizeMessageSchema = z.object({ type: z.literal("RESIZE"), height: z.number() }); var ErrorMessageSchema = z.object({ type: z.literal("ERROR"), message: z.string(), stack: z.string().optional() }); var RunStartedMessageSchema = z.object({ type: z.literal("RUN_STARTED"), runId: z.string() }); var TraceUrlMessageSchema = z.object({ type: z.literal("TRACE_URL"), url: z.string().url(), runId: z.string() }); var ThreadClearedMessageSchema = z.object({ type: z.literal("THREAD_CLEARED") }); var GuestToHostMessageSchema = z.discriminatedUnion("type", [ReadyMessageSchema, ResizeMessageSchema, ErrorMessageSchema, RunStartedMessageSchema, TraceUrlMessageSchema, ThreadClearedMessageSchema]); var PreviewMessageSchema = z.union([HostToGuestMessageSchema, GuestToHostMessageSchema]); function isOriginAllowed(origin, allowedOrigins) { return allowedOrigins.includes("*") || allowedOrigins.includes(origin); } function createPreviewHost(iframe, options) { const {allowedOrigins} = options; const targetOrigins = options.targetOrigins ?? allowedOrigins; const listeners = new Map(); function postToGuest(message) { if (!iframe.contentWindow) return; for (const origin of targetOrigins) { iframe.contentWindow.postMessage(message, origin); } } function addListener(type, callback) { if (!listeners.has(type)) { listeners.set(type, new Set()); } listeners.get(type).add(callback); return () => { listeners.get(type)?.delete(callback); }; } function handleMessage(event) { if (!isOriginAllowed(event.origin, allowedOrigins)) return; const result = GuestToHostMessageSchema.safeParse(event.data); if (!result.success) return; const msg = result.data; const cbs = listeners.get(msg.type); if (!cbs) return; for (const cb of cbs) { switch (msg.type) { case "READY": cb(msg.framework); break; case "RESIZE": cb(msg.height); break; case "ERROR": cb(msg.message, msg.stack); break; case "RUN_STARTED": cb(msg.runId); break; case "TRACE_URL": cb(msg.url, msg.runId); break; case "THREAD_CLEARED": cb(); break; } } } window.addEventListener("message", handleMessage); return { setTheme(theme) { postToGuest({ type: "SET_THEME", theme }); }, setPattern(slug) { postToGuest({ type: "SET_PATTERN", slug }); }, setView(view) { postToGuest({ type: "SET_VIEW", view }); }, setLanguage(language) { postToGuest({ type: "SET_LANGUAGE", language }); }, updateCode(files, entryFile) { postToGuest({ type: "UPDATE_CODE", files, entryFile }); }, reset() { postToGuest({ type: "RESET" }); }, trackEvent(name, properties) { postToGuest({ type: "TRACK_EVENT", name, properties }); }, onReady(callback) { return addListener("READY", callback); }, onResize(callback) { return addListener("RESIZE", callback); }, onError(callback) { return addListener("ERROR", callback); }, onRunStarted(callback) { return addListener("RUN_STARTED", callback); }, onTraceUrl(callback) { return addListener("TRACE_URL", callback); }, onThreadCleared(callback) { return addListener("THREAD_CLEARED", callback); }, destroy() { window.removeEventListener("message", handleMessage); listeners.clear(); } }; } var PROD_BASE = "https://ui-patterns.langchain.com"; var SDK_LABELS = { react: "React", vue: "Vue", svelte: "Svelte", angular: "Angular" }; var SDK_LOCAL_HOSTS = { react: "http://localhost:4100", vue: "http://localhost:4200", svelte: "http://localhost:4300", angular: "http://localhost:4400" }; var SDK_PROD_HOSTS = { react: `${PROD_BASE}/react`, vue: `${PROD_BASE}/vue`, svelte: `${PROD_BASE}/svelte`, angular: `${PROD_BASE}/angular` }; var SDK_LOGOS = { react: ``, vue: ``, svelte: ``, angular: `` }; var PROD_AGENT_API_BASE = `${PROD_BASE}/api/langgraph`; function normalizeAgentServerBase(agentServer, useLocalPreview) { const trimmed = agentServer.trim(); if (useLocalPreview) { return "http://localhost:2024"; } if (trimmed === "prod") { return PROD_AGENT_API_BASE; } if (trimmed === "local") { return PROD_AGENT_API_BASE; } return PROD_AGENT_API_BASE; } function isLocalhost() { if (typeof window === "undefined") return false; const {hostname} = window.location; return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::]"; } function detectPageTheme() { if (typeof document === "undefined") return "light"; const el = document.documentElement; if (el.classList.contains("dark")) return "dark"; if (el.getAttribute("data-theme") === "dark") return "dark"; if (el.style.colorScheme === "dark") return "dark"; return "light"; } var CACHE_KEY = "__lcPlaygroundIframeCache"; var iframeCache = globalThis[CACHE_KEY] ?? (() => { const m = new Map(); globalThis[CACHE_KEY] = m; return m; })(); var SDK_CACHE_KEY = "__lcPlaygroundSdkCache"; var sdkCache = globalThis[SDK_CACHE_KEY] ?? (() => { const m = new Map(); globalThis[SDK_CACHE_KEY] = m; return m; })(); var LANG_CACHE_KEY = "__lcPlaygroundLangCache"; var langCache = globalThis[LANG_CACHE_KEY] ?? (() => { const m = new Map(); globalThis[LANG_CACHE_KEY] = m; return m; })(); var VIEW_EYE_SVG = ``; var VIEW_CODE_SVG = ``; var CHEVRON_DOWN_SVG = ``; var TRACE_ICON_SVG = ``; var TRACE_SPINNER_SVG = ``; var EXTERNAL_LINK_SVG = ``; var DOWNLOAD_SVG = ``; var EXPAND_SVG = ``; var CLOSE_SVG = ``; var LANG_TS_SVG = ``; var LANG_PYTHON_SVG = ` `; var SDK_OPTIONS = Object.keys(SDK_LABELS).map(k => [k, SDK_LABELS[k]]); var EMBED_CSS = ` [data-lc-pe] .lc-tab{font-size:13px;font-family:inherit} [data-lc-pe] .lc-sdk-option{font-size:13px} [data-lc-pe] .lc-border{border-color:#B8DFFF} [data-lc-pe].dark .lc-border{border-color:#1A2740} [data-lc-pe] .lc-bg-surface{background-color:white} [data-lc-pe].dark .lc-bg-surface{background-color:#0B1120} [data-lc-pe] .lc-bg-wash{background-color:#F2FAFF} [data-lc-pe].dark .lc-bg-wash{background-color:#030710} [data-lc-pe] .lc-tab-active{background-color:#7FC8FF;color:#030710} [data-lc-pe] .lc-tab-inactive{background-color:transparent;color:#6B8299} [data-lc-pe] .lc-tab-inactive:hover{background-color:#E5F4FF;color:#030710} [data-lc-pe].dark .lc-tab-inactive:hover{background-color:#1A2740;color:#C8DDF0} [data-lc-pe] .lc-tab-trace{background-color:#FFF3E0;color:#E65100} [data-lc-pe].dark .lc-tab-trace{background-color:#3E2723;color:#FFB74D} [data-lc-pe] .lc-tab-trace:hover{background-color:#FFE0B2} [data-lc-pe].dark .lc-tab-trace:hover{background-color:#4E342E} [data-lc-pe] .lc-tab-trace-loading{background-color:transparent;color:#6B8299;cursor:not-allowed} [data-lc-pe] .lc-sdk-btn{border-color:#B8DFFF;background-color:white;font-size:13px;color:#030710} [data-lc-pe].dark .lc-sdk-btn{border-color:#1A2740;background-color:#0B1120;color:#C8DDF0} [data-lc-pe] .lc-sdk-btn:hover{background-color:#E5F4FF} [data-lc-pe].dark .lc-sdk-btn:hover{background-color:#1A2740} [data-lc-pe] .lc-dropdown{border-color:#B8DFFF;background-color:white;min-width:120px} [data-lc-pe].dark .lc-dropdown{border-color:#1A2740;background-color:#0B1120} [data-lc-pe] .lc-sdk-selected{background-color:#E5F4FF;color:#030710} [data-lc-pe].dark .lc-sdk-selected{background-color:#1A2740;color:#C8DDF0} [data-lc-pe] .lc-sdk-unselected{color:#6B8299} [data-lc-pe] .lc-sdk-unselected:hover{background-color:#F2FAFF;color:#030710} [data-lc-pe].dark .lc-sdk-unselected:hover{background-color:#1A2740;color:#C8DDF0} [data-lc-pe] .lc-spinner{border-color:#B8DFFF;border-top-color:#7FC8FF} [data-lc-pe].dark .lc-spinner{border-color:#1A2740;border-top-color:#7FC8FF} [data-lc-pe] .lc-error{background-color:rgb(178 125 117/0.1);border-color:rgb(178 125 117/0.3);color:#B27D75} [data-lc-pe] .lc-error-btn{border-color:rgb(178 125 117/0.3);background-color:white;color:#B27D75} [data-lc-pe].dark .lc-error-btn{background-color:#0B1120} [data-lc-pe] .lc-lang-switcher .lc-tab{padding:4px 8px} @media(max-width:639px){ [data-lc-pe] .lc-toolbar{flex-wrap:wrap;gap:8px} [data-lc-pe] .lc-tab-label{display:none} [data-lc-pe] .lc-tab{padding-left:10px;padding-right:10px} [data-lc-pe] .lc-sdk-btn{margin-left:auto} } [data-lc-pe] .lc-expand-btn{border:none;background:transparent;cursor:pointer;padding:6px;border-radius:6px;display:inline-flex;align-items:center;justify-content:center;color:#6B8299;transition:background-color 0.15s,color 0.15s} [data-lc-pe] .lc-expand-btn:hover{background-color:#E5F4FF;color:#030710} [data-lc-pe].dark .lc-expand-btn:hover{background-color:#1A2740;color:#C8DDF0} .lc-pe-backdrop{position:fixed;inset:0;z-index:9998;background:rgba(0,0,0,0.4);backdrop-filter:blur(4px);-webkit-backdrop-filter:blur(4px)} `; const slotRef = useRef(null); const cardRef = useRef(null); const placeholderRef = useRef(null); const cachedRef = useRef(null); const useLocalPreview = agentServer === "local" || agentServer === "prod" && isLocalhost(); const agentQuery = agentServer !== "local" && agentServer !== "prod" ? `?agentServer=${encodeURIComponent(agentServer)}` : ""; const sdkCacheKey = `${agentServer}|${pattern}`; const [sdk, setSdkRaw] = useState(() => { const fromCache = sdkCache.get(sdkCacheKey); if (fromCache) return fromCache; const hosts = useLocalPreview ? SDK_LOCAL_HOSTS : SDK_PROD_HOSTS; let best = null; for (const [s, url] of Object.entries(hosts)) { const entry = iframeCache.get(`${url}|${agentQuery}`); if (entry?.lastActiveAt && (!best || entry.lastActiveAt > best.at)) { best = { sdk: s, at: entry.lastActiveAt }; } } if (best) return best.sdk; return defaultSdk; }); const setSdk = useCallback(s => { sdkCache.set(sdkCacheKey, s); setSdkRaw(s); }, [sdkCacheKey]); const [sdkDropdownOpen, setSdkDropdownOpen] = useState(false); const langCacheKey = `${agentServer}|${pattern}`; const [agentLang, setAgentLangRaw] = useState(() => langCache.get(langCacheKey) ?? defaultLanguage); const setAgentLang = useCallback(l => { langCache.set(langCacheKey, l); setAgentLangRaw(l); }, [langCacheKey]); const previewUrl = useLocalPreview ? SDK_LOCAL_HOSTS[sdk] : SDK_PROD_HOSTS[sdk]; const cacheKey = `${previewUrl}|${agentQuery}`; const [ready, setReady] = useState(() => iframeCache.get(cacheKey)?.ready ?? false); const [iframeHeight, setIframeHeight] = useState(() => iframeCache.get(cacheKey)?.lastHeight ?? minHeight); const [error, setError] = useState(null); const [activeView, setActiveView] = useState(() => iframeCache.get(cacheKey)?.lastView ?? defaultView); const [traceUrl, setTraceUrl] = useState(null); const [traceLoading, setTraceLoading] = useState(false); const [expanded, setExpanded] = useState(false); const expandedRef = useRef(false); expandedRef.current = expanded; const [pageTheme, setPageTheme] = useState(detectPageTheme); useEffect(() => { setPageTheme(detectPageTheme()); const observer = new MutationObserver(() => setPageTheme(detectPageTheme())); observer.observe(document.documentElement, { attributes: true, attributeFilter: ["class", "data-theme", "style"] }); return () => observer.disconnect(); }, []); const effectiveTheme = theme ?? pageTheme; useEffect(() => { if (document.getElementById("lc-pe-css")) return; const style = document.createElement("style"); style.id = "lc-pe-css"; style.textContent = EMBED_CSS; document.head.appendChild(style); }, []); const onErrorRef = useRef(onError); onErrorRef.current = onError; const onReadyRef = useRef(onReady); onReadyRef.current = onReady; const patternRef = useRef(pattern); patternRef.current = pattern; const themeRef = useRef(effectiveTheme); themeRef.current = effectiveTheme; const activeViewRef = useRef(activeView); activeViewRef.current = activeView; const agentLangRef = useRef(agentLang); agentLangRef.current = agentLang; useEffect(() => { let cached = iframeCache.get(cacheKey); if (cached?.hideTimer) { clearTimeout(cached.hideTimer); cached.hideTimer = void 0; } if (!cached) { const iframe2 = document.createElement("iframe"); iframe2.src = `${previewUrl}/${agentQuery}#/${patternRef.current}`; iframe2.setAttribute("sandbox", "allow-scripts allow-same-origin allow-forms"); iframe2.setAttribute("allow", "clipboard-write"); iframe2.title = `${patternRef.current} pattern`; iframe2.setAttribute("data-cache-key", cacheKey); Object.assign(iframe2.style, { position: "fixed", border: "none", visibility: "hidden", pointerEvents: "auto", zIndex: "1", borderRadius: "0 0 15px 15px" }); document.body.appendChild(iframe2); let iframeOrigin; try { iframeOrigin = new URL(previewUrl).origin; } catch { iframeOrigin = previewUrl; } const host2 = createPreviewHost(iframe2, { allowedOrigins: [iframeOrigin] }); cached = { iframe: iframe2, host: host2, ready: false, lastHeight: minHeight, lastView: defaultView, lastActiveAt: 0 }; iframeCache.set(cacheKey, cached); } cachedRef.current = cached; const {iframe, host} = cached; if (cached.ready) { setReady(true); setIframeHeight(cached.lastHeight); host.setTheme(themeRef.current); host.setPattern(patternRef.current); host.setLanguage(agentLangRef.current); if (activeViewRef.current !== "preview") { host.setView(activeViewRef.current); } cached.lastActiveAt = Date.now(); iframe.style.visibility = "visible"; } const unsubReady = host.onReady(() => { cached.ready = true; cached.lastActiveAt = Date.now(); setReady(true); host.setTheme(themeRef.current); host.setPattern(patternRef.current); host.setLanguage(agentLangRef.current); if (activeViewRef.current !== "preview") { host.setView(activeViewRef.current); } iframe.style.visibility = "visible"; onReadyRef.current?.(); }); const unsubResize = host.onResize(h => { if (expandedRef.current) return; const clamped = Math.min(maxHeight, Math.max(minHeight, h)); cached.lastHeight = clamped; setIframeHeight(clamped); }); const unsubError = host.onError((message, stack) => { setError(message); iframe.style.visibility = "hidden"; onErrorRef.current?.(message, stack); }); const unsubRunStarted = host.onRunStarted(() => { setTraceUrl(null); setTraceLoading(true); }); const unsubTraceUrl = host.onTraceUrl((url, _runId) => { setTraceUrl(url); setTraceLoading(false); }); const unsubThreadCleared = host.onThreadCleared(() => { setTraceUrl(null); setTraceLoading(false); }); function syncPosition() { const slot2 = slotRef.current; if (!slot2) return; const rect = slot2.getBoundingClientRect(); const {style} = iframe; style.top = `${rect.top}px`; style.left = `${rect.left}px`; style.width = `${rect.width}px`; style.setProperty("height", `${rect.height}px`, "important"); if (expandedRef.current) { style.zIndex = "10000"; } else { style.zIndex = "1"; } } syncPosition(); const ro = new ResizeObserver(syncPosition); if (slotRef.current) ro.observe(slotRef.current); document.addEventListener("scroll", syncPosition, { passive: true, capture: true }); window.addEventListener("resize", syncPosition, { passive: true }); let frameCount = 0; let rafId = 0; function initialSync() { syncPosition(); if (++frameCount < 5) rafId = requestAnimationFrame(initialSync); } rafId = requestAnimationFrame(initialSync); return () => { cancelAnimationFrame(rafId); ro.disconnect(); document.removeEventListener("scroll", syncPosition, { capture: true }); window.removeEventListener("resize", syncPosition); unsubReady(); unsubResize(); unsubError(); unsubRunStarted(); unsubTraceUrl(); unsubThreadCleared(); cachedRef.current = null; cached.hideTimer = setTimeout(() => { iframe.style.visibility = "hidden"; }, 200); }; }, [cacheKey, previewUrl, agentQuery, defaultView, minHeight, maxHeight]); useEffect(() => { requestAnimationFrame(() => window.dispatchEvent(new Event("resize"))); if (!expanded) return; const card = cardRef.current; const placeholder = placeholderRef.current; if (!card || !placeholder) return; const wrapper = document.createElement("div"); wrapper.setAttribute("data-lc-pe", ""); wrapper.className = `${effectiveTheme === "dark" ? "dark" : ""}`; document.body.appendChild(wrapper); const backdrop = document.createElement("div"); backdrop.className = "lc-pe-backdrop"; backdrop.addEventListener("click", () => setExpanded(false)); wrapper.appendChild(backdrop); wrapper.appendChild(card); Object.assign(card.style, { position: "fixed", zIndex: "9999", top: "50%", left: "50%", transform: "translate(-50%, -50%)", width: "min(70vw, calc(100vw - 48px))", height: "85vh", display: "flex", flexDirection: "column" }); const handleKeyDown = e => { if (e.key === "Escape") setExpanded(false); }; document.addEventListener("keydown", handleKeyDown); const pageWrapper = document.body.children[0]; const savedFilter = pageWrapper?.style.filter ?? ""; const savedPointerEvents = pageWrapper?.style.pointerEvents ?? ""; if (pageWrapper && pageWrapper !== wrapper) { pageWrapper.style.filter = "blur(4px)"; pageWrapper.style.pointerEvents = "none"; } requestAnimationFrame(() => window.dispatchEvent(new Event("resize"))); return () => { document.removeEventListener("keydown", handleKeyDown); if (pageWrapper && pageWrapper !== wrapper) { pageWrapper.style.filter = savedFilter; pageWrapper.style.pointerEvents = savedPointerEvents; } card.style.cssText = ""; placeholder.appendChild(card); wrapper.remove(); requestAnimationFrame(() => window.dispatchEvent(new Event("resize"))); }; }, [expanded, effectiveTheme]); useEffect(() => { if (!ready || !cachedRef.current) return; setError(null); cachedRef.current.host.setPattern(pattern); }, [pattern, ready]); useEffect(() => { if (!ready || !cachedRef.current) return; cachedRef.current.host.setTheme(effectiveTheme); }, [effectiveTheme, ready]); useEffect(() => { if (!ready || !cachedRef.current) return; cachedRef.current.host.setLanguage(agentLang); }, [agentLang, ready]); const switchView = useCallback(view => { setActiveView(view); if (cachedRef.current) { cachedRef.current.lastView = view; if (cachedRef.current.ready) { cachedRef.current.host.setView(view); if (view === "code") { cachedRef.current.host.trackEvent("code_tab_clicked", { pattern }); } } } }, [pattern]); const sdkButtonRef = useRef(null); useEffect(() => { if (!sdkDropdownOpen || !sdkButtonRef.current) return; const isDark = effectiveTheme === "dark"; const rect = sdkButtonRef.current.getBoundingClientRect(); const dropdown = document.createElement("div"); Object.assign(dropdown.style, { position: "fixed", top: `${rect.bottom + 4}px`, right: `${window.innerWidth - rect.right}px`, zIndex: expandedRef.current ? "10001" : "10", minWidth: "120px", borderRadius: "8px", border: `1px solid ${isDark ? "#1A2740" : "#B8DFFF"}`, backgroundColor: isDark ? "#0B1120" : "white", boxShadow: "0 4px 12px rgba(0,0,0,0.15)", padding: "4px 0" }); for (const [value, label] of SDK_OPTIONS) { const isSelected = value === sdk; const btn = document.createElement("button"); btn.type = "button"; Object.assign(btn.style, { display: "flex", alignItems: "center", gap: "6px", width: "100%", textAlign: "left", padding: "6px 12px", fontSize: "13px", cursor: "pointer", border: "none", fontWeight: isSelected ? "500" : "normal", backgroundColor: isSelected ? isDark ? "#1A2740" : "#E5F4FF" : "transparent", color: isSelected ? isDark ? "#C8DDF0" : "#030710" : "#6B8299" }); btn.innerHTML = `${SDK_LOGOS[value]}${label}`; btn.addEventListener("mouseenter", () => { if (!isSelected) { btn.style.backgroundColor = isDark ? "#1A2740" : "#F2FAFF"; btn.style.color = isDark ? "#C8DDF0" : "#030710"; } }); btn.addEventListener("mouseleave", () => { if (!isSelected) { btn.style.backgroundColor = "transparent"; btn.style.color = "#6B8299"; } }); btn.addEventListener("click", () => { setSdk(value); setSdkDropdownOpen(false); cachedRef.current?.host.trackEvent("sdk_switched", { sdk: value, pattern }); }); dropdown.appendChild(btn); } document.body.appendChild(dropdown); const handleClose = e => { if (!dropdown.contains(e.target) && !sdkButtonRef.current?.contains(e.target)) { setSdkDropdownOpen(false); } }; const timer = setTimeout(() => document.addEventListener("mousedown", handleClose), 0); return () => { clearTimeout(timer); document.removeEventListener("mousedown", handleClose); dropdown.remove(); }; }, [sdkDropdownOpen, sdk, effectiveTheme, setSdk, pattern]); const handleReset = useCallback(() => { cachedRef.current?.host.reset(); if (cachedRef.current?.ready) { cachedRef.current.host.setPattern(pattern); } }, [pattern]); const resolvedHeight = height ?? Math.min(maxHeight, Math.max(minHeight, iframeHeight)); const heightStyle = typeof resolvedHeight === "number" ? `${resolvedHeight}px` : resolvedHeight; useEffect(() => { if (!expanded) { slotRef.current?.style.setProperty("height", heightStyle, "important"); } else { slotRef.current?.style.removeProperty("height"); } }, [heightStyle, expanded]); const tabBase = "lc-tab inline-flex items-center gap-1.5 px-3.5 py-1.5 rounded-lg border-none font-medium cursor-pointer transition-all duration-150"; const tabActiveClass = `${tabBase} lc-tab-active shadow-sm`; const tabInactiveClass = `${tabBase} lc-tab-inactive`; const tabTraceActiveClass = `${tabBase} lc-tab-trace`; const tabTraceLoadingClass = `${tabBase} lc-tab-trace-loading`; const toolbar = showCodeTab &&
{(traceUrl || traceLoading) && !useLocalPreview && { if (!traceUrl) e.preventDefault(); else cachedRef.current?.host.trackEvent("trace_tab_clicked", { pattern }); }} className={traceUrl ? tabTraceActiveClass : tabTraceLoadingClass} aria-disabled={!traceUrl}> Trace {traceUrl && } }
{activeView === "code" &&
}
{} {}
; const slot =
{!ready && !error &&
} {error &&
Preview Error

{error}

}
; return
{toolbar} {slot}
; }; 编码代理需要的不仅仅是一个聊天窗口。它们需要文件浏览器、代码查看器和差异面板，即一种 IDE 体验。此模式将深度代理连接到[沙箱](/oss/javascript/deepagents/sandboxes)，使其能够在隔离环境中读取、写入和执行代码，然后通过自定义 API 服务器暴露沙箱文件系统，以便前端可以在代理工作时实时显示文件。 ## 架构 沙箱模式有三个层次： 1. **具有沙箱后端的深度代理：** 代理从沙箱自动获取文件系统工具（`read_file`、`write_file`、`edit_file`、`execute`） 2. **自定义 API 服务器：** 一个通过 `langgraph.json` 的 `http.app` 字段暴露的 Hono 应用，提供前端可以调用的文件浏览端点 3. **IDE 前端：** 一个三面板布局（文件树、代码/差异查看器、聊天），在代理进行更改时实时同步文件 ```mermaid theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} %%{ init: { "fontFamily": "monospace", "flowchart": { "curve": "curve" } } }%% graph LR UI["IDE 前端"] API["API 服务器"] AGENT["createDeepAgent()"] SANDBOX["沙箱"] UI --"useStream()"--> AGENT UI --"/api/sandbox/:threadId/*"--> API AGENT --"读/写/执行"--> SANDBOX API --"ls / 读取"--> SANDBOX classDef blueHighlight fill:#E5F4FF,stroke:#006DDD,color:#030710; classDef greenHighlight fill:#F6FFDB,stroke:#6E8900,color:#2E3900; classDef purpleHighlight fill:#EBD0F0,stroke:#885270,color:#441E33; classDef orangeHighlight fill:#FDF3FF,stroke:#7E65AE,color:#504B5F; class UI blueHighlight; class AGENT greenHighlight; class SANDBOX purpleHighlight; class API orangeHighlight; ``` ## 沙箱生命周期 在深入代码之前，了解沙箱的作用域很重要。作用域策略决定了谁共享一个沙箱、它存活多久以及如何在运行时解析它。 ### 线程作用域沙箱（推荐） 每个 LangGraph 线程都有自己的沙箱。沙箱 ID 存储在线程的元数据中，并在运行时通过 `getConfig()` 解析。这是大多数应用程序的推荐方法： * 对话是隔离的——一个线程中的文件更改不会影响另一个线程 * 沙箱状态在页面重新加载后持续存在（相同线程 = 相同沙箱） * 清理很简单：当线程被删除时，其沙箱也可以被删除 ```mermaid theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} sequenceDiagram participant FE as 前端 participant LG as LangGraph API participant HTTP as API 服务器 participant SB as 沙箱 Note over FE: 页面加载 FE->>LG: POST /threads LG-->>FE: threadId FE->>HTTP: GET /api/sandbox/:threadId/tree HTTP->>LG: threads.get(threadId) → metadata.sandbox_id alt 尚无沙箱 HTTP->>SB: LangSmithSandbox.create() HTTP->>LG: threads.update(threadId, metadata.sandbox_id) else 已有沙箱 HTTP->>SB: connect(sandbox_id) end HTTP-->>FE: 文件树 Note over FE: 用户发送消息 FE->>LG: POST /threads/:threadId/runs/stream LG->>LG: 后端从配置中读取 thread_id LG->>SB: 连接到同一沙箱 ``` ### 代理作用域沙箱 同一助手下的所有线程共享一个沙箱。适用于需要跨对话保留更改的持久项目环境： ```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} import { getConfig } from "@langchain/langgraph"; function getSandboxBackendForAssistant() { const config = getConfig(); const assistantId = config.metadata?.assistant_id; return getOrCreateSandboxForAssistant(assistantId); } ``` ### 用户作用域沙箱 每个用户在所有线程中都有自己的沙箱。需要自定义身份验证和用户识别： ```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} import { getConfig } from "@langchain/langgraph"; function getSandboxBackendForUser() { const config = getConfig(); const userId = config.configurable?.user_id; return getOrCreateSandboxForUser(userId); } ``` ### 会话作用域沙箱（客户端） 对于没有 LangGraph 线程的简单应用程序，前端可以生成会话 ID 并直接传递。这种方法不会跨浏览器会话持久化，最适合演示或原型设计： ```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} const sessionId = crypto.randomUUID(); fetch(`/api/sandbox/tree?sessionId=${sessionId}`); ``` 本指南的其余部分使用**线程作用域沙箱**作为主要示例。 ## 设置代理 ### 选择沙箱提供商 深度代理支持多种沙箱提供商。任何实现 `SandboxBackendProtocol` 的提供商都可以： ```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} import { createDeepAgent, LangSmithSandbox } from "deepagents"; const sandbox = await LangSmithSandbox.create(); export const agent = createDeepAgent({ model: "google_genai:gemini-3.1-pro-preview", backend: sandbox, systemPrompt: "You are an expert developer working on a project in /app.", }); ``` 代理自动获取文件系统工具（`read_file`、`write_file`、`edit_file`、`ls`、`glob`、`grep`）和一个用于运行 shell 命令的 `execute` 工具。无需工具配置。 ### 为每个线程解析沙箱 不要在模块级别创建沙箱（这会在所有线程之间共享并可能过期），而是在运行时按线程解析沙箱。沙箱通过 `getConfig()` 从 LangGraph 配置中读取 `thread_id`： ```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} import { createDeepAgent, LangSmithSandbox } from "deepagents"; import { getConfig } from "@langchain/langgraph"; async function getOrCreateSandboxForThread(threadId: string): Promise { // 检查线程元数据中是否存在现有的 sandbox_id const client = new Client({ apiUrl: "http://localhost:2024" }); const thread = await client.threads.get(threadId); const sandboxId = thread.metadata?.sandbox_id; if (sandboxId) { // 重新连接到现有沙箱 return new LangSmithSandbox({ sandbox: await new SandboxClient().getSandbox(sandboxId), }); } // 创建新沙箱并将 ID 存储在线程元数据中 const sandbox = await LangSmithSandbox.create({ templateName: "my-template" }); await seedSandbox(sandbox); await client.threads.update(threadId, { metadata: { sandbox_id: sandbox.id } }); return sandbox; } // 创建一个在运行时按线程解析的沙箱 const sandbox = new LangSmithSandbox({ resolve: async () => { const config = getConfig(); const threadId = config.configurable?.thread_id; if (!threadId) throw new Error("No thread_id — agent must run on a thread"); return getOrCreateSandboxForThread(threadId); }, }); export const agent = createDeepAgent({ model: "google_genai:gemini-3.1-pro-preview", backend: sandbox, systemPrompt: "You are an expert developer working on a project in /app.", }); ``` ### 填充沙箱 在代理运行之前，使用 `uploadFiles` 将项目文件填充到沙箱中： 对于 **LangSmith** 沙箱，容器镜像和资源限制来自[沙箱快照](/langsmith/sandbox-snapshots)。创建沙箱时传递 `templateName`（参见上面的 `getOrCreateSandboxForThread`）。`uploadFiles` 在运行时在该镜像基础上填充或更新项目文件。 ```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} const SEED_FILES: Record = { "package.json": JSON.stringify({ name: "my-app", version: "1.0.0" }, null, 2), "src/index.js": 'console.log("Hello");', }; const encoder = new TextEncoder(); await sandbox.uploadFiles( Object.entries(SEED_FILES).map(([path, content]) => [`/app/${path}`, encoder.encode(content)]), ); ``` 在上传 `package.json` 后运行 `sandbox.execute("cd /app && npm install")` 以在代理开始之前安装依赖项。 ## 添加文件浏览 API 代理可以读写文件，但前端也需要直接访问以浏览沙箱文件系统。添加一个自定义 [Hono](https://hono.dev) API 服务器，并通过 `langgraph.json` 中的 `http.app` 字段暴露它。 ### 创建 API 服务器 沙箱 API 端点使用线程 ID 作为 URL 路径参数。这确保前端始终访问当前对话的正确沙箱，使用与代理后端相同的 `getOrCreateSandboxForThread` 函数： ```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} // src/api/app.ts import { Hono } from "hono"; import { getOrCreateSandboxForThread } from "./utils.js"; export const app = new Hono(); app.get("/api/sandbox/:threadId/tree", async (c) => { const threadId = c.req.param("threadId"); const rootPath = c.req.query("filePath") || "/app"; const sandbox = await getOrCreateSandboxForThread(threadId); const result = await sandbox.execute( `find '${rootPath}' -printf '%y\\t%s\\t%p\\n' 2>/dev/null | sort -t$'\\t' -k3`, ); const entries = result.output .trim() .split("\n") .filter(Boolean) .map((line) => { const [typeChar, sizeStr, fullPath] = line.split("\t"); return { name: fullPath.split("/").pop(), type: typeChar === "d" ? "directory" : "file", path: fullPath, size: parseInt(sizeStr, 10) || 0, }; }); return c.json({ path: rootPath, entries, sandboxId: sandbox.id }); }); app.get("/api/sandbox/:threadId/file", async (c) => { const threadId = c.req.param("threadId"); const filePath = c.req.query("filePath"); if (!filePath) return c.json({ error: "filePath is required" }, 400); const sandbox = await getOrCreateSandboxForThread(threadId); const results = await sandbox.downloadFiles([filePath]); const file = results[0]; if (file.error) return c.json({ error: file.error }, 404); const content = new TextDecoder().decode(file.content!); return c.json({ path: filePath, content }); }); ``` 代理的后端和 API 服务器都调用相同的 `getOrCreateSandboxForThread` 函数。这确保它们始终为给定线程解析到相同的沙箱。线程元数据中的沙箱 ID 是唯一的事实来源——不需要内存缓存。 ### 配置 `langgraph.json` 注册代理图和 API 服务器。`http.app` 字段告诉 LangGraph 平台在默认路由旁边提供您的自定义路由： ```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} { "node_version": "22", "graphs": { "coding_agent": "./src/agents/my-agent.ts:agent" }, "env": ".env", "http": { "app": "./src/api/app.ts:app" } } ``` 您的自定义路由与 LangGraph API 位于同一主机。对于使用 `langgraph dev` 的本地开发，该主机是 `http://localhost:2024`。 在 `http.app` 中定义的自定义路由优先于默认的 LangGraph 路由。这意味着您可以根据需要覆盖内置端点，但要小心不要意外覆盖像 `/threads` 或 `/runs` 这样的路由。 ## 构建前端 前端有三个面板：文件树侧边栏、代码/差异查看器和聊天面板。它使用 `useStream` 进行代理对话，使用自定义 API 端点进行文件浏览。 ### 线程创建 在页面加载时创建一个 LangGraph 线程，并将其 ID 持久化到 `sessionStorage` 中，以便页面重新加载时重新连接到相同的沙箱： ```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} const THREAD_KEY = "sandbox-thread-id"; function IDEPreview() { const [threadId, setThreadId] = useState( () => sessionStorage.getItem(THREAD_KEY), ); const updateThreadId = useCallback((id: string | null) => { setThreadId(id); if (id) sessionStorage.setItem(THREAD_KEY, id); else sessionStorage.removeItem(THREAD_KEY); }, []); const stream = useStream({ apiUrl: AGENT_URL, assistantId: "coding_agent", threadId, onThreadId: updateThreadId, }); // 首次挂载时创建线程 useEffect(() => { if (threadId) return; stream.client.threads.create().then((t) => updateThreadId(t.thread_id)); }, [stream.client, threadId, updateThreadId]); // 将 threadId 传递给沙箱文件钩子 const { tree, files } = useSandboxFiles(threadId); // ... } ``` “新线程”按钮清除存储的 ID，以便下次挂载时创建一个新线程（和沙箱）： ```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} function handleNewThread() { stream.switchThread(null); updateThreadId(null); } ``` ### 文件状态管理 跟踪沙箱文件系统的两个快照：原始状态（代理运行前）和当前状态（实时更新）。线程 ID 包含在 API URL 中，因此请求始终命中正确的沙箱： ```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} const AGENT_URL = "http://localhost:2024"; async function fetchTree(threadId: string): Promise { const res = await fetch( `${AGENT_URL}/api/sandbox/${encodeURIComponent(threadId)}/tree?filePath=/app`, ); const data = await res.json(); return data.entries.filter((e: FileEntry) => !e.path.includes("node_modules")); } async function fetchFile(threadId: string, path: string): Promise { const res = await fetch( `${AGENT_URL}/api/sandbox/${encodeURIComponent(threadId)}/file?filePath=${encodeURIComponent(path)}`, ); const data = await res.json(); return data.content ?? null; } ``` ### 实时文件同步 IDE 体验的关键是在**代理工作时**更新文件，而不是在它完成后。监视流中的消息以查找来自文件修改工具的 `ToolMessage` 实例。当 `write_file` 或 `edit_file` 工具调用完成时，刷新该特定文件。当 `execute` 完成时，刷新所有内容（因为 shell 命令可能修改任何文件）： ```tsx React theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} import { useStream } from "@langchain/react"; import { ToolMessage, AIMessage } from "langchain"; const FILE_MUTATING_TOOLS = new Set(["write_file", "edit_file", "execute"]); export function IDEPreview() { const stream = useStream({ apiUrl: AGENT_URL, assistantId: "coding_agent", }); const processedIds = useRef(new Set()); useEffect(() => { // 从 AI 消息构建文件修改工具调用的映射 const toolCallMap = new Map(); for (const msg of stream.messages) { if (!AIMessage.isInstance(msg)) continue; for (const tc of msg.tool_calls ?? []) { if (tc.id && FILE_MUTATING_TOOLS.has(tc.name)) { toolCallMap.set(tc.id, { name: tc.name, args: tc.args }); } } } // 当文件修改工具的 ToolMessage 出现时，刷新 for (const msg of stream.messages) { if (!ToolMessage.isInstance(msg)) continue; const id = msg.id ?? msg.tool_call_id; if (!id || processedIds.current.has(id)) continue; const call = toolCallMap.get(msg.tool_call_id); if (!call) continue; processedIds.current.add(id); if (call.name === "write_file" || call.name === "edit_file") { refreshSingleFile(call.args.path); } else if (call.name === "execute") { refreshAllFiles(); } } }, [stream.messages]); } ``` ```vue Vue theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} ``` ```svelte Svelte theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} ``` ```ts Angular theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} import { Component, effect } from "@angular/core"; import { useStream } from "@langchain/angular"; import { ToolMessage, AIMessage } from "langchain"; const FILE_MUTATING_TOOLS = new Set(["write_file", "edit_file", "execute"]); @Component({ selector: "app-ide-preview", template: ``, }) export class IdePreviewComponent { stream = useStream({ apiUrl: AGENT_URL, assistantId: "coding_agent", }); private processedIds = new Set(); constructor() { effect(() => { const messages = this.stream.messages(); const toolCallMap = new Map(); for (const msg of messages) { if (AIMessage.isInstance(msg)) { for (const tc of (msg as AIMessage).tool_calls ?? []) { if (tc.id && FILE_MUTATING_TOOLS.has(tc.name)) { toolCallMap.set(tc.id, { name: tc.name, args: tc.args }); } } } } for (const msg of messages) { if (!ToolMessage.isInstance(msg)) continue; const id = (msg as ToolMessage).id ?? (msg as ToolMessage).tool_call_id; if (!id || this.processedIds.has(id)) continue; const call = toolCallMap.get((msg as ToolMessage).tool_call_id); if (!call) continue; this.processedIds.add(id); if (call.name === "write_file" || call.name === "edit_file") { this.refreshSingleFile(call.args.path); } else if (call.name === "execute") { this.refreshAllFiles(); } } }); } } ``` ### 检测更改的文件 在每次代理运行之前，对当前文件内容进行快照。文件刷新后，与快照进行比较以识别哪些文件发生了更改： ```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} function detectChanges(current: FileSnapshot, original: FileSnapshot): Set { const changed = new Set(); for (const [path, content] of Object.entries(current)) { if (original[path] !== content) changed.add(path); } for (const path of Object.keys(original)) { if (!(path in current)) changed.add(path); } return changed; } ``` 当用户选择一个已更改的文件时，默认显示差异视图，以便他们立即看到代理修改了什么。 ### 显示差异 使用适合框架的差异库来渲染统一差异： | 框架 | 库 | 组件 | | ------- | -------------------------------------------------------------------------- | ------------------------------------------------------------ | | React | [`@pierre/diffs`](https://diffs.com) | `` 配合 `parseDiffFromFile` | | Vue | [`@git-diff-view/vue`](https://github.com/MrWangJustToDo/git-diff-view) | `` 配合来自 `@git-diff-view/file` 的 `generateDiffFile` | | Svelte | [`@git-diff-view/svelte`](https://github.com/MrWangJustToDo/git-diff-view) | `` 配合来自 `@git-diff-view/file` 的 `generateDiffFile` | | Angular | [`ngx-diff`](https://github.com/rars/ngx-diff) | `` 配合 `[before]` 和 `[after]` | 使用 `@pierre/diffs` (React) 的示例： ```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} import { FileDiff } from "@pierre/diffs/react"; import { parseDiffFromFile } from "@pierre/diffs"; function DiffPanel({ original, current, fileName }) { const diff = parseDiffFromFile( { name: fileName, contents: original }, { name: fileName, contents: current }, ); return ( ); } ``` ### 已更改文件摘要 显示所有已修改文件的摘要，包括行级添加/删除计数。这为用户提供了代理影响的快速概览——类似于 `git status`： ```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} function ChangedFilesSummary({ changedFiles, files, originalFiles, onSelect }) { const stats = [...changedFiles].map((path) => { const oldLines = (originalFiles[path] ?? "").split("\n"); const newLines = (files[path] ?? "").split("\n"); // 通过比较行来计算添加/删除 return { path, additions, deletions }; }); return (

{stats.length} 个文件已更改

{stats.map((file) => ( ))}
); } ``` ## 三面板布局 IDE 布局将三个面板并排排列： | 面板 | 宽度 | 用途 | | ----- | ---------- | -------------- | | 文件树 | 固定 (208px) | 浏览沙箱文件，查看更改指示器 | | 代码/差异 | 灵活 | 查看文件内容或统一差异 | | 聊天 | 固定 (320px) | 与代理交互 | ```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
``` 文件树显示 VS Code 风格的图标（使用 [`@iconify-json/vscode-icons`](https://www.npmjs.com/package/@iconify-json/vscode-icons)）和修改文件上的琥珀色点。选择修改的文件会自动切换到差异选项卡。 ## 用例 当以下情况时，沙箱是正确的选择： * **编码代理**创建、修改和运行代码需要聊天之外的视觉界面 * **代码审查工作流**，代理建议更改，用户在接受之前审查差异 * **教程或学习应用**，AI 助手帮助用户逐步构建项目，在上下文中显示更改 * **原型设计工具**，用户用自然语言描述功能，并实时观看代理实现它们 ## 最佳实践 * **在生产应用中使用线程作用域沙箱**。将沙箱 ID 存储在线程元数据中，并在运行时通过 `getConfig()` 解析。这避免了模块级状态，并保持沙箱按对话隔离。 * **在代理后端和 API 服务器之间共享 `getOrCreateSandboxForThread`**。两者都应以相同的方式解析沙箱——通过线程元数据——这样就有唯一的事实来源，无需内存缓存。 * **在 `sessionStorage` 中持久化 `threadId`**，以便页面重新加载时重新连接到相同的线程和沙箱，而不是创建新的。 * **在每个相关工具调用时同步文件**，而不仅仅是在运行完成后。这使 IDE 感觉是实时的。监视 `write_file`、`edit_file` 和 `execute` 工具消息并立即刷新。 * **默认为已更改文件显示差异视图**。当用户单击被代理修改的文件时，首先显示差异——这是他们关心的。 * **为只读操作显示紧凑的工具结果**。不要在聊天中转储 `read_file` 的完整输出，而是显示一行内容，如 `Read router.js L1-42`。将完整输出显示保留给修改工具。 * **用真实项目填充沙箱**。从空沙箱开始会让人迷失方向。上传一个可运行的入门项目，以便用户（和代理）立即拥有上下文。 * **从文件树中过滤 `node_modules`**。没有人想浏览数千个依赖文件。在获取树时将它们过滤掉。 ***
[将这些文档连接](/use-these-docs)到 Claude、VSCode 等，通过 MCP 获取实时答案。 [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/deepagents/frontend/sandbox.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。