feat(lens): add sample previews and improve setup and worker feedback (#44268)

* feat(lens): add interactive traces and investigations demo * fix(lens): limit sample previews to setup screens * fix(lens): simplify tracing setup and align sample previews * fix(ui): unify Lens and ROI demo notices * fix(lens): distinguish preparation from zero selected runs * fix(lens): report incompatible workers and address setup review
2026-10-03 02:22:24 +00:00 · 2026-10-02 17:27:13 -07:00 · 2026-10-02 17:27:13 -07:00 · f498176a27
commit f498176a27
parent 22bd49e231
42 changed files with 2427 additions and 1133 deletions
--- a/deploy/lens/README.md
+++ b/deploy/lens/README.md
@ -19,11 +19,13 @@ The URL, database, and retention settings can also come from `CLICKHOUSE_URL`, `

 Retention changes require a proxy restart. ClickHouse removes expired rows during background merges, not immediately at startup. Enable request/response logging to analyze LLM requests. Lens can only inspect content you actually retain

-In Lens, click **Set up analysis**, choose an existing virtual key or **Create worker key**, then **Generate setup command**. The LiteLLM address is filled in for you; change it only if the server running Docker needs a different network address. Copy the command and run it on your server. The dialog changes to **Analyzer connected** when the container checks in
+In **Lens > Investigations**, click **Connect worker**, choose an analysis model and monthly limit, then **Get install command**. Use **Advanced options** to select an existing virtual key or change the proxy URL if the server running Docker needs a different network address. Copy the command and run it on your server. The dashboard shows **Worker connected** when the container checks in

 The command already contains the compatible worker image and one worker token. The selected virtual key stays on the proxy; its secret is never sent to the worker. No source checkout, environment file, or second LiteLLM deployment is needed. Keep the command private because it includes the token. The LiteLLM release provides the dashboard and APIs; the container only runs background analysis

-The dashboard and Compose file pin a verified worker image by digest. The image uses Linux amd64, and the generated command selects that platform. Worker image releases are independent of proxy releases: update the pinned image when changing their API contract. CI also publishes immutable commit tags for reproducible builds
+The dashboard and Compose file pin a verified worker image by digest. The image uses Linux amd64, and the generated command selects that platform. CI also publishes immutable `:sha-<commit>` tags for successful worker builds on `main`. Keep the worker image compatible with your gateway version
+
+After upgrading the gateway, update the worker image and redeploy it while keeping its proxy URL and token. Existing containers do not update automatically. If an investigation reports a worker compatibility error, update the image before retrying

 For deployments managed with Compose, download `compose.yaml` and provide `LITELLM_URL` and `LENS_WORKER_TOKEN` in an environment file. Its default image is already selected:

--- a/deploy/lens/compose.yaml
+++ b/deploy/lens/compose.yaml
@ -1,6 +1,6 @@
 services:
  lens-worker:
-    image: ${LENS_WORKER_IMAGE:-ghcr.io/berriai/litellm-lens-worker@sha256:67eba741c1b97c749975c5c38e2370a603e1105babc908d613c1b79d7b995393}
+    image: ${LENS_WORKER_IMAGE:-ghcr.io/berriai/litellm-lens-worker@sha256:44f0597c7583dcfef999ece9a8bc02cfeb9f0f5167a1221cee3bd10b1b79271b}
    environment:
      LITELLM_URL: ${LITELLM_URL:?Set the URL reachable from this container}
      LENS_WORKER_TOKEN: ${LENS_WORKER_TOKEN:?Create a worker credential in the Lens UI}
--- a/litellm/proxy/lens/worker.py
+++ b/litellm/proxy/lens/worker.py
@ -8,6 +8,7 @@ from types import MappingProxyType
 from typing import Final

 import httpx
+from pydantic import BaseModel, ConfigDict, ValidationError

 from .analysis import analyze_sample
 from .models import Claim, Coverage, ExecutionContent, ModelRequest, ModelResult, Progress, Result, Sample
@ -15,6 +16,17 @@ from .models import Claim, Coverage, ExecutionContent, ModelRequest, ModelResult
 logger: Final = logging.getLogger("litellm.lens.worker")


+class ClaimedJobIdentity(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="ignore")
+    id: str
+
+
+class ClaimIdentity(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="ignore")
+    lens_id: str
+    job: ClaimedJobIdentity
+
+
 def failure_message(error: Exception) -> str:
    if isinstance(error, (OSError, sqlite3.Error)):
        return "Worker temporary storage failed. Increase its capacity or reduce analysis parallelism."
@ -74,9 +86,24 @@ class LensWorker:
    async def run_once(self) -> bool:
        response: Final = await self.client.post("/lens/worker/claim", params=MappingProxyType({"protocol_version": 2}))
        response.raise_for_status()
-        if response.json() is None:
+        payload: Final = response.json()
+        if payload is None:
            return False
-        claim: Final = Claim.model_validate(response.json())
+        try:
+            claim: Final = Claim.model_validate(payload)
+        except ValidationError:
+            identity: Final = ClaimIdentity.model_validate(payload)
+            failure: Final = await self.client.post(
+                f"/lens/worker/{identity.lens_id}/{identity.job.id}/result",
+                json=Result(
+                    coverage=Coverage(),
+                    error="The worker could not read this investigation. Update the worker to match the gateway, then retry.",
+                ).model_dump(),
+            )
+            if failure.status_code != 409:
+                failure.raise_for_status()
+            logger.warning("Worker could not read a claimed investigation; reported a version compatibility failure")
+            return True
        prefix: Final = f"/lens/worker/{claim.lens_id}/{claim.job.id}"

        async def model(body: ModelRequest) -> ModelResult:
--- a/tests/unit/proxy/lens/test_worker.py
+++ b/tests/unit/proxy/lens/test_worker.py
@ -3,6 +3,7 @@ from typing import Final

 import httpx
 import pytest
+from pydantic import ValidationError

 from litellm.proxy.lens.models import (
    Claim,
@ -81,6 +82,45 @@ async def test_idle_worker_does_not_start_an_analysis() -> None:
        assert await LensWorker(client).run_once() is False


+@pytest.mark.asyncio
+@pytest.mark.parametrize("result_status", (200, 409))
+async def test_incompatible_claim_reports_failure_instead_of_leaving_the_investigation_running(
+    result_status: int,
+) -> None:
+    claim: Final = Claim(lens_id="lens", job=queue_job(lens(), NOW, "job").jobs[0], findings=())
+    payload: Final = claim.model_dump(mode="json") | {
+        "job": claim.job.model_dump(mode="json") | {
+            "settings": claim.job.settings.model_dump() | {"future_setting": "private content"},
+        },
+    }
+    saved: Final = SimpleQueue[Result]()
+
+    def handle(request: httpx.Request) -> httpx.Response:
+        if request.url.path == "/lens/worker/claim":
+            return httpx.Response(200, json=payload)
+        assert request.url.path == "/lens/worker/lens/job/result"
+        saved.put(Result.model_validate_json(request.content))
+        return httpx.Response(result_status, json=True)
+
+    async with httpx.AsyncClient(base_url="https://proxy.test", transport=httpx.MockTransport(handle)) as client:
+        assert await LensWorker(client).run_once() is True
+    assert saved.get_nowait().error == (
+        "The worker could not read this investigation. Update the worker to match the gateway, then retry."
+    )
+    assert saved.empty()
+
+
+@pytest.mark.asyncio
+async def test_claim_without_an_identity_does_not_report_failure_for_another_investigation() -> None:
+    def handle(request: httpx.Request) -> httpx.Response:
+        assert request.url.path == "/lens/worker/claim"
+        return httpx.Response(200, json={"job": {"settings": {"future_setting": True}}})
+
+    async with httpx.AsyncClient(base_url="https://proxy.test", transport=httpx.MockTransport(handle)) as client:
+        with pytest.raises(ValidationError):
+            await LensWorker(client).run_once()
+
+
@pytest.mark.asyncio
@pytest.mark.parametrize("model_status", (200, 402, 503))
 async def test_worker_reads_claimed_activity_and_reports_analysis_or_failure(model_status: int) -> None:
--- a/ui/litellm-dashboard/public/assets/logos/google-adk.png
+++ b/ui/litellm-dashboard/public/assets/logos/google-adk.png
--- a/ui/litellm-dashboard/public/assets/logos/hermes.png
+++ b/ui/litellm-dashboard/public/assets/logos/hermes.png
--- a/ui/litellm-dashboard/public/assets/logos/openclaw.png
+++ b/ui/litellm-dashboard/public/assets/logos/openclaw.png
--- a/ui/litellm-dashboard/public/assets/logos/strands.svg
+++ b/ui/litellm-dashboard/public/assets/logos/strands.svg
@ -0,0 +1,4 @@
+<svg width="290" height="463" viewBox="0 0 290 463" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M97.2902 52.7884C85.0674 49.1667 72.2234 56.1389 68.6017 68.3616C64.9801 80.5843 71.9524 93.4283 84.1749 97.0501L235.117 139.775C245.223 142.769 246.357 156.628 236.874 161.226L32.546 260.291C-14.9439 283.316 -9.16107 352.74 41.4835 367.591L189.551 411.009L190.125 411.169C202.183 414.376 214.665 407.396 218.196 395.355C221.784 383.122 214.774 370.296 202.541 366.709L54.4738 323.291C44.3447 320.321 43.1879 306.436 52.6857 301.831L257.014 202.766C304.432 179.776 298.758 110.483 248.233 95.512L97.2902 52.7884Z" fill="#989898"/>
+<path d="M259.147 0.981812C271.389 -2.57498 284.197 4.46571 287.754 16.7074C291.311 28.9492 284.27 41.757 272.028 45.3138L71.1727 103.671C40.7142 112.521 37.1976 154.262 65.7459 168.083L241.343 253.093C307.872 285.302 299.794 382.546 228.862 403.336L30.4041 461.502C18.1707 465.088 5.34708 458.078 1.76153 445.844C-1.8239 433.611 5.18637 420.787 17.4197 417.202L215.878 359.035C246.277 350.125 249.739 308.449 221.226 294.645L45.6297 209.635C-20.9834 177.386 -12.7772 79.9893 58.2928 59.3402L259.147 0.981812Z" fill="#00FF77"/>
+</svg>
--- a/ui/litellm-dashboard/src/app/(dashboard)/hooks/models/useModelCostMap.ts
+++ b/ui/litellm-dashboard/src/app/(dashboard)/hooks/models/useModelCostMap.ts
@ -4,8 +4,9 @@ import { createQueryKeys } from "../common/queryKeysFactory";

 const modelCostMapKeys = createQueryKeys("modelCostMap");

-export const useModelCostMap = () => {
+export const useModelCostMap = (enabled = true) => {
  return useQuery<Record<string, any>>({
+    enabled,
    queryKey: modelCostMapKeys.list({}),
    queryFn: async () => await modelCostMap(),
    staleTime: 60 * 1000, // 1 minute
--- a/ui/litellm-dashboard/src/app/(dashboard)/lens/_components/LensOverview.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/lens/_components/LensOverview.tsx
@ -67,64 +67,6 @@ export function InvestigationList({
  );
 }

-export function InvestigationExample({ onClose }: { onClose: () => void }) {
-  return (
-    <Dialog
-      open
-      onOpenChange={(open) => {
-        if (!open) onClose();
-      }}
-    >
-      <DialogContent className="max-h-[90dvh] gap-5 overflow-y-auto sm:max-w-xl">
-        <DialogHeader className="gap-1.5 pr-6">
-          <DialogTitle className="text-base">Example investigation</DialogTitle>
-        </DialogHeader>
-        <section className="border-t pt-5" aria-labelledby="example-finding">
-          <div className="flex flex-wrap items-center justify-between gap-2 text-xs">
-            <span className="flex items-center gap-1.5 font-medium text-amber-700 dark:text-amber-400">
-              <span className="size-1.5 rounded-full bg-current" aria-hidden="true" />
-              Needs attention
-            </span>
-            <span className="text-muted-foreground">3 of 20 conversations</span>
-          </div>
-          <h3 id="example-finding" className="mt-2 text-lg font-semibold leading-6 tracking-tight">
-            Failed lookups leave customers without answers
-          </h3>
-          <DialogDescription className="mt-2 leading-5">
-            The agent retries the same failed order lookup, then ends the conversation without an answer or a handoff.
-          </DialogDescription>
-        </section>
-        <div className="overflow-hidden rounded-lg border">
-          <div className="space-y-1.5 bg-muted/30 px-4 py-3">
-            <p className="text-xs text-muted-foreground">After three failed lookups, the agent replies:</p>
-            <blockquote className="text-sm leading-5">“I will check that for you.”</blockquote>
-          </div>
-          <details className="group border-t">
-            <summary className="flex cursor-pointer list-none items-center justify-between gap-2 px-4 py-2.5 text-sm font-medium hover:bg-muted/30 focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-ring [&::-webkit-details-marker]:hidden">
-              See the trace <ChevronRight className="size-3.5 transition-transform group-open:rotate-90" />
-            </summary>
-            <ol className="space-y-3 border-t px-4 py-3 text-sm leading-5 text-muted-foreground">
-              <li>
-                <span className="font-medium text-foreground">Customer</span> · Where is my order?
-              </li>
-              <li>
-                <span className="font-medium text-foreground">Order lookup</span> · Service unavailable
-              </li>
-              <li>
-                <span className="font-medium text-foreground">Two retries</span> · Same error, no new information
-              </li>
-              <li>
-                <span className="font-medium text-foreground">Agent</span> · I will check that for you. Conversation
-                ends.
-              </li>
-            </ol>
-          </details>
-        </div>
-      </DialogContent>
-    </Dialog>
-  );
-}
-
 export function MonitoringSetup({
  settings,
  ready,
--- a/ui/litellm-dashboard/src/app/(dashboard)/lens/_components/LensProgress.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/lens/_components/LensProgress.tsx
@ -53,7 +53,7 @@ export function LensProgress({ job, onCancel }: { job: Job; onCancel?: () => voi
        >
          <div
            className={`h-full rounded-full bg-foreground/70 transition-[width] duration-500 ${percent === undefined ? "motion-safe:animate-pulse" : ""}`}
-            style={{ width: percent === undefined ? "100%" : `${percent}%` }}
+            style={{ width: percent === undefined ? "33%" : `${percent}%` }}
          />
        </div>
      </div>
--- a/ui/litellm-dashboard/src/app/(dashboard)/lens/_components/LensView.integration.test.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/lens/_components/LensView.integration.test.tsx
@ -231,39 +231,18 @@ it("runs saved settings immediately without opening setup", async () => {
  expect(screen.queryByRole("dialog")).not.toBeInTheDocument();
 });

-it("lets a new user inspect example evidence and return to setup without starting an investigation", async () => {
+it("offers the interactive demo without starting an investigation", async () => {
  window.history.replaceState({}, "", "/lens/");
  testQueryClient.clear();
  vi.mocked(apiClient.get).mockImplementation(async (path) => {
    if (path === "/lens") return { lenses: [], workers: [], tracing_enabled: false };
    return { traces: false, requests: false };
  });
+  const onDemo = vi.fn();
  const user = userEvent.setup();
-  renderWithProviders(<LensView accessToken="test" />);
-
-  await user.click(await screen.findByRole("button", { name: "View an example" }));
-  const example = within(screen.getByRole("dialog", { name: "Example investigation" }));
-  expect(example.getByRole("heading", { name: "Failed lookups leave customers without answers" })).toBeVisible();
-  const evidence = example.getByText(/Where is my order\?/);
-  expect(evidence).not.toBeVisible();
-  await user.click(example.getByText("See the trace"));
-  expect(evidence).toBeVisible();
-  expect(example.getByText(/Service unavailable/)).toBeVisible();
-  await user.click(example.getByText("See the trace"));
-  expect(evidence).not.toBeVisible();
-
-  await user.click(example.getByRole("button", { name: "Close" }));
-  await waitFor(() => expect(screen.queryByRole("dialog")).not.toBeInTheDocument());
-  expect(screen.getByRole("link", { name: "Set up traces" })).toBeVisible();
-  expect(screen.getByRole("button", { name: "Connect worker" })).toBeDisabled();
-  expect(screen.getByRole("button", { name: "New investigation" })).toBeDisabled();
-
-  await user.click(screen.getByRole("button", { name: "View an example" }));
-  expect(screen.getByRole("dialog", { name: "Example investigation" })).toBeVisible();
-  expect(screen.getByText(/Where is my order\?/)).not.toBeVisible();
-  await user.keyboard("{Escape}");
-  await waitFor(() => expect(screen.queryByRole("dialog")).not.toBeInTheDocument());
-  expect(screen.getByRole("button", { name: "View an example" })).toBeVisible();
+  renderWithProviders(<LensView accessToken="test" onDemo={onDemo} />);
+  await user.click(await screen.findByRole("button", { name: "Preview sample" }));
+  expect(onDemo).toHaveBeenCalledOnce();
  expect(apiClient.post).not.toHaveBeenCalled();
 });

@ -276,13 +255,14 @@ it("guides a first-time administrator into worker connection and lens setup", as
    return { traces: true, requests: false, data: [] };
  });
  const user = userEvent.setup();
-  renderWithProviders(<LensView accessToken="test" />);
+  renderWithProviders(<LensView accessToken="test" onDemo={vi.fn()} />);
  const guide = within(await screen.findByRole("region", { name: "Find what needs attention" }));
  expect(apiClient.get).toHaveBeenCalledWith("/lens/activity/available", { accessToken: "test" });
  expect(await guide.findByRole("link", { name: "View traces" })).toHaveAttribute(
    "href",
    expect.stringMatching(/^\/ui\/lens\/?\?tab=traces$/),
  );
+  expect(await guide.findByRole("button", { name: "Preview sample" })).toBeVisible();
  await user.click(guide.getByRole("button", { name: "Connect worker" }));
  const connection = within(await screen.findByRole("dialog", { name: "Connect a worker" }));
  expect(connection.getByRole("button", { name: "Get install command" })).toBeVisible();
@ -305,6 +285,7 @@ it("guides a first-time administrator into worker connection and lens setup", as
    });
  });
  await waitFor(() => expect(guide.getByRole("button", { name: "New investigation" })).toBeEnabled());
+  expect(guide.queryByRole("button", { name: "Preview sample" })).not.toBeInTheDocument();
  await user.click(guide.getByRole("button", { name: "New investigation" }));
  expect(await screen.findByRole("dialog", { name: "Which activity should we investigate?" })).toBeVisible();
 });
--- a/ui/litellm-dashboard/src/app/(dashboard)/lens/_components/LensView.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/lens/_components/LensView.tsx
@ -1,4 +1,5 @@
 "use client";
+import { useLensDemo } from "@/components/lens/LensDemoContext";

 import type { components } from "@/lib/http/schema";
 import { useEffect, useState } from "react";
@ -28,7 +29,7 @@ import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/ui/tabs";
 import { Sheet, SheetContent, SheetHeader, SheetTitle, SheetDescription } from "@/components/ui/sheet";
 import { Popover, PopoverContent, PopoverTitle, PopoverTrigger } from "@/components/ui/popover";
 import { LensFinding } from "./LensFinding";
-import { apiClient } from "@/components/networking";
+import { apiClient as liveApiClient } from "@/components/networking";
 import { TracePanel } from "./TracePanel";
 import { LensSetup } from "./LensSetup";
 import { LensRuns } from "./LensRuns";
@ -37,13 +38,7 @@ import { WorkerSetup } from "./WorkerSetup";
 import { useAnalysisKeyInfo } from "./AnalysisKeyDetails";
 import { uiHref } from "@/utils/uiHref";
 import { ApiError } from "@/lib/http/client";
-import {
-  InvestigationList,
-  InvestigationExample,
-  MonitoringSetup,
-  InvestigationSummary,
-  InvestigationFailure,
-} from "./LensOverview";
+import { InvestigationList, MonitoringSetup, InvestigationSummary, InvestigationFailure } from "./LensOverview";
 import { LensWelcome } from "./LensWelcome";
 import {
  workerConnected,
@ -70,10 +65,19 @@ function emptyFindingTitle(active: boolean, scanned: boolean, status?: string) {
  return scanned ? "No matching findings" : "Ready for the first analysis";
 }

-export function LensView({ accessToken, readOnly = false }: { accessToken: string; readOnly?: boolean }) {
+export function LensView({
+  accessToken,
+  readOnly = false,
+  onDemo,
+}: {
+  accessToken: string;
+  readOnly?: boolean;
+  onDemo?: () => void;
+}) {
+  const demo = useLensDemo();
+  const apiClient = demo?.client ?? liveApiClient;
  const client = useQueryClient();
  const [workerSetup, setWorkerSetup] = useState(false);
-  const [showExample, setShowExample] = useState(false);
  const [monitoring, setMonitoring] = useState(false);
  const [now, setNow] = useState(Date.now);
  useEffect(() => {
@ -85,6 +89,7 @@ export function LensView({ accessToken, readOnly = false }: { accessToken: strin
    queryKey: key,
    queryFn: () => apiClient.get<LensList>("/lens", { accessToken }),
    refetchInterval: (current) => {
+      if (demo) return false;
      const running = current.state.data?.lenses.some((item) =>
        item.jobs.some((job) => ["queued", "running"].includes(job.status)),
      );
@ -100,7 +105,10 @@ export function LensView({ accessToken, readOnly = false }: { accessToken: strin
    queryFn: () =>
      apiClient.get<{ data: import("./lensData").AnalysisModelInfo[] }>("/model_group/info", { accessToken }),
  });
-  const [selected, setSelected] = useQueryState("lens", parseAsString.withOptions({ history: "push" }));
+  const [liveSelected, setLiveSelected] = useQueryState("lens", parseAsString.withOptions({ history: "push" }));
+  const [demoSelected, setDemoSelected] = useState<string | null>(null);
+  const selected = demo ? demoSelected : liveSelected;
+  const setSelected = demo ? setDemoSelected : setLiveSelected;
  const [editing, setEditing] = useState<"new" | "edit" | "duplicate" | null>(null);
  const [batchId, setBatchId] = useState("latest");
  const [historyOffset, setHistoryOffset] = useState(0);
@ -146,7 +154,7 @@ export function LensView({ accessToken, readOnly = false }: { accessToken: strin
    queryKey: ["lens-activity-available", accessToken],
    queryFn: () => apiClient.get<{ traces: boolean; requests: boolean }>("/lens/activity/available", { accessToken }),
    enabled: loaded,
-    refetchInterval: 5000,
+    refetchInterval: demo ? (false as const) : 5000,
  };
  const activity = useQuery(activityOptions);
  const tracesReady = activity.data?.traces === true && !activity.error;
@ -157,7 +165,7 @@ export function LensView({ accessToken, readOnly = false }: { accessToken: strin
    queryKey: ["lens-history", lens?.id, historyOffset, accessToken],
    enabled: !!lens,
    queryFn: () => apiClient.get<Job[]>(`/lens/${lens?.id}/runs`, { accessToken, query: { offset: historyOffset } }),
-    refetchInterval: 10000,
+    refetchInterval: demo ? (false as const) : 10000,
  };
  const history = useQuery(historyQuery);
  const historical = useQuery({
@ -297,7 +305,7 @@ export function LensView({ accessToken, readOnly = false }: { accessToken: strin
          }}
          onConnect={() => setWorkerSetup(true)}
          onCreate={() => setEditing("new")}
-          onExample={() => setShowExample(true)}
+          onDemo={activity.isSuccess && !ready ? onDemo : undefined}
        />
      )}
      {showReadiness && !ready && (
@ -687,7 +695,6 @@ export function LensView({ accessToken, readOnly = false }: { accessToken: strin
          }
        />
      )}
-      {showExample && <InvestigationExample onClose={() => setShowExample(false)} />}
      {monitoring && lens && (
        <MonitoringSetup
          settings={lens.settings}
--- a/ui/litellm-dashboard/src/app/(dashboard)/lens/_components/LensWelcome.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/lens/_components/LensWelcome.tsx
@ -1,6 +1,7 @@
 import Link from "next/link";
-import { Check, ArrowRight, Loader2 } from "lucide-react";
+import { Check, Loader2 } from "lucide-react";
 import { Button, buttonVariants } from "@/components/ui/button";
+import { LensPreviewButton } from "@/components/lens/LensPreviewButton";
 import { uiHref } from "@/utils/uiHref";

 export function LensWelcome({
@ -13,7 +14,7 @@ export function LensWelcome({
  onConnect,
  onCreate,
  onRetry,
-  onExample,
+  onDemo,
 }: {
  tracesReady: boolean;
  requestsReady?: boolean;
@ -24,7 +25,7 @@ export function LensWelcome({
  onConnect: () => void;
  onCreate: () => void;
  onRetry: () => void;
-  onExample: () => void;
+  onDemo?: () => void;
 }) {
  const activityReady = tracesReady || requestsReady;
  const workerReady = activityReady && connected;
@ -39,16 +40,14 @@ export function LensWelcome({
    className: "col-start-2 w-fit sm:col-start-auto",
  });
  return (
-    <section aria-labelledby="lens-welcome" className="max-w-3xl py-4 sm:py-6">
+    <section aria-labelledby="lens-welcome" className="max-w-3xl pb-6">
+      {onDemo && <LensPreviewButton onClick={onDemo} />}
      <h2 id="lens-welcome" className="text-xl font-semibold tracking-tight">
        Find what needs attention
      </h2>
      <p className="mt-2 max-w-lg text-sm leading-6 text-muted-foreground">
        Check how your agents behave. Get findings you can trace back to what happened.
      </p>
-      <Button variant="link" className="mt-3 h-auto px-0 text-sm" onClick={onExample}>
-        View an example <ArrowRight className="size-3.5" />
-      </Button>
      <ol className="mt-8 divide-y border-y">
        <li className="grid grid-cols-[28px_minmax(0,1fr)] items-center gap-x-4 gap-y-3 py-5 sm:grid-cols-[28px_minmax(0,1fr)_auto]">
          <Step number={1} complete={activityReady} checking={checking} active={!activityReady} />
--- a/ui/litellm-dashboard/src/app/(dashboard)/lens/_components/LensWorkspace.integration.test.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/lens/_components/LensWorkspace.integration.test.tsx
@ -0,0 +1,137 @@
+import { fireEvent, screen, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { chooseSelectOption, renderWithProviders, testQueryClient } from "@/../tests/test-utils";
+import { LensWorkspace } from "./LensWorkspace";
+import { createLensDemoData } from "./lensDemoData";
+
+const network = vi.fn<typeof fetch>();
+beforeEach(() => {
+  testQueryClient.clear();
+  vi.stubGlobal("fetch", network);
+  network.mockReset();
+  network.mockImplementation(async (input) => {
+    const path = new URL(String(input), "http://localhost").pathname;
+    if (path === "/v1/traces") return Response.json({ detail: "Tracing is not enabled" }, { status: 501 });
+    if (path === "/lens") return Response.json({ lenses: [], workers: [], tracing_enabled: false });
+    return Response.json({ data: [], traces: false, requests: false });
+  });
+});
+
+describe("Lens interactive demo", () => {
+  it("opens without tracing, filters sample runs, and restores the live view without mixing data", async () => {
+    const user = userEvent.setup();
+    const onUrlUpdate = vi.fn();
+    renderWithProviders(<LensWorkspace accessToken="live-token" userRole="Internal User" readOnly={false} />, {
+      onUrlUpdate,
+    });
+    expect(await screen.findByText("Enable tracing")).toBeVisible();
+    await user.click(screen.getByRole("button", { name: "Preview sample" }));
+    expect(await screen.findByText("Where is order #1042?")).toBeVisible();
+    expect(screen.getByText("You’re viewing demo data")).toBeVisible();
+    expect(screen.queryByRole("button", { name: "Set up tracing" })).not.toBeInTheDocument();
+    network.mockClear();
+    await user.click(screen.getByRole("button", { name: "Refresh", exact: true }));
+    expect(screen.getByText("Where is order #1042?")).toBeVisible();
+    fireEvent.change(screen.getByPlaceholderText("Search input or trace ID"), { target: { value: "headphones" } });
+    expect(screen.getByText("Can I return my headphones?")).toBeVisible();
+    expect(screen.queryByText("Where is order #1042?")).not.toBeInTheDocument();
+    fireEvent.change(screen.getByRole("textbox", { name: "Search runs" }), { target: { value: "" } });
+    await chooseSelectOption(user, screen.getByRole("combobox", { name: "Filter by agent" }), "support_agent");
+    await chooseSelectOption(user, screen.getByRole("combobox", { name: "Filter by status" }), "Failed");
+    expect(within(screen.getByRole("table", { name: "Agent runs" })).getAllByRole("row")).toHaveLength(4);
+    await user.click(screen.getByRole("tab", { name: "Investigations", exact: true }));
+    expect(await screen.findByRole("button", { name: /Support quality/ })).toBeVisible();
+    expect(screen.queryByRole("button", { name: "New investigation" })).not.toBeInTheDocument();
+    expect(network).not.toHaveBeenCalled();
+    expect(onUrlUpdate).not.toHaveBeenCalled();
+    await user.click(screen.getByRole("button", { name: "Exit demo" }));
+    expect(await screen.findByText("Enable tracing")).toBeVisible();
+    expect(screen.queryByText("You’re viewing demo data")).not.toBeInTheDocument();
+    expect(screen.queryByText("Can I return my headphones?")).not.toBeInTheDocument();
+  });
+
+  it("connects findings and history to their original trace without live requests or URL changes", async () => {
+    const user = userEvent.setup();
+    const onUrlUpdate = vi.fn();
+    renderWithProviders(<LensWorkspace accessToken="live-token" userRole="Admin" readOnly={false} />, {
+      searchParams: "?tab=investigations",
+      onUrlUpdate,
+    });
+    await screen.findByRole("button", { name: "Preview sample" });
+    await user.click(screen.getByRole("button", { name: "Preview sample" }));
+    await user.click(await screen.findByRole("button", { name: /Support quality/ }));
+    network.mockClear();
+    await user.click(screen.getByRole("button", { name: /Repeated lookups leave customers without an answer/ }));
+    const finding = screen.getByRole("dialog");
+    expect(within(finding).getByText(/The support agent retries/)).toBeVisible();
+    const summaries = within(finding).getAllByText("support_agent", { exact: true });
+    await user.click(summaries[0]);
+    await user.click(within(finding).getAllByRole("button", { name: /Open original step/ })[0]);
+    expect(await screen.findByRole("complementary", { name: "Span details" })).toHaveTextContent(
+      "I will check that for you.",
+    );
+    await user.click(screen.getByRole("button", { name: "Copy for agent" }));
+    expect(await navigator.clipboard.readText()).toContain("I will check that for you.");
+    expect(await navigator.clipboard.readText()).not.toContain("Authorization");
+    await user.click(screen.getByRole("tab", { name: "Attributes" }));
+    expect(await screen.findByText("gen_ai.agent.name")).toBeVisible();
+    await user.click(
+      within(screen.getByRole("dialog", { name: "Original run" })).getByRole("button", { name: "Close", exact: true }),
+    );
+    await user.click(within(screen.getByRole("dialog")).getByRole("button", { name: "Close", exact: true }));
+    await user.click(screen.getByRole("tab", { name: "History" }));
+    await user.click(screen.getAllByRole("button", { name: /runs reviewed/ })[1]);
+    expect(await screen.findByText(/1 linked run · high priority/)).toBeVisible();
+    expect(network).not.toHaveBeenCalled();
+    expect(onUrlUpdate).not.toHaveBeenCalled();
+    await user.click(screen.getByRole("button", { name: "Exit demo" }));
+    expect(await screen.findByRole("heading", { name: "Find what needs attention" })).toBeVisible();
+  });
+
+  it("has no demo entry for existing investigations, populated traces, or connecting another agent", async () => {
+    const user = userEvent.setup();
+    const data = createLensDemoData();
+    const saved = data.lenses[0];
+    network.mockImplementation(async (input) => {
+      const path = new URL(String(input), "http://localhost").pathname;
+      if (path === "/lens") return Response.json({ lenses: [saved], workers: [], tracing_enabled: true });
+      if (path.endsWith("/runs")) return Response.json(saved.jobs);
+      if (path === "/v1/traces") return Response.json({ data: data.runs.map((run) => run.trace.summary) });
+      return Response.json({ data: [], traces: true, requests: false });
+    });
+    renderWithProviders(<LensWorkspace accessToken="live-token" userRole="Admin" readOnly={false} />, {
+      searchParams: `?tab=investigations&lens=${saved.id}`,
+    });
+    expect(await screen.findByRole("heading", { name: saved.settings.name })).toBeVisible();
+    expect(screen.queryByRole("button", { name: "Preview sample" })).not.toBeInTheDocument();
+    await user.click(within(screen.getByRole("tablist", { name: "Lens" })).getByRole("tab", { name: "Traces" }));
+    expect(await screen.findByText("Where is order #1042?")).toBeVisible();
+    expect(screen.queryByRole("button", { name: "Preview sample" })).not.toBeInTheDocument();
+    await user.click(screen.getByRole("button", { name: "Set up tracing" }));
+    expect(await screen.findByRole("heading", { name: "Connect another agent" })).toBeVisible();
+    expect(screen.queryByRole("button", { name: "Preview sample" })).not.toBeInTheDocument();
+  });
+
+  it("shows the header preview only for the active tab that still needs setup", async () => {
+    const user = userEvent.setup();
+    const saved = createLensDemoData().lenses[0];
+    network.mockImplementation(async (input) => {
+      const path = new URL(String(input), "http://localhost").pathname;
+      if (path === "/lens") return Response.json({ lenses: [saved], workers: [], tracing_enabled: false });
+      if (path.endsWith("/runs")) return Response.json(saved.jobs);
+      if (path === "/v1/traces") return Response.json({ detail: "Tracing is not enabled" }, { status: 501 });
+      return Response.json({ data: [], traces: false, requests: false });
+    });
+    renderWithProviders(<LensWorkspace accessToken="live-token" userRole="Admin" readOnly={false} />);
+    expect(await screen.findByRole("button", { name: "Preview sample" })).toBeVisible();
+    const tabs = within(screen.getByRole("tablist", { name: "Lens" }));
+    await user.click(tabs.getByRole("tab", { name: "Investigations" }));
+    expect(await screen.findByRole("button", { name: new RegExp(saved.settings.name) })).toBeVisible();
+    expect(screen.queryByRole("button", { name: "Preview sample" })).not.toBeInTheDocument();
+    await user.click(tabs.getByRole("tab", { name: "Traces" }));
+    await user.click(await screen.findByRole("button", { name: "Preview sample" }));
+    expect(await screen.findByRole("table", { name: "Agent runs" })).toBeVisible();
+    expect(screen.queryByRole("button", { name: "Preview sample" })).not.toBeInTheDocument();
+  });
+});
--- a/ui/litellm-dashboard/src/app/(dashboard)/lens/_components/LensWorkspace.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/lens/_components/LensWorkspace.tsx
@ -0,0 +1,117 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { Aperture } from "lucide-react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { parseAsString, parseAsStringLiteral, useQueryState } from "nuqs";
+import AgentTracesPage from "@/components/view_logs/TraceView/AgentTracesPage";
+import { DemoNotice } from "@/components/shared/DemoNotice";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
+import { LensDemoContext, useLensDemo } from "@/components/lens/LensDemoContext";
+import { LensPreviewTarget } from "@/components/lens/LensPreviewButton";
+import { isProxyAdminRole, isProxyAdminTierRole } from "@/utils/roles";
+import { LensView } from "./LensView";
+import { createLensDemo } from "./lensDemoData";
+
+type Tab = "traces" | "investigations";
+type WorkspaceProps = { accessToken: string; userRole: string; readOnly: boolean };
+
+export function LensWorkspace(props: WorkspaceProps) {
+  const [demoTab, setDemoTab] = useState<Tab | null>(null);
+  return demoTab ? (
+    <DemoSession initialTab={demoTab} onExit={() => setDemoTab(null)} />
+  ) : (
+    <LensContent {...props} onDemo={setDemoTab} />
+  );
+}
+
+function DemoSession({ initialTab, onExit }: { initialTab: Tab; onExit: () => void }) {
+  const [demo] = useState(createLensDemo);
+  const [client] = useState(
+    () => new QueryClient({ defaultOptions: { queries: { retry: false, staleTime: Infinity } } }),
+  );
+  useEffect(
+    () => () => {
+      client.clear();
+    },
+    [client],
+  );
+  return (
+    <LensDemoContext.Provider value={demo}>
+      <QueryClientProvider client={client}>
+        <LensContent accessToken="lens-demo" userRole="" readOnly initialTab={initialTab} onExit={onExit} />
+      </QueryClientProvider>
+    </LensDemoContext.Provider>
+  );
+}
+
+function LensContent({
+  accessToken,
+  userRole,
+  readOnly,
+  initialTab = "traces",
+  onDemo,
+  onExit,
+}: WorkspaceProps & { initialTab?: Tab; onDemo?: (tab: Tab) => void; onExit?: () => void }) {
+  const demo = useLensDemo();
+  const [tab, setTab] = useQueryState(
+    "tab",
+    parseAsStringLiteral(["traces", "investigations"]).withOptions({ history: "push" }),
+  );
+  const [lensId] = useQueryState("lens", parseAsString);
+  const [demoTab, setDemoTab] = useState(initialTab);
+  const [previewTarget, setPreviewTarget] = useState<HTMLDivElement | null>(null);
+  const defaultTab = lensId ? "investigations" : "traces";
+  const activeTab = demo ? demoTab : tab ?? defaultTab;
+  const openDemo = onDemo ? () => onDemo(activeTab) : undefined;
+  return (
+    <LensPreviewTarget.Provider value={previewTarget}>
+      <main className="flex w-full min-w-0 flex-1 flex-col gap-5 p-6 md:p-8">
+        <div className="flex min-h-9 flex-wrap items-center justify-between gap-3">
+          <h1 className="flex items-center gap-2 text-2xl font-semibold tracking-tight">
+            <Aperture aria-hidden="true" className="size-7" strokeWidth={1.75} />
+            Lens
+          </h1>
+          <div ref={setPreviewTarget} />
+        </div>
+        {demo && <DemoNotice onExit={onExit} />}
+        <Tabs
+          value={activeTab}
+          onValueChange={(value) => (demo ? setDemoTab(value as Tab) : void setTab(value as Tab))}
+          className="min-h-0 flex-1 gap-4"
+        >
+          <TabsList variant="line" aria-label="Lens" className="w-full justify-start gap-6 border-b px-0">
+            <TabsTrigger value="traces" className="flex-none px-0">
+              Traces
+            </TabsTrigger>
+            <TabsTrigger value="investigations" className="flex-none px-0">
+              Investigations
+            </TabsTrigger>
+          </TabsList>
+          <TabsContent value="traces" keepMounted className="min-h-0">
+            <AgentTracesPage
+              accessToken={accessToken}
+              isActive={activeTab === "traces"}
+              readOnly={readOnly}
+              canMintTracingKey={!demo && isProxyAdminRole(userRole)}
+              onDemo={activeTab === "traces" ? openDemo : undefined}
+            />
+          </TabsContent>
+          <TabsContent value="investigations" keepMounted={!!demo}>
+            {demo || isProxyAdminTierRole(userRole) ? (
+              <LensView
+                accessToken={accessToken}
+                readOnly={readOnly || !isProxyAdminRole(userRole)}
+                onDemo={activeTab === "investigations" ? openDemo : undefined}
+              />
+            ) : (
+              <p className="py-6 text-sm text-muted-foreground">
+                Investigations require proxy administrator access. You can still view your traces.
+              </p>
+            )}
+          </TabsContent>
+        </Tabs>
+      </main>
+    </LensPreviewTarget.Provider>
+  );
+}
--- a/ui/litellm-dashboard/src/app/(dashboard)/lens/_components/WorkerSetup.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/lens/_components/WorkerSetup.tsx
@ -21,7 +21,7 @@ import { AnalysisKey, AnalysisAccessFields, createAnalysisKey, type AnalysisAcce
 import type { LensList, WorkerCreated } from "./lensData";

 export const LENS_WORKER_IMAGE =
-  "ghcr.io/berriai/litellm-lens-worker@sha256:67eba741c1b97c749975c5c38e2370a603e1105babc908d613c1b79d7b995393";
+  "ghcr.io/berriai/litellm-lens-worker@sha256:44f0597c7583dcfef999ece9a8bc02cfeb9f0f5167a1221cee3bd10b1b79271b";

 function initialProxyAddress(): string {
  const url = new URL(proxyBaseUrl || serverRootPath, window.location.origin);
--- a/ui/litellm-dashboard/src/app/(dashboard)/lens/_components/lensData.test.ts
+++ b/ui/litellm-dashboard/src/app/(dashboard)/lens/_components/lensData.test.ts
@ -58,6 +58,28 @@ const job: Job = {
 };

 describe("Analysis progress", () => {
+  it.each(["Collecting executions", "Reading executions"])(
+    "does not turn an unreported run count into zero runs during %s",
+    (stage) => {
+      expect(analysisProgress({ ...job, stage })).toEqual({
+        step: -1,
+        title: "Preparing activity",
+        done: 0,
+        total: 0,
+        detail: "Loading the runs selected for this investigation.",
+      });
+    },
+  );
+
+  it("shows the selected count as soon as the worker reports it", () => {
+    expect(analysisProgress({ ...job, coverage: { ...coverage, selected: 7 } })).toMatchObject({
+      step: 0,
+      done: 0,
+      total: 7,
+      detail: "0 of 7 selected runs reviewed",
+    });
+  });
+
  it("measures review progress against the sample, not all eligible runs", () => {
    const expected = { step: 0, done: 7, total: 20, detail: "7 of 20 selected runs reviewed" };
    expect(
--- a/ui/litellm-dashboard/src/app/(dashboard)/lens/_components/lensData.ts
+++ b/ui/litellm-dashboard/src/app/(dashboard)/lens/_components/lensData.ts
@ -108,6 +108,15 @@ export function analysisProgress(job: Job) {
        : `${investigated} patterns checked against the original activity`,
    };
  }
+  if (!selected) {
+    return {
+      step: -1,
+      title: "Preparing activity",
+      done: 0,
+      total: 0,
+      detail: "Loading the runs selected for this investigation.",
+    };
+  }
  return {
    step: 0,
    title: "Reviewing activity",
--- a/ui/litellm-dashboard/src/app/(dashboard)/lens/_components/lensDemoData.test.ts
+++ b/ui/litellm-dashboard/src/app/(dashboard)/lens/_components/lensDemoData.test.ts
@ -0,0 +1,55 @@
+import { describe, expect, it, vi } from "vitest";
+import { createLensDemo, createLensDemoData } from "./lensDemoData";
+import type { TracePage } from "@/components/view_logs/TraceView/traceTypes";
+import { evidenceTarget } from "./lensData";
+
+describe("Lens demo data", () => {
+  it("links every finding to the quoted original step and assessed run", () => {
+    const data = createLensDemoData();
+    for (const lens of data.lenses) {
+      for (const job of lens.jobs) {
+        for (const finding of job.findings ?? []) {
+          for (const evidence of finding.evidence) {
+            const target = evidenceTarget(evidence.execution_id);
+            const run = data.runs.find(({ trace }) => trace.summary.trace_id === target?.id);
+            const step = run?.details.find((span) => span.span_id === evidence.span_id);
+            expect(step?.output).toContain(evidence.quote);
+            expect(job.sample?.executions.map((execution) => execution.id)).toContain(evidence.execution_id);
+            expect(
+              job.assessments.find((assessment) => assessment.execution_id === evidence.execution_id)?.[
+                finding.kind === "issue" ? "issue_checks" : "pattern_checks"
+              ],
+            ).toContain(finding.check_id);
+          }
+        }
+      }
+    }
+  });
+
+  it("keeps trace totals, timestamps, and agent names consistent", () => {
+    const data = createLensDemoData();
+    for (const { trace } of data.runs) {
+      expect(trace.summary.span_count).toBe(trace.spans.length);
+      expect(trace.summary.agent_names).toContain(trace.agents[0].name);
+      expect(trace.summary.error_count).toBe(trace.spans.filter((span) => span.status === "error").length);
+      for (const span of trace.spans) {
+        expect(span.start_offset_ms + span.duration_ms).toBeLessThanOrEqual(trace.summary.duration_ms);
+      }
+    }
+  });
+
+  it("filters time windows locally and rejects writes or unknown reads without network access", async () => {
+    const network = vi.spyOn(globalThis, "fetch");
+    const now = Date.now();
+    const { client } = createLensDemo(now);
+    const all = await client.get<TracePage>("/v1/traces");
+    const recent = await client.get<TracePage>("/v1/traces", { query: { start_ms: now - 3600_000, end_ms: now } });
+    expect(recent.data.length).toBeGreaterThan(0);
+    expect(recent.data.length).toBeLessThan(all.data.length);
+    expect(recent.data.every((trace) => Date.parse(trace.start_time) >= now - 3600_000)).toBe(true);
+    await expect(client.post("/lens", { body: {} })).rejects.toMatchObject({ status: 403 });
+    await expect(client.get("/lens/real-investigation")).rejects.toMatchObject({ status: 404 });
+    expect(network).not.toHaveBeenCalled();
+    network.mockRestore();
+  });
+});
--- a/ui/litellm-dashboard/src/app/(dashboard)/lens/_components/lensDemoData.ts
+++ b/ui/litellm-dashboard/src/app/(dashboard)/lens/_components/lensDemoData.ts
@ -0,0 +1,483 @@
+import { createApiClient } from "@/lib/http/client";
+import type { LensDemo } from "@/components/lens/LensDemoContext";
+import type { Trace, Span, SpanDetail } from "@/components/view_logs/TraceView/traceTypes";
+import type { Lens, Finding, Job, Settings } from "./lensData";
+
+type Scenario = {
+  agent: string;
+  question: string;
+  tool: string;
+  result: string;
+  answer: string;
+  failed?: boolean;
+};
+
+const scenarios: Scenario[] = [
+  {
+    agent: "support_agent",
+    question: "Where is order #1042?",
+    tool: "lookup_order",
+    result: "Order service timed out",
+    answer: "I will check that for you.",
+    failed: true,
+  },
+  {
+    agent: "research_agent",
+    question: "Which database should we use for analytics?",
+    tool: "search_docs",
+    result: "Column stores are designed for analytical queries. No comparative benchmark is available.",
+    answer: "The column store is 40% faster than the row store for your workload.",
+  },
+  {
+    agent: "support_agent",
+    question: "Can I return my headphones?",
+    tool: "lookup_return_policy",
+    result: "Returns are accepted within 30 days. This order was delivered 10 days ago.",
+    answer: "Yes. Your order is eligible for a return. I can help you start it.",
+  },
+  {
+    agent: "release_agent",
+    question: "Is the checkout release ready to ship?",
+    tool: "read_test_results",
+    result: "Checkout: 120 passed, 0 failed. Rollback plan approved.",
+    answer: "All 120 checkout tests passed and the rollback plan is approved. The release is ready.",
+  },
+  {
+    agent: "support_agent",
+    question: "My order #1088 has not arrived",
+    tool: "lookup_order",
+    result: "Order service timed out",
+    answer: "I will check that for you.",
+    failed: true,
+  },
+  {
+    agent: "research_agent",
+    question: "How long do we retain audit logs?",
+    tool: "search_docs",
+    result: "Audit log retention is 90 days on the current plan.",
+    answer: "Audit logs are retained for 90 days, according to the plan documentation.",
+  },
+  {
+    agent: "release_agent",
+    question: "Review the search release",
+    tool: "read_test_results",
+    result: "Search: 86 passed, 1 failed. Unicode query regression remains open.",
+    answer: "Hold the release. The Unicode query regression is still failing.",
+  },
+  {
+    agent: "support_agent",
+    question: "Update the address on order #1091",
+    tool: "lookup_order",
+    result: "Order #1091 has not shipped. Address changes are allowed.",
+    answer: "Your order has not shipped. Please confirm the new delivery address.",
+  },
+  {
+    agent: "research_agent",
+    question: "Can this plan store data in Europe?",
+    tool: "search_docs",
+    result: "Regional availability is not documented for this plan.",
+    answer: "I could not verify European data residency for this plan. Please confirm with support before choosing it.",
+  },
+  {
+    agent: "support_agent",
+    question: "Check the delivery date for order #1107",
+    tool: "lookup_order",
+    result: "Order service timed out",
+    answer: "The order service is unavailable. I can connect you to support instead.",
+    failed: true,
+  },
+  {
+    agent: "release_agent",
+    question: "Summarize the authentication release checks",
+    tool: "read_test_results",
+    result: "Authentication: 214 passed, 0 failed. Security review approved.",
+    answer: "All 214 tests passed and the security review is approved.",
+  },
+  {
+    agent: "research_agent",
+    question: "Does the API support request retries?",
+    tool: "search_docs",
+    result: "Retry requests with exponential backoff after a 429 or 503 response.",
+    answer: "Yes. Use exponential backoff for 429 and 503 responses, as documented.",
+  },
+];
+
+const executionId = (traceId: string) => btoa(JSON.stringify(["traces", "", traceId]));
+const iso = (time: number) => new Date(time).toISOString();
+
+function makeTrace(scene: Scenario, index: number, now: number) {
+  const traceId = (index + 1).toString(16).padStart(32, "0");
+  const spanId = (step: number) => `${index + 1}${step}`.padStart(16, "0");
+  const toolCount = scene.failed && index !== 9 ? 3 : 1;
+  const duration = toolCount === 3 ? 6340 : 3180 + index * 137;
+  const base: Span = {
+    agent: scene.agent,
+    duration_ms: duration,
+    error: null,
+    error_truncated: false,
+    framework: "",
+    input_preview: scene.question,
+    input_tokens: 0,
+    output_tokens: 0,
+    litellm_request_id: null,
+    model: null,
+    name: scene.agent,
+    parent_span_id: null,
+    span_id: spanId(0),
+    spend: null,
+    start_offset_ms: 0,
+    status: "ok",
+    type: "agent",
+  };
+  const tools: Span[] = Array.from({ length: toolCount }, (_, i) => ({
+    ...base,
+    span_id: spanId(i + 1),
+    parent_span_id: base.span_id,
+    name: scene.tool,
+    type: "tool",
+    start_offset_ms: 150 + i * 1600,
+    duration_ms: scene.failed ? 1500 : 340,
+    status: scene.failed ? "error" : "ok",
+    error: scene.failed ? scene.result : null,
+  }));
+  const model: Span = {
+    ...base,
+    span_id: spanId(5),
+    parent_span_id: base.span_id,
+    name: "Generate response",
+    type: "llm",
+    model: "demo-chat-model",
+    start_offset_ms: toolCount * 1600,
+    duration_ms: 1200,
+    input_tokens: 520 + index * 41,
+    output_tokens: 48 + index * 7,
+    spend: 0.003 + index * 0.0002,
+  };
+  const trace: Trace = {
+    summary: {
+      agent_count: 1,
+      agent_invocations: 1,
+      agent_names: [scene.agent],
+      duration_ms: duration,
+      error_count: scene.failed ? toolCount : 0,
+      frameworks: [],
+      input_preview: scene.question,
+      input_tokens: model.input_tokens,
+      output_tokens: model.output_tokens,
+      llm_calls: 1,
+      models: [model.model!],
+      name: scene.agent,
+      service: "demo-agents",
+      span_count: toolCount + 2,
+      spend: model.spend,
+      start_time: iso(now - (index + 1) * 35 * 60_000),
+      status: scene.failed ? "error" : "ok",
+      tool_calls: toolCount,
+      trace_id: traceId,
+    },
+    agents: [
+      {
+        name: scene.agent,
+        parent_agent: null,
+        duration_ms: duration,
+        invocations: 1,
+        llm_calls: 1,
+        tool_calls: toolCount,
+        spend: model.spend,
+      },
+    ],
+    spans: [base, ...tools, model],
+  };
+  const details: SpanDetail[] = trace.spans.map((span) => ({
+    span_id: span.span_id,
+    input:
+      span.type === "tool"
+        ? JSON.stringify({ query: scene.question })
+        : JSON.stringify([{ role: "user", content: scene.question }]),
+    output: span.type === "tool" ? scene.result : JSON.stringify([{ role: "assistant", content: scene.answer }]),
+    attributes: {
+      "gen_ai.agent.name": scene.agent,
+      "service.name": "demo-agents",
+      demo: "true",
+      ...(span.model ? { "gen_ai.request.model": span.model } : {}),
+    },
+  }));
+  return { trace, details };
+}
+
+export function createLensDemoData(now = Date.now()) {
+  const runs = scenarios.map((scene, index) => makeTrace(scene, index, now));
+  const finding = ({
+    id,
+    check,
+    title,
+    description,
+    suggestion,
+    indices,
+    kind = "issue",
+  }: {
+    id: string;
+    check: string;
+    title: string;
+    description: string;
+    suggestion: string;
+    indices: number[];
+    kind?: Finding["kind"];
+  }): Finding => ({
+    id,
+    check_id: check,
+    title,
+    description,
+    suggestion,
+    kind,
+    priority: kind === "issue" ? "high" : "low",
+    status: "open",
+    reason: "",
+    revision: 1,
+    first_seen: iso(now - 86_400_000),
+    last_seen: iso(now - 300_000),
+    limitation: "",
+    occurrences: indices.map((i) => executionId(runs[i].trace.summary.trace_id)),
+    evidence: indices.map((i) => ({
+      execution_id: executionId(runs[i].trace.summary.trace_id),
+      span_id: runs[i].trace.spans.at(-1)!.span_id,
+      quote: scenarios[i].answer,
+      role: "support",
+    })),
+  });
+  const findingInputs: Parameters<typeof finding>[0][] = [
+    {
+      id: "failed-lookups",
+      check: "recover",
+      title: "Repeated lookups leave customers without an answer",
+      description:
+        "The support agent retries the same unavailable order service three times, then promises to check without answering or offering a handoff.",
+      suggestion: "After repeated failures, explain the problem and offer a handoff.",
+      indices: [0, 4],
+    },
+    {
+      id: "safe-handoff",
+      check: "recover",
+      title: "A clear handoff helps when the order service is unavailable",
+      description:
+        "The agent explains the service outage and offers a support handoff instead of promising an answer it cannot provide.",
+      suggestion: "Keep this fallback for unavailable services.",
+      indices: [9],
+      kind: "pattern",
+    },
+    {
+      id: "unsupported-claim",
+      check: "grounding",
+      title: "Performance claim has no supporting benchmark",
+      description:
+        "The answer claims a 40% performance improvement, but the retrieved documentation contains no comparative benchmark.",
+      suggestion: "Require a benchmark source for numeric performance claims, or remove the comparison.",
+      indices: [1],
+    },
+    {
+      id: "uncertainty",
+      check: "grounding",
+      title: "Missing information is acknowledged",
+      description:
+        "When documentation does not establish regional availability, the agent says so and asks the user to verify it.",
+      suggestion: "Keep stating when a source does not answer the question.",
+      indices: [8],
+      kind: "pattern",
+    },
+    {
+      id: "release-blocked",
+      check: "release",
+      title: "Failing checks correctly block the release",
+      description: "The release agent identifies an unresolved regression and recommends holding the release.",
+      suggestion: "Continue requiring passing checks before recommending a release.",
+      indices: [6],
+      kind: "pattern",
+    },
+  ];
+  const findings = findingInputs.map(finding);
+  const definitions = [
+    {
+      id: "support",
+      name: "Support quality",
+      agent: "support_agent",
+      check: "recover",
+      context:
+        "Answer the customer's question using order information. If a tool fails, explain the problem and offer a handoff.",
+      instruction: "Look for repeated failed calls and conversations that end without an answer or a handoff.",
+    },
+    {
+      id: "research",
+      name: "Research accuracy",
+      agent: "research_agent",
+      check: "grounding",
+      context: "Answer questions using verified documentation. Acknowledge missing information.",
+      instruction: "Find claims that are not supported by the retrieved sources.",
+    },
+    {
+      id: "release",
+      name: "Release readiness",
+      agent: "release_agent",
+      check: "release",
+      context: "Review test results and recommend a release only when all required checks pass.",
+      instruction: "Check whether failed tests are acknowledged before a release recommendation.",
+    },
+  ];
+  const lenses: Lens[] = definitions.map((definition) => {
+    const settings: Settings = {
+      name: definition.name,
+      agent_name: definition.agent,
+      context: definition.context,
+      checks: [{ id: definition.check, instruction: definition.instruction, enabled: true }],
+      source: "traces",
+      service: "",
+      filters: [],
+      team_id: "",
+      execution_ids: [],
+      lookback_hours: 24,
+      sample_size: 0,
+      sample_percent: 100,
+      concurrency: 8,
+      monthly_budget: 100,
+      interval_minutes: 30,
+      enabled: false,
+      model: "demo-analysis-model",
+    };
+    const executions = runs
+      .filter(({ trace }) => trace.summary.name === definition.agent)
+      .map(({ trace }) => ({
+        id: executionId(trace.summary.trace_id),
+        trace_ref: "",
+        metadata: [],
+        root_seen: true,
+        service: trace.summary.service,
+        source: "traces" as const,
+        trace_id: trace.summary.trace_id,
+        team_id: "",
+        name: trace.summary.name,
+        start_time: trace.summary.start_time,
+        span_count: trace.summary.span_count,
+      }));
+    const relevant = findings.filter((f) => f.check_id === definition.check);
+    const jobs: Job[] = [0, 1].map((day) => {
+      const sample = day === 0 ? executions : executions.slice(1);
+      const selectedIds = new Set(sample.map((item) => item.id));
+      const snapshot = relevant
+        .map((f) => ({
+          ...f,
+          occurrences: f.occurrences.filter((id) => selectedIds.has(id)),
+          evidence: f.evidence.filter((e) => selectedIds.has(e.execution_id)),
+        }))
+        .filter((f) => f.occurrences.length > 0);
+      return {
+        id: `${definition.id}-scan-${day}`,
+        findings: snapshot,
+        settings,
+        revision: 1,
+        assessments: sample.map((e) => ({
+          execution_id: e.id,
+          cannot_assess: false,
+          issue_checks: snapshot.some((f) => f.kind === "issue" && f.occurrences.includes(e.id))
+            ? [definition.check]
+            : [],
+          pattern_checks: snapshot.some((f) => f.kind === "pattern" && f.occurrences.includes(e.id))
+            ? [definition.check]
+            : [],
+        })),
+        attempts: 1,
+        error: "",
+        cost: sample.length * 0.012,
+        coverage: {
+          eligible: sample.length,
+          selected: sample.length,
+          screened: sample.length,
+          investigated: sample.length,
+          inconclusive: 0,
+          grouping_batches: 1,
+          grouped_batches: 1,
+          candidates: snapshot.length,
+          partial: 0,
+          unassessable: 0,
+        },
+        status: "completed",
+        stage: "Complete",
+        created_at: iso(now - 330_000 - day * 60_000),
+        finished_at: iso(now - 300_000 - day * 60_000),
+        start: iso(now - 86_400_000),
+        end: iso(now - 300_000 - day * 60_000),
+        sample: { eligible: sample.length, selected: sample.length, executions: sample },
+      };
+    });
+    return {
+      id: definition.id,
+      version: 1,
+      revision: 1,
+      spent: jobs.reduce((sum, job) => sum + job.cost, 0),
+      scope: { all_teams: true, api_key_hash: "", team_id: "" },
+      settings,
+      created_at: iso(now - 2 * 86_400_000),
+      next_run_at: iso(now),
+      budget_month: iso(now).slice(0, 7),
+      findings: relevant,
+      jobs,
+    };
+  });
+  return { runs, lenses };
+}
+
+function readDemoTrace(data: ReturnType<typeof createLensDemoData>, url: URL): unknown {
+  const parts = url.pathname.split("/").filter(Boolean);
+  if (parts[0] !== "v1" || parts[1] !== "traces") return undefined;
+  if (!parts[2]) {
+    const start = Number(url.searchParams.get("start_ms") ?? 0);
+    const end = Number(url.searchParams.get("end_ms") ?? Infinity);
+    return {
+      data: data.runs
+        .map((run) => run.trace.summary)
+        .filter((trace) => Date.parse(trace.start_time) >= start && Date.parse(trace.start_time) <= end),
+      next_cursor: null,
+    };
+  }
+  const run = data.runs.find(({ trace }) => trace.summary.trace_id === parts[2]);
+  if (!parts[3]) return run?.trace;
+  if (parts[3] === "spans" && !parts[5]) return run?.details.find((span) => span.span_id === parts[4]);
+  if (parts[3] === "spans" && parts[5] === "error") {
+    const span = run?.trace.spans.find((item) => item.span_id === parts[4]);
+    return span
+      ? { span_id: span.span_id, message: span.error ?? "", total_chars: span.error?.length ?? 0, next_cursor: null }
+      : undefined;
+  }
+  return undefined;
+}
+
+export function createLensDemo(now = Date.now()): LensDemo {
+  const data = createLensDemoData(now);
+  const read = (url: URL): unknown => {
+    const parts = url.pathname.split("/").filter(Boolean);
+    if (url.pathname === "/lens") return { lenses: data.lenses, workers: [], tracing_enabled: true };
+    if (url.pathname === "/lens/activity/available") return { traces: true, requests: false };
+    if (url.pathname === "/models" || url.pathname === "/model_group/info") return { data: [] };
+    if (parts[0] === "lens" && parts[2] === "runs") {
+      const jobs = data.lenses.find((lens) => lens.id === parts[1])?.jobs;
+      return parts[3]
+        ? jobs?.find((job) => job.id === parts[3])
+        : jobs?.slice(Number(url.searchParams.get("offset") ?? 0));
+    }
+    return readDemoTrace(data, url);
+  };
+  return {
+    client: createApiClient({
+      getBaseUrl: () => "https://lens-demo.invalid",
+      fetchImpl: async (input, init) => {
+        if (init?.method !== "GET") return Response.json({ detail: "Demo data is read-only" }, { status: 403 });
+        const result = read(new URL(String(input)));
+        return result === undefined
+          ? Response.json({ detail: "This item is not in the demo" }, { status: 404 })
+          : Response.json(result);
+      },
+    }),
+    copyTrace: (traceId, spanId) => {
+      const run = data.runs.find(({ trace }) => trace.summary.trace_id === traceId);
+      return JSON.stringify(spanId ? run?.details.find((span) => span.span_id === spanId) : run, null, 2);
+    },
+  };
+}
--- a/ui/litellm-dashboard/src/app/(dashboard)/lens/page.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/lens/page.tsx
@ -1,60 +1,10 @@
 "use client";

 import useAuthorized from "@/app/(dashboard)/hooks/useAuthorized";
-import { Aperture } from "lucide-react";
-import { parseAsString, parseAsStringLiteral, useQueryState } from "nuqs";
-import AgentTracesPage from "@/components/view_logs/TraceView/AgentTracesPage";
-import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
-import { isProxyAdminRole, isProxyAdminTierRole } from "@/utils/roles";
-import { LensView } from "./_components/LensView";
+import { LensWorkspace } from "./_components/LensWorkspace";

 export default function LensPage() {
  const { accessToken, userRole, isViewOnly } = useAuthorized();
-  const [tab, setTab] = useQueryState(
-    "tab",
-    parseAsStringLiteral(["traces", "investigations"]).withOptions({ history: "push" }),
-  );
-  const [lensId] = useQueryState("lens", parseAsString);
-  const defaultTab = lensId ? "investigations" : "traces";
-  const activeTab = tab ?? defaultTab;
  if (!accessToken) return null;
-  return (
-    <main className="flex w-full min-w-0 flex-1 flex-col gap-5 p-6 md:p-8">
-      <h1 className="flex items-center gap-2 text-2xl font-semibold tracking-tight">
-        <Aperture aria-hidden="true" className="size-7" strokeWidth={1.75} />
-        Lens
-      </h1>
-      <Tabs
-        value={activeTab}
-        onValueChange={(value) => void setTab(value as "traces" | "investigations")}
-        className="min-h-0 flex-1 gap-4"
-      >
-        <TabsList variant="line" aria-label="Lens" className="w-full justify-start gap-6 border-b px-0">
-          <TabsTrigger value="traces" className="flex-none px-0">
-            Traces
-          </TabsTrigger>
-          <TabsTrigger value="investigations" className="flex-none px-0">
-            Investigations
-          </TabsTrigger>
-        </TabsList>
-        <TabsContent value="traces" keepMounted className="min-h-0">
-          <AgentTracesPage
-            accessToken={accessToken}
-            isActive={activeTab === "traces"}
-            readOnly={isViewOnly}
-            canMintTracingKey={isProxyAdminRole(userRole ?? "")}
-          />
-        </TabsContent>
-        <TabsContent value="investigations">
-          {isProxyAdminTierRole(userRole ?? "") ? (
-            <LensView accessToken={accessToken} readOnly={isViewOnly || !isProxyAdminRole(userRole ?? "")} />
-          ) : (
-            <p className="py-6 text-sm text-muted-foreground">
-              Investigations require proxy administrator access. You can still view your traces.
-            </p>
-          )}
-        </TabsContent>
-      </Tabs>
-    </main>
-  );
+  return <LensWorkspace accessToken={accessToken} userRole={userRole ?? ""} readOnly={isViewOnly} />;
 }
--- a/ui/litellm-dashboard/src/app/(dashboard)/roi-calculator/_components/ROICalculatorView.integration.test.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/roi-calculator/_components/ROICalculatorView.integration.test.tsx
@ -249,6 +249,32 @@ describe("ROICalculatorView", () => {
    expect(screen.getAllByText("Connect GitHub to get started")).toHaveLength(1);
  });

+  it("clearly identifies the sample report and returns to setup when exiting", async () => {
+    const emptySettings = { ...settings, has_github_token: false, ready: false, repos: [], estimator_model: "" };
+    vi.mocked(apiClient.get).mockImplementation((path: string, options) => {
+      if (path === "/roi-calculator/settings") return Promise.resolve(emptySettings);
+      if (path === "/roi-calculator/report") {
+        return Promise.resolve({ report: options?.query?.mode === "demo" ? { ...summary, mode: "demo" } : null });
+      }
+      return Promise.resolve(idleStatus);
+    });
+
+    render(<ROICalculatorView accessToken="token" />);
+    fireEvent.click(await screen.findByRole("button", { name: "Preview sample report" }));
+
+    expect(await screen.findByText("You’re viewing demo data")).toBeVisible();
+    expect(screen.getByText("Spend per estimated engineering hour")).toBeVisible();
+    expect(screen.queryByRole("button", { name: "Run analysis" })).not.toBeInTheDocument();
+    expect(screen.queryByRole("tab", { name: "Settings" })).not.toBeInTheDocument();
+
+    fireEvent.click(screen.getByRole("button", { name: "Exit demo" }));
+
+    expect(screen.getByRole("heading", { name: "Connect GitHub to get started" })).toBeVisible();
+    expect(screen.queryByText("You’re viewing demo data")).not.toBeInTheDocument();
+    expect(apiClient.post).not.toHaveBeenCalled();
+    expect(apiClient.put).not.toHaveBeenCalled();
+  });
+
  it("returns to Overview and shows the last sync time when completion is polled from Settings", async () => {
    const runningStatus = {
      ...idleStatus,
--- a/ui/litellm-dashboard/src/app/(dashboard)/roi-calculator/_components/ROICalculatorView.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/roi-calculator/_components/ROICalculatorView.tsx
@ -5,6 +5,7 @@ import { Calculator, RefreshCw } from "lucide-react";

 import { apiClient } from "@/components/networking";
 import { PageHeader } from "@/components/shared/PageHeader";
+import { DemoNotice } from "@/components/shared/DemoNotice";
 import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert";
 import { Button } from "@/components/ui/button";
 import { Card, CardContent } from "@/components/ui/card";
@ -222,6 +223,13 @@ export default function ROICalculatorView({
      <PageHeader
        icon={<Calculator />}
        title="ROI Calculator"
+        titleAction={
+          !liveSummary && showLiveStatus ? (
+            <Button variant="outline" onClick={() => void previewSample()}>
+              Preview sample report
+            </Button>
+          ) : undefined
+        }
        subtitle={
          <>
            {summary
@ -238,22 +246,7 @@ export default function ROICalculatorView({
          </>
        }
      />
-      {!liveSummary && showLiveStatus && (
-        <Button variant="outline" onClick={() => void previewSample()}>
-          Preview sample report
-        </Button>
-      )}
-      {sampleSummary && (
-        <Alert>
-          <AlertTitle>Sample report</AlertTitle>
-          <AlertDescription>
-            Example data only. No GitHub or model requests were made.
-            <Button variant="link" onClick={() => setSampleSummary(null)}>
-              Use my data
-            </Button>
-          </AlertDescription>
-        </Alert>
-      )}
+      {sampleSummary && <DemoNotice onExit={() => setSampleSummary(null)} />}
      {liveSummary && showLiveStatus && (
        <p className="text-xs text-muted-foreground">
          {status.next_update ? `Next update ${formatSyncedAt(status.next_update)}` : scheduleLabel}
--- a/ui/litellm-dashboard/src/components/lens/LensDemoContext.tsx
+++ b/ui/litellm-dashboard/src/components/lens/LensDemoContext.tsx
@ -0,0 +1,12 @@
+"use client";
+
+import { createContext, useContext } from "react";
+import type { ApiClient } from "@/lib/http/client";
+
+export interface LensDemo {
+  client: ApiClient;
+  copyTrace: (traceId: string, spanId?: string) => string;
+}
+
+export const LensDemoContext = createContext<LensDemo | null>(null);
+export const useLensDemo = () => useContext(LensDemoContext);
--- a/ui/litellm-dashboard/src/components/lens/LensPreviewButton.tsx
+++ b/ui/litellm-dashboard/src/components/lens/LensPreviewButton.tsx
@ -0,0 +1,18 @@
+"use client";
+
+import { createContext, useContext } from "react";
+import { createPortal } from "react-dom";
+import { Button } from "@/components/ui/button";
+
+export const LensPreviewTarget = createContext<HTMLElement | null | undefined>(undefined);
+
+export function LensPreviewButton({ onClick }: { onClick: () => void }) {
+  const target = useContext(LensPreviewTarget);
+  const button = (
+    <Button variant="outline" onClick={onClick}>
+      Preview sample
+    </Button>
+  );
+  if (target === null) return null;
+  return target ? createPortal(button, target) : button;
+}
--- a/ui/litellm-dashboard/src/components/shared/DemoNotice.tsx
+++ b/ui/litellm-dashboard/src/components/shared/DemoNotice.tsx
@ -0,0 +1,16 @@
+import { Info } from "lucide-react";
+import { Button } from "@/components/ui/button";
+
+export function DemoNotice({ onExit }: { onExit?: () => void }) {
+  return (
+    <div className="flex flex-wrap items-center justify-between gap-3 rounded-lg border border-info/20 bg-info/10 px-4 py-3">
+      <p role="status" className="flex items-center gap-2 text-sm font-medium text-info">
+        <Info aria-hidden="true" className="size-4 shrink-0" />
+        You’re viewing demo data
+      </p>
+      <Button variant="outline" size="sm" onClick={onExit}>
+        Exit demo
+      </Button>
+    </div>
+  );
+}
--- a/ui/litellm-dashboard/src/components/shared/PageHeader.tsx
+++ b/ui/litellm-dashboard/src/components/shared/PageHeader.tsx
@ -14,11 +14,12 @@ interface PageHeaderProps {
  subtitle: React.ReactNode;
  icon: React.ReactNode;
  primaryAction?: React.ReactNode;
+  titleAction?: React.ReactNode;
  tabs?: React.ReactNode | ((slots: EmbeddedTabsSlots) => React.ReactNode);
  utilities?: React.ReactNode;
 }

-export function PageHeader({ title, subtitle, icon, primaryAction, tabs, utilities }: PageHeaderProps) {
+export function PageHeader({ title, subtitle, icon, primaryAction, titleAction, tabs, utilities }: PageHeaderProps) {
  const leadingControls =
    primaryAction == null ? null : (
      <div className="flex h-9 items-center">
@ -31,14 +32,17 @@ export function PageHeader({ title, subtitle, icon, primaryAction, tabs, utiliti

  return (
    <div>
-      <div className="flex items-center gap-2.5">
-        <span
-          aria-hidden="true"
-          className="flex size-5 flex-none items-center justify-center text-foreground [&_svg]:size-5 [&_svg]:stroke-[1.75]"
-        >
-          {icon}
-        </span>
-        <h1 className="text-2xl font-semibold tracking-tight text-foreground">{title}</h1>
+      <div className="flex flex-wrap items-center justify-between gap-3">
+        <div className="flex items-center gap-2.5">
+          <span
+            aria-hidden="true"
+            className="flex size-5 flex-none items-center justify-center text-foreground [&_svg]:size-5 [&_svg]:stroke-[1.75]"
+          >
+            {icon}
+          </span>
+          <h1 className="text-2xl font-semibold tracking-tight text-foreground">{title}</h1>
+        </div>
+        {titleAction}
      </div>
      <p className="mt-1.5 text-sm text-muted-foreground">{subtitle}</p>

--- a/ui/litellm-dashboard/src/components/view_logs/TraceView/AgentTracesPage.tsx
+++ b/ui/litellm-dashboard/src/components/view_logs/TraceView/AgentTracesPage.tsx
@ -1,4 +1,5 @@
 "use client";
+import { useLensDemo } from "@/components/lens/LensDemoContext";

 import moment from "moment";
 import { useMemo, useState } from "react";
@ -13,12 +14,15 @@ export default function AgentTracesPage({
  isActive = true,
  readOnly = false,
  canMintTracingKey = false,
+  onDemo,
 }: {
  accessToken: string;
  isActive?: boolean;
  readOnly?: boolean;
  canMintTracingKey?: boolean;
+  onDemo?: () => void;
 }) {
+  const demo = useLensDemo();
  const [rangeHours, setRangeHours] = useState(DEFAULT_RANGE_HOURS);
  const [live, setLive] = useState(true);
  const [anchor, setAnchor] = useState(() => moment());
@ -36,16 +40,17 @@ export default function AgentTracesPage({
  };

  return (
-    <div className="flex min-h-0 flex-1 flex-col pt-3">
+    <div className="flex min-h-0 flex-1 flex-col">
      <AgentTracesSection
        accessToken={accessToken}
        isActive={isActive}
        startTime={startTime}
        endTime={endTime}
        isCustomDate={false}
-        isLiveTail={live}
+        isLiveTail={live && !demo}
        readOnly={readOnly}
        canMintTracingKey={canMintTracingKey}
+        onDemo={onDemo}
        timeControls={{ rangeHours, onRangeHoursChange: changeRange, onLiveChange: setLive }}
      />
    </div>
--- a/ui/litellm-dashboard/src/components/view_logs/TraceView/AgentTracesSection.integration.test.tsx
+++ b/ui/litellm-dashboard/src/components/view_logs/TraceView/AgentTracesSection.integration.test.tsx
@ -0,0 +1,509 @@
+import { act, fireEvent, screen, waitFor, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { ApiError } from "@/lib/http/client";
+
+import { chooseSelectOption, renderWithProviders, testQueryClient } from "../../../../tests/test-utils";
+import traceList from "./__fixtures__/trace_list.json";
+import AgentTracesPage from "./AgentTracesPage";
+import { AgentTracesSection, type TimeControls } from "./AgentTracesSection";
+import type { TracePage, TraceSummary } from "./traceTypes";
+
+vi.mock("../../networking", () => ({
+  apiClient: { get: vi.fn(), post: vi.fn() },
+  agentTraceListCall: vi.fn(),
+  sendOtlpTraceCall: vi.fn(),
+  agentTraceCall: vi.fn(),
+  agentTraceSpanCall: vi.fn(),
+  getProxyBaseUrl: () => "http://localhost:4000",
+}));
+
+vi.mock("./TraceDrawer", () => ({
+  RunView: ({ traceId, onBack }: { traceId: string; onBack: () => void }) => (
+    <div data-testid="run-view">
+      run {traceId}
+      <button onClick={onBack}>back</button>
+    </div>
+  ),
+}));
+
+import { agentTraceListCall, apiClient } from "../../networking";
+
+const runs = (traceList as TracePage).data as TraceSummary[];
+
+const renderSection = () =>
+  renderWithProviders(
+    <AgentTracesSection
+      accessToken="sk-test"
+      isActive
+      startTime="2026-09-29T00:00"
+      endTime="2026-09-30T00:00"
+      isCustomDate={false}
+      isLiveTail={false}
+      onDemo={vi.fn()}
+    />,
+  );
+
+// A UTC-pinned day around the fixture runs (2026-09-30 ~06:43 UTC), so they land in the same bucket in any timezone.
+const renderWindowed = (timeControls?: TimeControls) =>
+  renderWithProviders(
+    <AgentTracesSection
+      accessToken="sk-test"
+      isActive
+      startTime="2026-09-30T00:00Z"
+      endTime="2026-10-01T00:00Z"
+      isCustomDate
+      isLiveTail={false}
+      timeControls={timeControls}
+    />,
+  );
+
+const bucketRunCounts = () =>
+  screen.getAllByTestId("timeline-bucket").map((bucket) => Number(bucket.getAttribute("data-runs")));
+
+describe("AgentTracesSection", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  beforeEach(() => {
+    vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockReturnValue({
+      left: 0,
+      width: 600,
+      top: 0,
+      height: 56,
+      right: 600,
+      bottom: 56,
+      x: 0,
+      y: 0,
+      toJSON: () => ({}),
+    } as DOMRect);
+    testQueryClient.clear();
+    vi.mocked(agentTraceListCall).mockReset();
+    vi.mocked(apiClient.get).mockResolvedValue({ data: [] });
+  });
+
+  it.each([
+    [401, "Your session is no longer valid. Sign out and sign in again."],
+    [403, "Your account does not have access to these traces."],
+  ])("stops live polling after HTTP %s and explains how to recover", async (status, message) => {
+    vi.useFakeTimers();
+    vi.mocked(agentTraceListCall).mockRejectedValue(new ApiError("Private token details", Number(status), {}));
+    renderWithProviders(
+      <AgentTracesSection
+        accessToken="sk-test"
+        isActive
+        startTime="2026-09-29T00:00"
+        endTime="2026-09-30T00:00"
+        isCustomDate={false}
+        isLiveTail
+      />,
+    );
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(60_000);
+    });
+    expect(screen.getByText(`Could not load runs: ${message}`)).toBeVisible();
+    expect(screen.queryByText(/Private token details/)).not.toBeInTheDocument();
+    expect(agentTraceListCall).toHaveBeenCalledOnce();
+    expect(screen.getByTestId("runs-footer")).toHaveTextContent("Update failed");
+  });
+
+  it("renders the setup snippet when the proxy answers 501", async () => {
+    vi.mocked(agentTraceListCall).mockRejectedValue(
+      new ApiError("Agent tracing is not enabled", 501, { detail: "Agent tracing is not enabled" }),
+    );
+    renderSection();
+
+    const card = await screen.findByTestId("tracing-setup-card");
+    expect(card).toHaveTextContent("Tracing is not enabled");
+    expect(screen.getByRole("button", { name: "Preview sample" })).toBeVisible();
+    expect(card).toHaveTextContent("type: clickhouse");
+    expect(card).toHaveTextContent("url: os.environ/CLICKHOUSE_URL");
+    expect(screen.getByRole("button", { name: "Check setup" })).toBeEnabled();
+    expect(card).not.toHaveTextContent(/langsmith/i);
+    expect(card).toHaveTextContent("ClickHouse and proxy setup");
+    expect(card).toHaveTextContent("Ask your proxy administrator");
+  });
+
+  it("shows the waiting guide when tracing is on but no runs have arrived", async () => {
+    vi.mocked(agentTraceListCall).mockResolvedValue({ ...(traceList as TracePage), data: [] });
+    renderSection();
+
+    const card = await screen.findByTestId("tracing-setup-card");
+    expect(card).toHaveTextContent("Connect your agent");
+    expect(card).toHaveTextContent("Waiting for your first trace");
+    expect(screen.getByRole("button", { name: "Preview sample" })).toBeVisible();
+    expect(card).not.toHaveTextContent("store: clickhouse");
+  });
+
+  it("keeps the trace list available when traces exist outside the current time window", async () => {
+    vi.mocked(agentTraceListCall).mockResolvedValue({ ...(traceList as TracePage), data: [] });
+    vi.mocked(apiClient.get).mockResolvedValue(traceList);
+    renderSection();
+    expect(await screen.findByText("No runs match these filters.")).toBeVisible();
+    expect(screen.queryByTestId("tracing-setup-card")).not.toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: "Preview sample" })).not.toBeInTheDocument();
+    expect(apiClient.get).toHaveBeenCalledWith("/v1/traces", { accessToken: "sk-test", query: { start_ms: 0 } });
+  });
+
+  it("checks proxy readiness, waits for an agent, and confirms receipt using actual query results", async () => {
+    vi.mocked(agentTraceListCall).mockRejectedValue(new ApiError("Tracing is not enabled", 501, {}));
+    renderSection();
+    const checkSetup = await screen.findByRole("button", { name: "Check setup" });
+    vi.mocked(agentTraceListCall).mockResolvedValue({ ...(traceList as TracePage), data: [] });
+    fireEvent.click(checkSetup);
+    expect(await screen.findByRole("heading", { name: "Connect your agent" })).toBeVisible();
+    expect(screen.getByText("Waiting for your first trace")).toBeVisible();
+    vi.mocked(agentTraceListCall).mockResolvedValue(traceList as TracePage);
+    fireEvent.click(screen.getByRole("button", { name: "Check for traces" }));
+    expect(await screen.findAllByTestId("agent-trace-row")).toHaveLength(runs.length);
+    expect(screen.getByText("Traces received. Select a run to inspect it.")).toBeVisible();
+    expect(screen.queryByRole("button", { name: "Preview sample" })).not.toBeInTheDocument();
+    expect(screen.queryByTestId("tracing-setup-card")).not.toBeInTheDocument();
+  });
+
+  it("keeps setup visible while checking and explains when tracing is still disabled", async () => {
+    const failure = new ApiError("Tracing is not enabled", 501, {});
+    vi.mocked(agentTraceListCall).mockRejectedValue(failure);
+    renderSection();
+    const checkSetup = await screen.findByRole("button", { name: "Check setup" });
+    let rejectCheck: (error: Error) => void = () => {};
+    vi.mocked(agentTraceListCall).mockImplementationOnce(
+      () =>
+        new Promise((_, reject) => {
+          rejectCheck = reject;
+        }),
+    );
+    fireEvent.click(checkSetup);
+    expect(await screen.findByRole("button", { name: "Checking…" })).toBeDisabled();
+    expect(screen.getByRole("heading", { name: "Enable tracing" })).toBeVisible();
+    await act(async () => rejectCheck(failure));
+    expect(await screen.findByText(/Tracing is still unavailable/)).toBeVisible();
+    expect(screen.getByRole("button", { name: "Check setup" })).toBeEnabled();
+  });
+
+  it("keeps received traces and the open drawer visible during subsequent fetches", async () => {
+    vi.mocked(agentTraceListCall).mockRejectedValue(new ApiError("Tracing is not enabled", 501, {}));
+    renderSection();
+    const checkSetup = await screen.findByRole("button", { name: "Check setup" });
+    vi.mocked(agentTraceListCall).mockResolvedValue(traceList as TracePage);
+    fireEvent.click(checkSetup);
+    const rows = await screen.findAllByTestId("agent-trace-row");
+    fireEvent.click(rows[0]);
+    const drawer = screen.getByRole("complementary", { name: "Trace details" });
+
+    let finishRefresh: (page: TracePage) => void = () => {};
+    vi.mocked(agentTraceListCall).mockImplementationOnce(
+      () =>
+        new Promise((resolve) => {
+          finishRefresh = resolve;
+        }),
+    );
+    await act(async () => {
+      void testQueryClient.invalidateQueries({ queryKey: ["agentTraces"] });
+    });
+    expect(await screen.findByText("Updating…")).toBeVisible();
+    expect(screen.getAllByTestId("agent-trace-row")).toHaveLength(runs.length);
+    expect(screen.getByRole("complementary", { name: "Trace details" })).toBe(drawer);
+    expect(screen.queryByTestId("tracing-setup-card")).not.toBeInTheDocument();
+    await act(async () => finishRefresh(traceList as TracePage));
+  });
+
+  it("separates a failed history check from the empty list and retries that check", async () => {
+    vi.mocked(agentTraceListCall).mockResolvedValue({ ...(traceList as TracePage), data: [] });
+    vi.mocked(apiClient.get).mockRejectedValue(new ApiError("History unavailable", 503, {}));
+    renderSection();
+    expect(await screen.findByRole("alert")).toHaveTextContent("Could not check earlier traces. History unavailable");
+    expect(screen.getByText("No runs match these filters.")).toBeVisible();
+    expect(screen.queryByText(/Could not load runs/)).not.toBeInTheDocument();
+
+    vi.mocked(apiClient.get).mockResolvedValue(traceList);
+    fireEvent.click(screen.getByRole("button", { name: "Retry trace check" }));
+    await waitFor(() => expect(screen.queryByRole("alert")).not.toBeInTheDocument());
+    expect(screen.getByText("No runs match these filters.")).toBeVisible();
+    expect(agentTraceListCall).toHaveBeenCalledTimes(1);
+  });
+
+  it("treats a proxy without the trace routes (404) like tracing being off", async () => {
+    vi.mocked(agentTraceListCall).mockRejectedValue(new ApiError("Not Found", 404, { detail: "Not Found" }));
+    renderSection();
+
+    const card = await screen.findByTestId("tracing-setup-card");
+    expect(card).toHaveTextContent("Tracing is not enabled");
+    expect(card).toHaveTextContent("url: os.environ/CLICKHOUSE_URL");
+  });
+
+  it("lists every run with its input, counts and failed column", async () => {
+    vi.mocked(agentTraceListCall).mockResolvedValue(traceList as TracePage);
+    renderSection();
+
+    const rows = await screen.findAllByTestId("agent-trace-row");
+    expect(rows).toHaveLength(runs.length);
+    const lead = rows.find((row) => row.textContent?.includes("Should we store OTEL agent spans"));
+    expect(lead).toBeDefined();
+    const failed = rows.find((row) => row.textContent?.includes("acme-404")) as HTMLElement;
+    expect(within(failed).getByLabelText("2 errors")).toBeInTheDocument();
+    expect(screen.getByText(`${runs.length} runs`)).toBeInTheDocument();
+    expect(screen.getByRole("columnheader", { name: "Cost" })).toBeInTheDocument();
+    expect(within(failed).getByText("—")).toBeInTheDocument();
+  });
+
+  it("shows the spend returned for a run", async () => {
+    vi.mocked(agentTraceListCall).mockResolvedValue({
+      ...(traceList as TracePage),
+      data: [{ ...runs[0], spend: 0.025 }],
+    });
+    renderSection();
+
+    const row = await screen.findByTestId("agent-trace-row");
+    expect(within(row).getByText("$0.03")).toBeInTheDocument();
+  });
+
+  it("filters by input text and by trace id", async () => {
+    vi.mocked(agentTraceListCall).mockResolvedValue(traceList as TracePage);
+    renderSection();
+    await screen.findAllByTestId("agent-trace-row");
+
+    const search = screen.getByLabelText("Search runs");
+    fireEvent.change(search, { target: { value: "acme-404" } });
+    expect(screen.getAllByTestId("agent-trace-row")).toHaveLength(1);
+
+    const lead = runs.find((r) => r.name === "research_lead") as TraceSummary;
+    fireEvent.change(search, { target: { value: lead.trace_id.slice(0, 10) } });
+    const rows = screen.getAllByTestId("agent-trace-row");
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toHaveTextContent("Should we store OTEL agent spans");
+  });
+
+  it("uses recorded agent names for the column and filter even when services are shared", async () => {
+    vi.mocked(agentTraceListCall).mockResolvedValue({
+      ...(traceList as TracePage),
+      data: [
+        ...runs.slice(1).map((run) => ({ ...run, service: "shared-app", agent_names: ["research-agent"] })),
+        { ...runs[0], service: "shared-app", agent_names: ["billing-agent", "review-agent"] },
+      ],
+    });
+    const user = userEvent.setup();
+    renderSection();
+    await screen.findAllByTestId("agent-trace-row");
+
+    expect(screen.getByRole("columnheader", { name: "Agent" })).toBeInTheDocument();
+    const agentFilter = screen.getByRole("combobox", { name: "Filter by agent" });
+    expect(agentFilter).toHaveTextContent("All agents");
+
+    await chooseSelectOption(user, agentFilter, "billing-agent");
+    const rows = screen.getAllByTestId("agent-trace-row");
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toHaveTextContent("billing-agent");
+    expect(rows[0]).not.toHaveTextContent("shared-app");
+
+    await chooseSelectOption(user, agentFilter, "review-agent");
+    expect(screen.getAllByTestId("agent-trace-row")).toHaveLength(1);
+
+    await chooseSelectOption(user, agentFilter, "All agents");
+    expect(screen.getAllByTestId("agent-trace-row")).toHaveLength(runs.length);
+  });
+
+  it("shows each run's agent name with the logo of the SDK that produced it", async () => {
+    vi.mocked(agentTraceListCall).mockResolvedValue({
+      ...(traceList as TracePage),
+      data: [
+        { ...runs[0], agent_names: ["research-bot"], frameworks: ["claude-agent-sdk", "claude-code"] },
+        { ...runs[1], agent_names: [], frameworks: ["claude-code"] },
+        { ...runs[2], frameworks: [] },
+      ],
+    });
+    renderSection();
+    const [sdkRun, cliRun, plainRun] = await screen.findAllByTestId("agent-trace-row");
+    const agentCell = (row: HTMLElement) => within(row).getAllByRole("cell")[1];
+
+    expect(agentCell(sdkRun)).toHaveTextContent(/^research-bot$/);
+    expect(agentCell(sdkRun)).toHaveAttribute("title", "research-bot · Claude Agent SDK");
+    expect(within(sdkRun).getByRole("img", { name: "Claude Agent SDK logo", hidden: true })).toHaveAttribute(
+      "src",
+      expect.stringContaining("anthropic.svg"),
+    );
+    expect(agentCell(cliRun)).toHaveTextContent(/^Claude Code$/);
+    expect(within(plainRun).queryByRole("img", { hidden: true })).not.toBeInTheDocument();
+    expect(agentCell(plainRun)).toHaveTextContent((runs[2].agent_names ?? [runs[2].service]).join(", "));
+  });
+
+  it("opens a run in a side drawer over the list and swaps runs without closing it", async () => {
+    vi.mocked(agentTraceListCall).mockResolvedValue(traceList as TracePage);
+    renderSection();
+    const rows = await screen.findAllByTestId("agent-trace-row");
+
+    fireEvent.click(rows[0]);
+    const drawer = screen.getByRole("complementary", { name: "Trace details" });
+    expect(within(drawer).getByTestId("run-view")).toHaveTextContent(`run ${runs[0].trace_id}`);
+    expect(screen.getByTestId("runs-table")).toBeInTheDocument();
+    expect(rows[0]).toHaveAttribute("aria-selected", "true");
+
+    fireEvent.click(rows[1]);
+    expect(screen.getByRole("complementary", { name: "Trace details" })).toBe(drawer);
+    expect(within(drawer).getByTestId("run-view")).toHaveTextContent(`run ${runs[1].trace_id}`);
+    expect(rows[1]).toHaveAttribute("aria-selected", "true");
+    expect(rows[0]).toHaveAttribute("aria-selected", "false");
+  });
+
+  it("closes the drawer when the open row is clicked again or Escape is pressed", async () => {
+    vi.mocked(agentTraceListCall).mockResolvedValue(traceList as TracePage);
+    renderSection();
+    const rows = await screen.findAllByTestId("agent-trace-row");
+
+    fireEvent.click(rows[0]);
+    fireEvent.click(rows[0]);
+    expect(rows[0]).toHaveAttribute("aria-selected", "false");
+
+    fireEvent.click(rows[1]);
+    fireEvent.keyDown(window, { key: "Escape" });
+    expect(rows[1]).toHaveAttribute("aria-selected", "false");
+  });
+
+  it("moves to the next and previous run with j / k and the header arrows", async () => {
+    vi.mocked(agentTraceListCall).mockResolvedValue(traceList as TracePage);
+    renderSection();
+    const rows = await screen.findAllByTestId("agent-trace-row");
+
+    fireEvent.click(rows[0]);
+    fireEvent.keyDown(window, { key: "j" });
+    expect(screen.getByTestId("run-view")).toHaveTextContent(`run ${runs[1].trace_id}`);
+    fireEvent.keyDown(window, { key: "k" });
+    expect(screen.getByTestId("run-view")).toHaveTextContent(`run ${runs[0].trace_id}`);
+    expect(screen.getByRole("button", { name: "Previous trace (K)" })).toBeDisabled();
+    fireEvent.click(screen.getByRole("button", { name: "Next trace (J)" }));
+    expect(screen.getByTestId("run-view")).toHaveTextContent(`run ${runs[1].trace_id}`);
+  });
+
+  it("plots every loaded run on the timeline", async () => {
+    vi.mocked(agentTraceListCall).mockResolvedValue(traceList as TracePage);
+    renderWindowed();
+    await screen.findAllByTestId("agent-trace-row");
+
+    expect(screen.getByTestId("traces-timeline")).toBeInTheDocument();
+    const counts = bucketRunCounts();
+    expect(counts).toHaveLength(60);
+    expect(counts.reduce((a, b) => a + b, 0)).toBe(runs.length);
+  });
+
+  it("zooms by dragging, resizes and pans the bracket, and clears with Esc", async () => {
+    vi.mocked(agentTraceListCall).mockResolvedValue(traceList as TracePage);
+    renderWindowed();
+    await screen.findAllByTestId("agent-trace-row");
+    const area = screen.getByTestId("timeline-area");
+    const x = (bucket: number) => bucket * 10 + 5;
+    const drag = (target: HTMLElement, from: number, to: number) => {
+      fireEvent.pointerDown(target, { clientX: x(from), pointerId: 1 });
+      fireEvent.pointerMove(area, { clientX: x(to), pointerId: 1 });
+      fireEvent.pointerUp(area, { clientX: x(to), pointerId: 1 });
+    };
+    const rowCount = () => screen.queryAllByTestId("agent-trace-row").length;
+    const withRuns = bucketRunCounts().flatMap((count, i) => (count > 0 ? [i] : []));
+    const first = withRuns[0];
+    // The pan below moves a [0, first] bracket to the far right; it must end up clear of every run.
+    expect(first).toBeGreaterThan(1);
+    expect(first).toBeLessThan(30);
+
+    drag(area, 0, 1);
+    expect(screen.getByTestId("timeline-selection")).toBeInTheDocument();
+    expect(rowCount()).toBe(0);
+
+    drag(screen.getByTestId("timeline-handle-hi"), 1, first);
+    expect(rowCount()).toBeGreaterThan(0);
+
+    drag(screen.getByTestId("timeline-selection"), 1, 1 - first);
+    expect(rowCount()).toBeGreaterThan(0);
+    drag(screen.getByTestId("timeline-selection"), 0, 59);
+    expect(rowCount()).toBe(0);
+
+    fireEvent.keyDown(screen.getByTestId("traces-timeline"), { key: "Escape" });
+    expect(screen.queryByTestId("timeline-selection")).not.toBeInTheDocument();
+    expect(rowCount()).toBe(runs.length);
+  });
+
+  it("clears timeline zoom when refreshed", async () => {
+    vi.mocked(agentTraceListCall).mockResolvedValue(traceList as TracePage);
+    renderWindowed({ rangeHours: 24, onRangeHoursChange: () => {}, onLiveChange: () => {} });
+    await screen.findAllByTestId("agent-trace-row");
+    const area = screen.getByTestId("timeline-area");
+    const x = (bucket: number) => bucket * 10 + 5;
+
+    fireEvent.pointerDown(area, { clientX: x(0), pointerId: 1 });
+    fireEvent.pointerMove(area, { clientX: x(1), pointerId: 1 });
+    fireEvent.pointerUp(area, { clientX: x(1), pointerId: 1 });
+    expect(screen.getByTestId("timeline-selection")).toBeInTheDocument();
+    expect(screen.queryAllByTestId("agent-trace-row")).toHaveLength(0);
+
+    fireEvent.click(screen.getByRole("button", { name: "Refresh" }));
+
+    expect(screen.queryByTestId("timeline-selection")).not.toBeInTheDocument();
+    expect(screen.getAllByTestId("agent-trace-row")).toHaveLength(runs.length);
+  });
+});
+
+describe("AgentTracesPage", () => {
+  beforeEach(() => {
+    testQueryClient.clear();
+    vi.mocked(agentTraceListCall).mockReset();
+    vi.mocked(apiClient.get).mockResolvedValue({ data: [] });
+  });
+
+  it("shows the actual range, switches presets from the popover, and toggles Live", async () => {
+    vi.mocked(agentTraceListCall).mockResolvedValue(traceList as TracePage);
+    renderWithProviders(<AgentTracesPage accessToken="sk-test" />);
+    await screen.findByTestId("runs-table");
+
+    const trigger = screen.getByRole("button", { name: "Time range" });
+    expect(trigger).toHaveTextContent(/ to /);
+    expect(screen.getByTestId("traces-timeline")).toHaveTextContent("Total 1d");
+
+    fireEvent.click(trigger);
+    fireEvent.click(await screen.findByRole("menuitemradio", { name: "Last 7 days" }));
+    expect(await screen.findByText("Total 7d")).toBeInTheDocument();
+    const last = vi.mocked(agentTraceListCall).mock.calls.at(-1)?.[0];
+    expect((last?.endMs ?? 0) - (last?.startMs ?? 0)).toBeGreaterThanOrEqual(7 * 24 * 3600 * 1000 - 60_000);
+
+    const live = screen.getByRole("button", { name: "Live" });
+    expect(live).toHaveAttribute("aria-pressed", "true");
+    fireEvent.click(live);
+    expect(live).toHaveAttribute("aria-pressed", "false");
+    expect(screen.getByRole("button", { name: "Refresh" })).toBeEnabled();
+  });
+
+  it("refreshes the trace list", async () => {
+    vi.mocked(agentTraceListCall).mockResolvedValue(traceList as TracePage);
+    renderWithProviders(<AgentTracesPage accessToken="sk-test" />);
+    await screen.findByTestId("runs-table");
+
+    const callsBeforeRefresh = vi.mocked(agentTraceListCall).mock.calls.length;
+    fireEvent.click(screen.getByRole("button", { name: "Refresh" }));
+
+    await waitFor(() => expect(vi.mocked(agentTraceListCall).mock.calls.length).toBeGreaterThan(callsBeforeRefresh));
+  });
+
+  it("keeps the time controls on an empty range the user picked, instead of showing onboarding", async () => {
+    vi.mocked(agentTraceListCall).mockResolvedValue(traceList as TracePage);
+    renderWithProviders(<AgentTracesPage accessToken="sk-test" />);
+    await screen.findByTestId("runs-table");
+
+    vi.mocked(agentTraceListCall).mockResolvedValue({ ...(traceList as TracePage), data: [] });
+    fireEvent.click(screen.getByRole("button", { name: "Time range" }));
+    fireEvent.click(await screen.findByRole("menuitemradio", { name: "Last hour" }));
+
+    expect(await screen.findByText("No runs match these filters.")).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Time range" })).toBeInTheDocument();
+    expect(screen.queryByTestId("tracing-setup-card")).not.toBeInTheDocument();
+  });
+
+  it("asks the proxy for the last 24 hours by default", async () => {
+    vi.mocked(agentTraceListCall).mockResolvedValue(traceList as TracePage);
+    renderWithProviders(<AgentTracesPage accessToken="sk-test" />);
+    await screen.findByTestId("runs-table");
+
+    const { startMs, endMs } = vi.mocked(agentTraceListCall).mock.calls[0][0];
+    expect(endMs - startMs).toBeGreaterThanOrEqual(24 * 3600 * 1000 - 60_000);
+    expect(endMs - startMs).toBeLessThan(24 * 3600 * 1000 + 120_000);
+  });
+});
--- a/ui/litellm-dashboard/src/components/view_logs/TraceView/AgentTracesSection.test.tsx
+++ b/ui/litellm-dashboard/src/components/view_logs/TraceView/AgentTracesSection.test.tsx
@ -1,330 +1,11 @@
-import { act, fireEvent, screen, waitFor, within } from "@testing-library/react";
-import userEvent from "@testing-library/user-event";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-
-import { ApiError } from "@/lib/http/client";
-
-import { chooseSelectOption, renderWithProviders, testQueryClient } from "../../../../tests/test-utils";
+import { describe, expect, it } from "vitest";
+import { filterRuns } from "./AgentTracesSection";
 import traceList from "./__fixtures__/trace_list.json";
-import AgentTracesPage from "./AgentTracesPage";
-import { AgentTracesSection, filterRuns, type TimeControls } from "./AgentTracesSection";
 import type { TracePage, TraceSummary } from "./traceTypes";

-vi.mock("../../networking", () => ({
-  apiClient: { get: vi.fn(), post: vi.fn() },
-  agentTraceListCall: vi.fn(),
-  sendOtlpTraceCall: vi.fn(),
-  agentTraceCall: vi.fn(),
-  agentTraceSpanCall: vi.fn(),
-  getProxyBaseUrl: () => "http://localhost:4000",
-}));
-
-vi.mock("./TraceDrawer", () => ({
-  RunView: ({ traceId, onBack }: { traceId: string; onBack: () => void }) => (
-    <div data-testid="run-view">
-      run {traceId}
-      <button onClick={onBack}>back</button>
-    </div>
-  ),
-}));
-
-import { agentTraceListCall, apiClient } from "../../networking";
-
 const runs = (traceList as TracePage).data as TraceSummary[];

-const renderSection = () =>
-  renderWithProviders(
-    <AgentTracesSection
-      accessToken="sk-test"
-      isActive
-      startTime="2026-09-29T00:00"
-      endTime="2026-09-30T00:00"
-      isCustomDate={false}
-      isLiveTail={false}
-    />,
-  );
-
-// A UTC-pinned day around the fixture runs (2026-09-30 ~06:43 UTC), so they land in the same bucket in any timezone.
-const renderWindowed = (timeControls?: TimeControls) =>
-  renderWithProviders(
-    <AgentTracesSection
-      accessToken="sk-test"
-      isActive
-      startTime="2026-09-30T00:00Z"
-      endTime="2026-10-01T00:00Z"
-      isCustomDate
-      isLiveTail={false}
-      timeControls={timeControls}
-    />,
-  );
-
-const bucketRunCounts = () =>
-  screen.getAllByTestId("timeline-bucket").map((bucket) => Number(bucket.getAttribute("data-runs")));
-
-describe("AgentTracesSection", () => {
-  afterEach(() => {
-    vi.useRealTimers();
-    vi.restoreAllMocks();
-  });
-
-  beforeEach(() => {
-    vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockReturnValue({
-      left: 0,
-      width: 600,
-      top: 0,
-      height: 56,
-      right: 600,
-      bottom: 56,
-      x: 0,
-      y: 0,
-      toJSON: () => ({}),
-    } as DOMRect);
-    testQueryClient.clear();
-    vi.mocked(agentTraceListCall).mockReset();
-    vi.mocked(apiClient.get).mockResolvedValue({ data: [] });
-  });
-
-  it.each([
-    [401, "Your session is no longer valid. Sign out and sign in again."],
-    [403, "Your account does not have access to these traces."],
-  ])("stops live polling after HTTP %s and explains how to recover", async (status, message) => {
-    vi.useFakeTimers();
-    vi.mocked(agentTraceListCall).mockRejectedValue(new ApiError("Private token details", Number(status), {}));
-    renderWithProviders(
-      <AgentTracesSection
-        accessToken="sk-test"
-        isActive
-        startTime="2026-09-29T00:00"
-        endTime="2026-09-30T00:00"
-        isCustomDate={false}
-        isLiveTail
-      />,
-    );
-    await act(async () => {
-      await vi.advanceTimersByTimeAsync(60_000);
-    });
-    expect(screen.getByText(`Could not load runs: ${message}`)).toBeVisible();
-    expect(screen.queryByText(/Private token details/)).not.toBeInTheDocument();
-    expect(agentTraceListCall).toHaveBeenCalledOnce();
-    expect(screen.getByTestId("runs-footer")).toHaveTextContent("Update failed");
-  });
-
-  it("renders the setup snippet when the proxy answers 501", async () => {
-    vi.mocked(agentTraceListCall).mockRejectedValue(
-      new ApiError("Agent tracing is not enabled", 501, { detail: "Agent tracing is not enabled" }),
-    );
-    renderSection();
-
-    const card = await screen.findByTestId("tracing-setup-card");
-    expect(card).toHaveTextContent("Tracing is not enabled");
-    expect(card).toHaveTextContent("type: clickhouse");
-    expect(card).toHaveTextContent("url: os.environ/CLICKHOUSE_URL");
-    expect(screen.getByRole("button", { name: "Check setup" })).toBeEnabled();
-    expect(card).not.toHaveTextContent(/langsmith/i);
-    expect(card).toHaveTextContent("ClickHouse and proxy setup");
-    expect(card).toHaveTextContent("Ask your proxy administrator");
-  });
-
-  it("shows the waiting guide when tracing is on but no runs have arrived", async () => {
-    vi.mocked(agentTraceListCall).mockResolvedValue({ ...(traceList as TracePage), data: [] });
-    renderSection();
-
-    const card = await screen.findByTestId("tracing-setup-card");
-    expect(card).toHaveTextContent("Connect your agent");
-    expect(card).toHaveTextContent("Waiting for your first trace");
-    expect(card).not.toHaveTextContent("store: clickhouse");
-  });
-
-  it("keeps the trace list available when traces exist outside the current time window", async () => {
-    vi.mocked(agentTraceListCall).mockResolvedValue({ ...(traceList as TracePage), data: [] });
-    vi.mocked(apiClient.get).mockResolvedValue(traceList);
-    renderSection();
-    expect(await screen.findByText("No runs match these filters.")).toBeVisible();
-    expect(screen.queryByTestId("tracing-setup-card")).not.toBeInTheDocument();
-    expect(apiClient.get).toHaveBeenCalledWith("/v1/traces", { accessToken: "sk-test", query: { start_ms: 0 } });
-  });
-
-  it("checks proxy readiness, waits for an agent, and confirms receipt using actual query results", async () => {
-    vi.mocked(agentTraceListCall).mockRejectedValue(new ApiError("Tracing is not enabled", 501, {}));
-    renderSection();
-    const checkSetup = await screen.findByRole("button", { name: "Check setup" });
-    vi.mocked(agentTraceListCall).mockResolvedValue({ ...(traceList as TracePage), data: [] });
-    fireEvent.click(checkSetup);
-    expect(await screen.findByRole("heading", { name: "Connect your agent" })).toBeVisible();
-    expect(screen.getByText("Waiting for your first trace")).toBeVisible();
-    vi.mocked(agentTraceListCall).mockResolvedValue(traceList as TracePage);
-    fireEvent.click(screen.getByRole("button", { name: "Check for traces" }));
-    expect(await screen.findAllByTestId("agent-trace-row")).toHaveLength(runs.length);
-    expect(screen.getByText("Traces received. Select a run to inspect it.")).toBeVisible();
-    expect(screen.queryByTestId("tracing-setup-card")).not.toBeInTheDocument();
-  });
-
-  it("keeps setup visible while checking and explains when tracing is still disabled", async () => {
-    const failure = new ApiError("Tracing is not enabled", 501, {});
-    vi.mocked(agentTraceListCall).mockRejectedValue(failure);
-    renderSection();
-    const checkSetup = await screen.findByRole("button", { name: "Check setup" });
-    let rejectCheck: (error: Error) => void = () => {};
-    vi.mocked(agentTraceListCall).mockImplementationOnce(
-      () =>
-        new Promise((_, reject) => {
-          rejectCheck = reject;
-        }),
-    );
-    fireEvent.click(checkSetup);
-    expect(await screen.findByRole("button", { name: "Checking…" })).toBeDisabled();
-    expect(screen.getByRole("heading", { name: "Enable tracing" })).toBeVisible();
-    await act(async () => rejectCheck(failure));
-    expect(await screen.findByText(/Tracing is still unavailable/)).toBeVisible();
-    expect(screen.getByRole("button", { name: "Check setup" })).toBeEnabled();
-  });
-
-  it("keeps received traces and the open drawer visible during subsequent fetches", async () => {
-    vi.mocked(agentTraceListCall).mockRejectedValue(new ApiError("Tracing is not enabled", 501, {}));
-    renderSection();
-    const checkSetup = await screen.findByRole("button", { name: "Check setup" });
-    vi.mocked(agentTraceListCall).mockResolvedValue(traceList as TracePage);
-    fireEvent.click(checkSetup);
-    const rows = await screen.findAllByTestId("agent-trace-row");
-    fireEvent.click(rows[0]);
-    const drawer = screen.getByRole("complementary", { name: "Trace details" });
-
-    let finishRefresh: (page: TracePage) => void = () => {};
-    vi.mocked(agentTraceListCall).mockImplementationOnce(
-      () =>
-        new Promise((resolve) => {
-          finishRefresh = resolve;
-        }),
-    );
-    await act(async () => {
-      void testQueryClient.invalidateQueries({ queryKey: ["agentTraces"] });
-    });
-    expect(await screen.findByText("Updating…")).toBeVisible();
-    expect(screen.getAllByTestId("agent-trace-row")).toHaveLength(runs.length);
-    expect(screen.getByRole("complementary", { name: "Trace details" })).toBe(drawer);
-    expect(screen.queryByTestId("tracing-setup-card")).not.toBeInTheDocument();
-    await act(async () => finishRefresh(traceList as TracePage));
-  });
-
-  it("separates a failed history check from the empty list and retries that check", async () => {
-    vi.mocked(agentTraceListCall).mockResolvedValue({ ...(traceList as TracePage), data: [] });
-    vi.mocked(apiClient.get).mockRejectedValue(new ApiError("History unavailable", 503, {}));
-    renderSection();
-    expect(await screen.findByRole("alert")).toHaveTextContent("Could not check earlier traces. History unavailable");
-    expect(screen.getByText("No runs match these filters.")).toBeVisible();
-    expect(screen.queryByText(/Could not load runs/)).not.toBeInTheDocument();
-
-    vi.mocked(apiClient.get).mockResolvedValue(traceList);
-    fireEvent.click(screen.getByRole("button", { name: "Retry trace check" }));
-    await waitFor(() => expect(screen.queryByRole("alert")).not.toBeInTheDocument());
-    expect(screen.getByText("No runs match these filters.")).toBeVisible();
-    expect(agentTraceListCall).toHaveBeenCalledTimes(1);
-  });
-
-  it("treats a proxy without the trace routes (404) like tracing being off", async () => {
-    vi.mocked(agentTraceListCall).mockRejectedValue(new ApiError("Not Found", 404, { detail: "Not Found" }));
-    renderSection();
-
-    const card = await screen.findByTestId("tracing-setup-card");
-    expect(card).toHaveTextContent("Tracing is not enabled");
-    expect(card).toHaveTextContent("url: os.environ/CLICKHOUSE_URL");
-  });
-
-  it("lists every run with its input, counts and failed column", async () => {
-    vi.mocked(agentTraceListCall).mockResolvedValue(traceList as TracePage);
-    renderSection();
-
-    const rows = await screen.findAllByTestId("agent-trace-row");
-    expect(rows).toHaveLength(runs.length);
-    const lead = rows.find((row) => row.textContent?.includes("Should we store OTEL agent spans"));
-    expect(lead).toBeDefined();
-    const failed = rows.find((row) => row.textContent?.includes("acme-404")) as HTMLElement;
-    expect(within(failed).getByLabelText("2 errors")).toBeInTheDocument();
-    expect(screen.getByText(`${runs.length} runs`)).toBeInTheDocument();
-    expect(screen.getByRole("columnheader", { name: "Cost" })).toBeInTheDocument();
-    expect(within(failed).getByText("—")).toBeInTheDocument();
-  });
-
-  it("shows the spend returned for a run", async () => {
-    vi.mocked(agentTraceListCall).mockResolvedValue({
-      ...(traceList as TracePage),
-      data: [{ ...runs[0], spend: 0.025 }],
-    });
-    renderSection();
-
-    const row = await screen.findByTestId("agent-trace-row");
-    expect(within(row).getByText("$0.03")).toBeInTheDocument();
-  });
-
-  it("filters by input text and by trace id", async () => {
-    vi.mocked(agentTraceListCall).mockResolvedValue(traceList as TracePage);
-    renderSection();
-    await screen.findAllByTestId("agent-trace-row");
-
-    const search = screen.getByLabelText("Search runs");
-    fireEvent.change(search, { target: { value: "acme-404" } });
-    expect(screen.getAllByTestId("agent-trace-row")).toHaveLength(1);
-
-    const lead = runs.find((r) => r.name === "research_lead") as TraceSummary;
-    fireEvent.change(search, { target: { value: lead.trace_id.slice(0, 10) } });
-    const rows = screen.getAllByTestId("agent-trace-row");
-    expect(rows).toHaveLength(1);
-    expect(rows[0]).toHaveTextContent("Should we store OTEL agent spans");
-  });
-
-  it("uses recorded agent names for the column and filter even when services are shared", async () => {
-    vi.mocked(agentTraceListCall).mockResolvedValue({
-      ...(traceList as TracePage),
-      data: [
-        ...runs.slice(1).map((run) => ({ ...run, service: "shared-app", agent_names: ["research-agent"] })),
-        { ...runs[0], service: "shared-app", agent_names: ["billing-agent", "review-agent"] },
-      ],
-    });
-    const user = userEvent.setup();
-    renderSection();
-    await screen.findAllByTestId("agent-trace-row");
-
-    expect(screen.getByRole("columnheader", { name: "Agent" })).toBeInTheDocument();
-    const agentFilter = screen.getByRole("combobox", { name: "Filter by agent" });
-    expect(agentFilter).toHaveTextContent("All agents");
-
-    await chooseSelectOption(user, agentFilter, "billing-agent");
-    const rows = screen.getAllByTestId("agent-trace-row");
-    expect(rows).toHaveLength(1);
-    expect(rows[0]).toHaveTextContent("billing-agent");
-    expect(rows[0]).not.toHaveTextContent("shared-app");
-
-    await chooseSelectOption(user, agentFilter, "review-agent");
-    expect(screen.getAllByTestId("agent-trace-row")).toHaveLength(1);
-
-    await chooseSelectOption(user, agentFilter, "All agents");
-    expect(screen.getAllByTestId("agent-trace-row")).toHaveLength(runs.length);
-  });
-
-  it("shows each run's agent name with the logo of the SDK that produced it", async () => {
-    vi.mocked(agentTraceListCall).mockResolvedValue({
-      ...(traceList as TracePage),
-      data: [
-        { ...runs[0], agent_names: ["research-bot"], frameworks: ["claude-agent-sdk", "claude-code"] },
-        { ...runs[1], agent_names: [], frameworks: ["claude-code"] },
-        { ...runs[2], frameworks: [] },
-      ],
-    });
-    renderSection();
-    const [sdkRun, cliRun, plainRun] = await screen.findAllByTestId("agent-trace-row");
-    const agentCell = (row: HTMLElement) => within(row).getAllByRole("cell")[1];
-
-    expect(agentCell(sdkRun)).toHaveTextContent(/^research-bot$/);
-    expect(agentCell(sdkRun)).toHaveAttribute("title", "research-bot · Claude Agent SDK");
-    expect(within(sdkRun).getByRole("img", { name: "Claude Agent SDK logo", hidden: true })).toHaveAttribute(
-      "src",
-      expect.stringContaining("anthropic.svg"),
-    );
-    expect(agentCell(cliRun)).toHaveTextContent(/^Claude Code$/);
-    expect(within(plainRun).queryByRole("img", { hidden: true })).not.toBeInTheDocument();
-    expect(agentCell(plainRun)).toHaveTextContent((runs[2].agent_names ?? [runs[2].service]).join(", "));
-  });
-
+describe("filterRuns", () => {
  it("status filter 'Failed' keeps only runs with errors", () => {
    const failed = filterRuns(runs, "", "all", "error");
    expect(failed.length).toBeGreaterThan(0);
@ -333,181 +14,4 @@ describe("AgentTracesSection", () => {
    expect(ok.every((r) => r.error_count === 0)).toBe(true);
    expect(failed.length + ok.length).toBe(runs.length);
  });
-
-  it("opens a run in a side drawer over the list and swaps runs without closing it", async () => {
-    vi.mocked(agentTraceListCall).mockResolvedValue(traceList as TracePage);
-    renderSection();
-    const rows = await screen.findAllByTestId("agent-trace-row");
-
-    fireEvent.click(rows[0]);
-    const drawer = screen.getByRole("complementary", { name: "Trace details" });
-    expect(within(drawer).getByTestId("run-view")).toHaveTextContent(`run ${runs[0].trace_id}`);
-    expect(screen.getByTestId("runs-table")).toBeInTheDocument();
-    expect(rows[0]).toHaveAttribute("aria-selected", "true");
-
-    fireEvent.click(rows[1]);
-    expect(screen.getByRole("complementary", { name: "Trace details" })).toBe(drawer);
-    expect(within(drawer).getByTestId("run-view")).toHaveTextContent(`run ${runs[1].trace_id}`);
-    expect(rows[1]).toHaveAttribute("aria-selected", "true");
-    expect(rows[0]).toHaveAttribute("aria-selected", "false");
-  });
-
-  it("closes the drawer when the open row is clicked again or Escape is pressed", async () => {
-    vi.mocked(agentTraceListCall).mockResolvedValue(traceList as TracePage);
-    renderSection();
-    const rows = await screen.findAllByTestId("agent-trace-row");
-
-    fireEvent.click(rows[0]);
-    fireEvent.click(rows[0]);
-    expect(rows[0]).toHaveAttribute("aria-selected", "false");
-
-    fireEvent.click(rows[1]);
-    fireEvent.keyDown(window, { key: "Escape" });
-    expect(rows[1]).toHaveAttribute("aria-selected", "false");
-  });
-
-  it("moves to the next and previous run with j / k and the header arrows", async () => {
-    vi.mocked(agentTraceListCall).mockResolvedValue(traceList as TracePage);
-    renderSection();
-    const rows = await screen.findAllByTestId("agent-trace-row");
-
-    fireEvent.click(rows[0]);
-    fireEvent.keyDown(window, { key: "j" });
-    expect(screen.getByTestId("run-view")).toHaveTextContent(`run ${runs[1].trace_id}`);
-    fireEvent.keyDown(window, { key: "k" });
-    expect(screen.getByTestId("run-view")).toHaveTextContent(`run ${runs[0].trace_id}`);
-    expect(screen.getByRole("button", { name: "Previous trace (K)" })).toBeDisabled();
-    fireEvent.click(screen.getByRole("button", { name: "Next trace (J)" }));
-    expect(screen.getByTestId("run-view")).toHaveTextContent(`run ${runs[1].trace_id}`);
-  });
-
-  it("plots every loaded run on the timeline", async () => {
-    vi.mocked(agentTraceListCall).mockResolvedValue(traceList as TracePage);
-    renderWindowed();
-    await screen.findAllByTestId("agent-trace-row");
-
-    expect(screen.getByTestId("traces-timeline")).toBeInTheDocument();
-    const counts = bucketRunCounts();
-    expect(counts).toHaveLength(60);
-    expect(counts.reduce((a, b) => a + b, 0)).toBe(runs.length);
-  });
-
-  it("zooms by dragging, resizes and pans the bracket, and clears with Esc", async () => {
-    vi.mocked(agentTraceListCall).mockResolvedValue(traceList as TracePage);
-    renderWindowed();
-    await screen.findAllByTestId("agent-trace-row");
-    const area = screen.getByTestId("timeline-area");
-    const x = (bucket: number) => bucket * 10 + 5;
-    const drag = (target: HTMLElement, from: number, to: number) => {
-      fireEvent.pointerDown(target, { clientX: x(from), pointerId: 1 });
-      fireEvent.pointerMove(area, { clientX: x(to), pointerId: 1 });
-      fireEvent.pointerUp(area, { clientX: x(to), pointerId: 1 });
-    };
-    const rowCount = () => screen.queryAllByTestId("agent-trace-row").length;
-    const withRuns = bucketRunCounts().flatMap((count, i) => (count > 0 ? [i] : []));
-    const first = withRuns[0];
-    // The pan below moves a [0, first] bracket to the far right; it must end up clear of every run.
-    expect(first).toBeGreaterThan(1);
-    expect(first).toBeLessThan(30);
-
-    drag(area, 0, 1);
-    expect(screen.getByTestId("timeline-selection")).toBeInTheDocument();
-    expect(rowCount()).toBe(0);
-
-    drag(screen.getByTestId("timeline-handle-hi"), 1, first);
-    expect(rowCount()).toBeGreaterThan(0);
-
-    drag(screen.getByTestId("timeline-selection"), 1, 1 - first);
-    expect(rowCount()).toBeGreaterThan(0);
-    drag(screen.getByTestId("timeline-selection"), 0, 59);
-    expect(rowCount()).toBe(0);
-
-    fireEvent.keyDown(screen.getByTestId("traces-timeline"), { key: "Escape" });
-    expect(screen.queryByTestId("timeline-selection")).not.toBeInTheDocument();
-    expect(rowCount()).toBe(runs.length);
-  });
-
-  it("clears timeline zoom when refreshed", async () => {
-    vi.mocked(agentTraceListCall).mockResolvedValue(traceList as TracePage);
-    renderWindowed({ rangeHours: 24, onRangeHoursChange: () => {}, onLiveChange: () => {} });
-    await screen.findAllByTestId("agent-trace-row");
-    const area = screen.getByTestId("timeline-area");
-    const x = (bucket: number) => bucket * 10 + 5;
-
-    fireEvent.pointerDown(area, { clientX: x(0), pointerId: 1 });
-    fireEvent.pointerMove(area, { clientX: x(1), pointerId: 1 });
-    fireEvent.pointerUp(area, { clientX: x(1), pointerId: 1 });
-    expect(screen.getByTestId("timeline-selection")).toBeInTheDocument();
-    expect(screen.queryAllByTestId("agent-trace-row")).toHaveLength(0);
-
-    fireEvent.click(screen.getByRole("button", { name: "Refresh" }));
-
-    expect(screen.queryByTestId("timeline-selection")).not.toBeInTheDocument();
-    expect(screen.getAllByTestId("agent-trace-row")).toHaveLength(runs.length);
-  });
-});
-
-describe("AgentTracesPage", () => {
-  beforeEach(() => {
-    testQueryClient.clear();
-    vi.mocked(agentTraceListCall).mockReset();
-    vi.mocked(apiClient.get).mockResolvedValue({ data: [] });
-  });
-
-  it("shows the actual range, switches presets from the popover, and toggles Live", async () => {
-    vi.mocked(agentTraceListCall).mockResolvedValue(traceList as TracePage);
-    renderWithProviders(<AgentTracesPage accessToken="sk-test" />);
-    await screen.findByTestId("runs-table");
-
-    const trigger = screen.getByRole("button", { name: "Time range" });
-    expect(trigger).toHaveTextContent(/ to /);
-    expect(screen.getByTestId("traces-timeline")).toHaveTextContent("Total 1d");
-
-    fireEvent.click(trigger);
-    fireEvent.click(await screen.findByRole("menuitemradio", { name: "Last 7 days" }));
-    expect(await screen.findByText("Total 7d")).toBeInTheDocument();
-    const last = vi.mocked(agentTraceListCall).mock.calls.at(-1)?.[0];
-    expect((last?.endMs ?? 0) - (last?.startMs ?? 0)).toBeGreaterThanOrEqual(7 * 24 * 3600 * 1000 - 60_000);
-
-    const live = screen.getByRole("button", { name: "Live" });
-    expect(live).toHaveAttribute("aria-pressed", "true");
-    fireEvent.click(live);
-    expect(live).toHaveAttribute("aria-pressed", "false");
-    expect(screen.getByRole("button", { name: "Refresh" })).toBeEnabled();
-  });
-
-  it("refreshes the trace list", async () => {
-    vi.mocked(agentTraceListCall).mockResolvedValue(traceList as TracePage);
-    renderWithProviders(<AgentTracesPage accessToken="sk-test" />);
-    await screen.findByTestId("runs-table");
-
-    const callsBeforeRefresh = vi.mocked(agentTraceListCall).mock.calls.length;
-    fireEvent.click(screen.getByRole("button", { name: "Refresh" }));
-
-    await waitFor(() => expect(vi.mocked(agentTraceListCall).mock.calls.length).toBeGreaterThan(callsBeforeRefresh));
-  });
-
-  it("keeps the time controls on an empty range the user picked, instead of showing onboarding", async () => {
-    vi.mocked(agentTraceListCall).mockResolvedValue(traceList as TracePage);
-    renderWithProviders(<AgentTracesPage accessToken="sk-test" />);
-    await screen.findByTestId("runs-table");
-
-    vi.mocked(agentTraceListCall).mockResolvedValue({ ...(traceList as TracePage), data: [] });
-    fireEvent.click(screen.getByRole("button", { name: "Time range" }));
-    fireEvent.click(await screen.findByRole("menuitemradio", { name: "Last hour" }));
-
-    expect(await screen.findByText("No runs match these filters.")).toBeInTheDocument();
-    expect(screen.getByRole("button", { name: "Time range" })).toBeInTheDocument();
-    expect(screen.queryByTestId("tracing-setup-card")).not.toBeInTheDocument();
-  });
-
-  it("asks the proxy for the last 24 hours by default", async () => {
-    vi.mocked(agentTraceListCall).mockResolvedValue(traceList as TracePage);
-    renderWithProviders(<AgentTracesPage accessToken="sk-test" />);
-    await screen.findByTestId("runs-table");
-
-    const { startMs, endMs } = vi.mocked(agentTraceListCall).mock.calls[0][0];
-    expect(endMs - startMs).toBeGreaterThanOrEqual(24 * 3600 * 1000 - 60_000);
-    expect(endMs - startMs).toBeLessThan(24 * 3600 * 1000 + 120_000);
-  });
 });
--- a/ui/litellm-dashboard/src/components/view_logs/TraceView/AgentTracesSection.tsx
+++ b/ui/litellm-dashboard/src/components/view_logs/TraceView/AgentTracesSection.tsx
@ -1,4 +1,5 @@
 "use client";
+import { useLensDemo } from "@/components/lens/LensDemoContext";

 import moment from "moment";
 import { useMemo, useState } from "react";
@ -61,6 +62,7 @@ interface AgentTracesSectionProps {
  onRunOpenChange?: (open: boolean) => void;
  readOnly?: boolean;
  canMintTracingKey?: boolean;
+  onDemo?: () => void;
 }

 function useTracingSetup(traces: AgentTracesResult, isActive: boolean, rangeChanged: boolean) {
@ -102,7 +104,9 @@ export function AgentTracesSection({
  onRunOpenChange,
  readOnly = false,
  canMintTracingKey = false,
+  onDemo,
 }: AgentTracesSectionProps) {
+  const demo = useLensDemo();
  const [openTrace, setOpenTrace] = useState<TraceSummary | null>(null);
  const [query, setQuery] = useState("");
  const [agent, setAgent] = useState(ALL_AGENTS);
@ -160,10 +164,11 @@ export function AgentTracesSection({
    checking: traces.isFetching,
  };

-  if (setup.disabledDetail != null) return <TracingSetupCard detail={setup.disabledDetail} {...setupProps} />;
+  if (setup.disabledDetail != null)
+    return <TracingSetupCard detail={setup.disabledDetail} onDemo={onDemo} {...setupProps} />;
  // Onboarding only on the first, default view; an empty range the user picked keeps its controls.
  if (checkHistory && !history.error && history.data === false)
-    return <TracingSetupCard detail={null} {...setupProps} />;
+    return <TracingSetupCard detail={null} onDemo={onDemo} {...setupProps} />;
  if (showSetup) {
    return (
      <div>
@ -185,11 +190,7 @@ export function AgentTracesSection({
  return (
    <div className="flex min-h-[560px] flex-1 flex-col overflow-hidden border-y border-border bg-card">
      {checkHistory && <TraceHistoryError history={history} />}
-      {setup.received && (
-        <p role="status" className="border-b px-3 py-3 text-sm text-emerald-700 dark:text-emerald-400">
-          Traces received. Select a run to inspect it.
-        </p>
-      )}
+      <TracesReceived received={setup.received} />
      <RunDrawer trace={openTrace} runs={runs} accessToken={accessToken} onSelect={openRun} />
      <RunsToolbar
        query={query}
@ -200,16 +201,19 @@ export function AgentTracesSection({
        onAgentChange={setAgent}
        onStatusChange={setStatus}
      >
-        <Button variant="outline" size="sm" onClick={() => setShowSetup(true)} className="shrink-0 gap-1.5">
-          <ActiveDot />
-          Set up tracing
-        </Button>
+        {!demo && (
+          <Button variant="outline" size="sm" onClick={() => setShowSetup(true)} className="shrink-0 gap-1.5">
+            <ActiveDot />
+            Set up tracing
+          </Button>
+        )}
        {timeControls && (
          <TimeRangeControls
            range={zoom ?? range}
            rangeHours={timeControls.rangeHours}
            onRangeHoursChange={(hours) => changeRange(hours, timeControls.onRangeHoursChange)}
            live={isLiveTail}
+            showLive={!demo}
            onLiveChange={timeControls.onLiveChange}
            onRefresh={() => {
              setZoom(null);
@ -240,6 +244,16 @@ export function AgentTracesSection({
  );
 }

+function TracesReceived({ received }: { received: boolean }) {
+  const demo = useLensDemo();
+  if (!received || demo) return null;
+  return (
+    <p role="status" className="border-b px-3 py-3 text-sm text-emerald-700 dark:text-emerald-400">
+      Traces received. Select a run to inspect it.
+    </p>
+  );
+}
+
 function RunsFooter({
  count,
  zoom,
--- a/ui/litellm-dashboard/src/components/view_logs/TraceView/DetailContent.tsx
+++ b/ui/litellm-dashboard/src/components/view_logs/TraceView/DetailContent.tsx
@ -1,4 +1,5 @@
 "use client";
+import { useLensDemo } from "@/components/lens/LensDemoContext";

 import { useQuery, type UseQueryOptions } from "@tanstack/react-query";
 import { useState } from "react";
@ -29,9 +30,15 @@ const errorReason = (headline: string): string => /^([A-Za-z_][\w.]*)\(/.exec(he

 /** Shared lazy fetch of one span's full input / output / attributes. */
 export function useSpanDetail(accessToken: string, traceId: string, spanId: string | null, traceRef?: string) {
+  const demo = useLensDemo();
  const queryOptions: UseQueryOptions<SpanDetail, Error> = {
    queryKey: ["agentTraceSpan", traceId, traceRef, spanId, accessToken],
-    queryFn: () => agentTraceSpanCall(accessToken, traceId, spanId as string, traceRef),
+    queryFn: () =>
+      demo
+        ? demo.client.get<SpanDetail>(
+            `/v1/traces/${encodeURIComponent(traceId)}/spans/${encodeURIComponent(spanId as string)}`,
+          )
+        : agentTraceSpanCall(accessToken, traceId, spanId as string, traceRef),
    enabled: spanId !== null,
    staleTime: Infinity,
  };
@ -146,11 +153,17 @@ interface DetailContentProps {
 }

 function DiagnosticContent({ accessToken, traceId, traceRef, span }: DetailContentProps) {
+  const demo = useLensDemo();
  const [opened, setOpened] = useState(false);
  const [cursor, setCursor] = useState<string | null>(null);
  const queryOptions: UseQueryOptions<SpanErrorPage, Error> = {
    queryKey: ["agentTraceSpanError", traceId, traceRef, span.span_id, accessToken, cursor],
-    queryFn: () => agentTraceSpanErrorCall(accessToken, traceId, span.span_id, { traceRef, cursor }),
+    queryFn: () =>
+      demo
+        ? demo.client.get<SpanErrorPage>(
+            `/v1/traces/${encodeURIComponent(traceId)}/spans/${encodeURIComponent(span.span_id)}/error`,
+          )
+        : agentTraceSpanErrorCall(accessToken, traceId, span.span_id, { traceRef, cursor }),
    enabled: opened,
    staleTime: Infinity,
    gcTime: 0,
--- a/ui/litellm-dashboard/src/components/view_logs/TraceView/DetailPane.tsx
+++ b/ui/litellm-dashboard/src/components/view_logs/TraceView/DetailPane.tsx
@ -1,4 +1,5 @@
 "use client";
+import { useLensDemo } from "@/components/lens/LensDemoContext";

 import { PanelRightClose } from "lucide-react";
 import { useState } from "react";
@ -104,6 +105,7 @@ function SpanPane({
  onClose: () => void;
 }) {
  const [tab, setTab] = useState<Tab>("content");
+  const demo = useLensDemo();
  const traceId = trace.summary.trace_id;
  const detailQuery = useSpanDetail(
    accessToken,
@ -162,9 +164,13 @@ function SpanPane({
      </div>
      <PaneFooter>
        <CopyButton
-          value={agentHandoffText(traceId, span.span_id, trace.summary.trace_ref)}
+          value={
+            demo
+              ? demo.copyTrace(traceId, span.span_id)
+              : agentHandoffText(traceId, span.span_id, trace.summary.trace_ref)
+          }
          label="Copy step"
-          copiedLabel="Command copied"
+          copiedLabel={demo ? "Step copied" : "Command copied"}
        />
        <div className="ml-auto flex items-center gap-3 text-[13px] text-trace-duration tabular-nums">
          <Meta label="time" value={fmtMs(span.duration_ms)} />
@ -186,6 +192,7 @@ function GroupMetric({ label, value }: { label: string; value: string }) {

 /** ×N group: rollup of every invocation plus the first failure's message. */
 function GroupPane({ trace, row, onClose }: { trace: Trace; row: GroupRowData; onClose: () => void }) {
+  const demo = useLensDemo();
  const tokens = row.members.reduce((sum, m) => sum + m.input_tokens + m.output_tokens, 0);
  const firstFailure = row.members.find((m) => m.status === "error" && m.error);
  return (
@ -222,7 +229,11 @@ function GroupPane({ trace, row, onClose }: { trace: Trace; row: GroupRowData; o
      </div>
      <PaneFooter>
        <CopyButton
-          value={agentHandoffText(trace.summary.trace_id, (firstFailure ?? row.members[0]).span_id)}
+          value={
+            demo
+              ? demo.copyTrace(trace.summary.trace_id, (firstFailure ?? row.members[0]).span_id)
+              : agentHandoffText(trace.summary.trace_id, (firstFailure ?? row.members[0]).span_id)
+          }
          label="Copy group sample"
        />
      </PaneFooter>
--- a/ui/litellm-dashboard/src/components/view_logs/TraceView/TimeRangeControls.tsx
+++ b/ui/litellm-dashboard/src/components/view_logs/TraceView/TimeRangeControls.tsx
@ -34,6 +34,7 @@ interface TimeRangeControlsProps {
  rangeHours: number;
  onRangeHoursChange: (hours: number) => void;
  live: boolean;
+  showLive?: boolean;
  onLiveChange: (live: boolean) => void;
  onRefresh: () => void;
  refreshing: boolean;
@ -45,6 +46,7 @@ export function TimeRangeControls({
  rangeHours,
  onRangeHoursChange,
  live,
+  showLive = true,
  onLiveChange,
  onRefresh,
  refreshing,
@ -84,18 +86,20 @@ export function TimeRangeControls({
            </DropdownMenuRadioGroup>
          </DropdownMenuContent>
        </DropdownMenu>
-        <button
-          type="button"
-          aria-pressed={live}
-          onClick={() => onLiveChange(!live)}
-          className={cn(
-            SEGMENT,
-            live ? "bg-info/10 text-info hover:bg-info/15" : "text-muted-foreground hover:text-foreground",
-          )}
-        >
-          {live ? <Pause className="size-3.5" /> : <Play className="size-3.5" />}
-          Live
-        </button>
+        {showLive && (
+          <button
+            type="button"
+            aria-pressed={live}
+            onClick={() => onLiveChange(!live)}
+            className={cn(
+              SEGMENT,
+              live ? "bg-info/10 text-info hover:bg-info/15" : "text-muted-foreground hover:text-foreground",
+            )}
+          >
+            {live ? <Pause className="size-3.5" /> : <Play className="size-3.5" />}
+            Live
+          </button>
+        )}
      </div>
    </div>
  );
--- a/ui/litellm-dashboard/src/components/view_logs/TraceView/TraceDrawer.tsx
+++ b/ui/litellm-dashboard/src/components/view_logs/TraceView/TraceDrawer.tsx
@ -1,4 +1,5 @@
 "use client";
+import { useLensDemo } from "@/components/lens/LensDemoContext";

 import { useQuery } from "@tanstack/react-query";
 import { ArrowLeft, Check, Copy } from "lucide-react";
@ -74,6 +75,7 @@ const toggle = (set: ReadonlySet<string>, id: string): Set<string> => {
 };

 function CopyForAgent({ traceId, traceRef }: { traceId: string; traceRef?: string }) {
+  const demo = useLensDemo();
  const [copied, setCopied] = useState(false);
  useEffect(() => {
    if (!copied) return;
@ -86,11 +88,16 @@ function CopyForAgent({ traceId, traceRef }: { traceId: string; traceRef?: strin
      size="xs"
      className="h-7 shrink-0 gap-1.5 rounded-md text-[12px] shadow-none"
      onClick={async () =>
-        setCopied(await copyToClipboard(agentHandoffText(traceId, null, traceRef), "Command copied"))
+        setCopied(
+          await copyToClipboard(
+            demo ? demo.copyTrace(traceId) : agentHandoffText(traceId, null, traceRef),
+            demo ? "Trace copied" : "Command copied",
+          ),
+        )
      }
    >
      {copied ? <Check className="size-3" /> : <Copy className="size-3" />}
-      {copied ? "Command copied" : "Copy for agent"}
+      {copied ? "Copied" : "Copy for agent"}
    </Button>
  );
 }
@ -277,9 +284,13 @@ interface RunViewProps {

 /** One agent run: header with totals and "Copy for agent", span tree on the left, span details on the right. */
 export function RunView({ traceId, traceRef, initialSpanId, accessToken, onBack, embedded = false }: RunViewProps) {
+  const demo = useLensDemo();
  const traceQuery = useQuery({
    queryKey: ["agentTrace", traceId, traceRef, accessToken],
-    queryFn: () => agentTraceCall(accessToken, traceId, traceRef),
+    queryFn: () =>
+      demo
+        ? demo.client.get<Trace>(`/v1/traces/${encodeURIComponent(traceId)}`)
+        : agentTraceCall(accessToken, traceId, traceRef),
    staleTime: 30_000,
  });
  const trace = traceQuery.data;
--- a/ui/litellm-dashboard/src/components/view_logs/TraceView/TracePreview.tsx
+++ b/ui/litellm-dashboard/src/components/view_logs/TraceView/TracePreview.tsx
@ -1,70 +0,0 @@
-"use client";
-
-import { cn } from "@/lib/cva.config";
-
-import previewTrace from "./previewTrace.json";
-import { SpanIcon } from "./SpanIcon";
-import type { SpanType } from "./traceTypes";
-import { fmtMs } from "./traceUtils";
-
-interface PreviewRow {
-  id: string;
-  name: string;
-  type: SpanType;
-  model: string | null;
-  depth: number;
-  start_offset_ms: number;
-  duration_ms: number;
-  error: boolean;
-}
-
-const preview = previewTrace as {
-  name: string;
-  input_preview: string;
-  span_count: number;
-  duration_ms: number;
-  rows: PreviewRow[];
-};
-
-export function TracePreview() {
-  const total = preview.duration_ms;
-  return (
-    <div
-      aria-hidden
-      data-testid="trace-preview"
-      className="pointer-events-none overflow-hidden rounded-lg border border-border bg-background shadow-sm select-none"
-    >
-      <div className="flex items-center gap-3 border-b border-border px-4 py-2.5">
-        <SpanIcon type="agent" size="md" />
-        <span className="text-[13px] font-medium text-foreground">{preview.name}</span>
-        <span className="truncate text-[12px] text-muted-foreground">{preview.input_preview}</span>
-        <span className="ml-auto shrink-0 font-mono text-[11px] text-muted-foreground">
-          {preview.span_count} steps · {fmtMs(total)}
-        </span>
-      </div>
-      <div className="relative">
-        {preview.rows.map((row) => (
-          <div key={row.id} className="flex h-8 items-center gap-2 border-b border-border/60 px-4 last:border-b-0">
-            <div className="flex min-w-0 flex-1 items-center gap-2" style={{ paddingLeft: row.depth * 16 }}>
-              <SpanIcon type={row.type} model={row.model} error={row.error} size="sm" />
-              <span className="truncate text-[12.5px] text-foreground">{row.name}</span>
-            </div>
-            <div className="relative h-1.5 w-[40%] shrink-0 rounded-full bg-muted">
-              <div
-                className={cn("absolute h-full rounded-full", row.error ? "bg-destructive" : "bg-trace-brand/70")}
-                style={{
-                  left: `${(row.start_offset_ms / total) * 100}%`,
-                  width: `${Math.max((row.duration_ms / total) * 100, 0.6)}%`,
-                }}
-              />
-            </div>
-            <span className="w-14 shrink-0 text-right font-mono text-[11px] text-muted-foreground">
-              {fmtMs(row.duration_ms)}
-            </span>
-          </div>
-        ))}
-        <div className="pointer-events-none absolute inset-x-0 bottom-0 h-16 bg-gradient-to-t from-background to-transparent" />
-      </div>
-    </div>
-  );
-}
--- a/ui/litellm-dashboard/src/components/view_logs/TraceView/TracingSetupCard.integration.test.tsx
+++ b/ui/litellm-dashboard/src/components/view_logs/TraceView/TracingSetupCard.integration.test.tsx
@ -12,6 +12,7 @@ import {
  tracingEnvSnippet,
  TracingSetupCard,
 } from "./TracingSetupCard";
+import { FRAMEWORKS } from "./tracingSetupGuides";
 import type { Trace } from "./traceTypes";

 vi.mock("../../networking", () => ({
@ -31,6 +32,7 @@ const renderCard = (
    onCheck?: () => void;
    readOnly?: boolean;
    canMintTracingKey?: boolean;
+    onDemo?: () => void;
  } = {},
 ) => {
  const onOpenTrace = vi.fn();
@ -38,6 +40,7 @@ const renderCard = (
    <TracingSetupCard
      detail={props.detail ?? null}
      connected={props.connected}
+      onDemo={props.onDemo}
      onCheck={props.onCheck}
      readOnly={props.readOnly}
      canMintTracingKey={props.canMintTracingKey ?? true}
@ -51,69 +54,98 @@ const renderCard = (
 beforeEach(() => vi.clearAllMocks());

 describe("TracingSetupCard", () => {
-  it("shows agent connection guidance and labels the example run as sample data", async () => {
+  it("offers the interactive demo while waiting for the first trace", async () => {
    const user = userEvent.setup();
-    const { card } = renderCard();
+    const onDemo = vi.fn();
+    const { card } = renderCard({ onDemo });
    expect(screen.getByRole("heading", { name: "Connect your agent" })).toBeVisible();
    expect(screen.getByText("Tracing enabled")).toBeVisible();
    expect(screen.getByText("Waiting for your first trace")).toBeVisible();
-    expect(screen.getByTestId("trace-preview")).toBeVisible();
-    expect(card).toHaveTextContent("sample data, not your runs");
+    await user.click(screen.getByRole("button", { name: "Preview sample" }));
+    expect(onDemo).toHaveBeenCalledOnce();
+    expect(sendOtlpTraceCall).not.toHaveBeenCalled();
    expect(card).not.toHaveTextContent("store: clickhouse");
    await user.click(screen.getByText("Set up manually"));
-    expect(screen.getByText(/^export OTEL_EXPORTER_OTLP_ENDPOINT=http:\/\/proxy.test/)).toBeVisible();
+    expect(screen.getByText(/^export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=/)).toBeVisible();
    expect(card).not.toHaveTextContent(/langsmith/i);
  });

-  it("lists the OTEL endpoints before the framework picker, each copyable", async () => {
+  it("keeps connection details visible and copies the full trace endpoint", async () => {
    const user = userEvent.setup();
-    const { card } = renderCard();
-    const text = card.textContent ?? "";
-    expect(text.indexOf("OpenTelemetry (OTEL) endpoints")).toBeLessThan(text.indexOf("Your agent framework"));
+    renderCard();
+    expect(screen.getByRole("combobox", { name: "Your agent framework" })).toBeVisible();
+    expect(screen.getByRole("button", { name: "Copy http://proxy.test/v1/traces" })).toBeVisible();
    await user.click(screen.getByRole("button", { name: "Copy http://proxy.test/v1/traces" }));
    expect(copyToClipboard).toHaveBeenLastCalledWith("http://proxy.test/v1/traces");
  });

-  it("hides the sample preview once traces are arriving", () => {
+  it("shows connection guidance for another agent without a demo", () => {
    renderCard({ connected: true });
    expect(screen.getByRole("heading", { name: "Connect another agent" })).toBeVisible();
-    expect(screen.queryByTestId("trace-preview")).not.toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: "Preview sample" })).not.toBeInTheDocument();
  });

  it("builds the coding agent command for the selected framework and keeps both manual installers", async () => {
    const user = userEvent.setup();
    renderCard();
    await chooseSelectOption(user, screen.getByRole("combobox", { name: "Your agent framework" }), "CrewAI");
-    const prompt = codingAgentPrompt("http://proxy.test", {
-      label: "CrewAI",
-      packages: "crewai openinference-instrumentation-crewai",
-    });
-    const commandText = () => screen.getByText(/^claude |^codex /).textContent;
-    expect(commandText()).toBe(codingAgentCommand("Claude Code", prompt));
+    const prompt = codingAgentPrompt(
+      "http://proxy.test",
+      FRAMEWORKS.find((guide) => guide.id === "crewai")!,
+      "openai/gpt-6-sol",
+    );
+    expect(screen.getByText(/^claude /)).not.toBeVisible();
+    await user.click(screen.getByRole("button", { name: "Copy setup command" }));
+    expect(copyToClipboard).toHaveBeenLastCalledWith(codingAgentCommand("Claude Code", prompt));
    await user.click(screen.getByRole("tab", { name: "Codex" }));
-    expect(commandText()).toBe(codingAgentCommand("Codex", prompt));
+    await user.click(screen.getByRole("button", { name: "Copy setup command" }));
+    expect(copyToClipboard).toHaveBeenLastCalledWith(codingAgentCommand("Codex", prompt));
+    await user.click(screen.getByText("View command"));
+    expect(screen.getByText(/^codex /)).toBeVisible();
+    expect(screen.getByText(/^codex /)).toHaveTextContent(codingAgentCommand("Codex", prompt), {
+      normalizeWhitespace: false,
+    });

    await user.click(screen.getByText("Set up manually"));
-    expect(screen.getByText(/pip install -U opentelemetry-distro/)).toHaveTextContent(
+    expect(screen.getByText(/^pip install opentelemetry-distro/)).toHaveTextContent(
      "crewai openinference-instrumentation-crewai",
    );
    await user.click(screen.getByRole("tab", { name: "uv" }));
-    expect(screen.getByText(/uv add opentelemetry-distro/)).toHaveTextContent(
+    expect(screen.getByText(/^uv add opentelemetry-distro/)).toHaveTextContent(
      "crewai openinference-instrumentation-crewai",
    );
  });

-  it("uses npm and a CommonJS-safe TypeScript entrypoint for the Vercel AI SDK", async () => {
+  it("uses the selected framework's tracing and agent name without asking for a model", async () => {
    const user = userEvent.setup();
    const { card } = renderCard();
    await chooseSelectOption(user, screen.getByRole("combobox", { name: "Your agent framework" }), "Vercel AI SDK");
    await user.click(screen.getByText("Set up manually"));
-    expect(card).toHaveTextContent("npm install ai @ai-sdk/openai-compatible @vercel/otel");
-    expect(card).toHaveTextContent("my_agent.ts");
-    expect(card).not.toHaveTextContent("opentelemetry-instrument python");
-    const quickstart = screen.getByText(/registerOTel\(\{/).textContent ?? "";
-    expect(quickstart).toContain("async function main()");
-    expect(quickstart.split("\n").filter((line) => /^(const|let) .*= await /.test(line))).toEqual([]);
+    expect(screen.queryByRole("combobox", { name: "Model" })).not.toBeInTheDocument();
+    expect(card).toHaveTextContent("npm install ai @ai-sdk/otel");
+    expect(card).toHaveTextContent('const AGENT_NAME = "research_agent"');
+    expect(card).toHaveTextContent("functionId: AGENT_NAME");
+    expect(card).toHaveTextContent("Use a model configured on this proxy.");
+    expect(screen.getByText(/^import \{ createOpenAICompatible/)).toHaveTextContent(
+      'const model = litellm("openai/gpt-6-sol")',
+    );
+    expect(card).toHaveTextContent('baseURL: "http://proxy.test/v1"');
+  });
+
+  it("keeps plugin model settings and uses a generated tracing key only for tracing", async () => {
+    const user = userEvent.setup();
+    vi.mocked(apiClient.post).mockResolvedValue({ key: SECRET });
+    const { card } = renderCard();
+    await chooseSelectOption(user, screen.getByRole("combobox", { name: "Your agent framework" }), "Hermes");
+    await user.click(screen.getByText("Set up manually"));
+    expect(screen.queryByRole("combobox", { name: "Model" })).not.toBeInTheDocument();
+    expect(card).toHaveTextContent("Keep your existing model settings");
+    await user.click(screen.getByRole("button", { name: "Generate tracing key" }));
+    await screen.findByText("Your tracing key");
+    expect(card).toHaveTextContent("gen_ai.agent.name: research_agent");
+    expect(card).toHaveTextContent("endpoint: http://proxy.test/v1/traces");
+    expect(card).toHaveTextContent('Authorization: "Bearer ${LITELLM_TRACING_KEY}"');
+    expect(card).not.toHaveTextContent(SECRET);
  });

  it("hides the actions a read-only viewer cannot perform", () => {
@ -121,7 +153,7 @@ describe("TracingSetupCard", () => {
    expect(screen.queryByRole("button", { name: "Send a test trace" })).not.toBeInTheDocument();
    expect(screen.queryByRole("button", { name: "Generate tracing key" })).not.toBeInTheDocument();
    expect(card).toHaveTextContent("ask a proxy admin for one");
-    expect(card).toHaveTextContent("OpenTelemetry (OTEL) endpoints");
+    expect(card).toHaveTextContent("Connection details");
  });

  it("offers a scoped tracing key only to callers allowed to set key routes", () => {
@ -135,7 +167,7 @@ describe("TracingSetupCard", () => {
    const user = userEvent.setup();
    vi.mocked(apiClient.post).mockResolvedValue({ key: SECRET });
    const { card } = renderCard();
-
+    await user.click(screen.getByText("Set up manually"));
    await user.click(screen.getByRole("button", { name: "Generate tracing key" }));

    expect(await screen.findByText("Your tracing key")).toBeVisible();
@ -193,24 +225,23 @@ describe("TracingSetupCard", () => {
 });

 describe("setup snippets", () => {
-  it("uses OTLP HTTP with the proxy base URL and reads the key from the environment", () => {
+  it("uses the instance trace endpoint and keeps tracing and inference keys separate", () => {
    const env = tracingEnvSnippet("http://proxy.test");
-    expect(env).toContain("OTEL_EXPORTER_OTLP_ENDPOINT=http://proxy.test\n");
-    expect(env).toContain("OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf");
-    expect(env).not.toContain("/v1/traces");
+    expect(env).toContain('OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://proxy.test/v1/traces"');
+    expect(env).toContain('OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"');
    expect(env).not.toContain("export LITELLM_API_KEY=");
    expect(env).toContain("Bearer $LITELLM_API_KEY");
    const withKey = tracingEnvSnippet("http://proxy.test", SECRET);
    expect(withKey).toContain(`export LITELLM_TRACING_KEY=${SECRET}\n`);
-    expect(withKey).toContain('OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer $LITELLM_TRACING_KEY"');
-    expect(withKey).not.toContain("LITELLM_API_KEY");
+    expect(withKey).toContain('OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer $LITELLM_TRACING_KEY"');
+    expect(withKey).not.toContain("export LITELLM_API_KEY=");

-    const prompt = codingAgentPrompt("http://proxy.test", { label: "LangChain", packages: "langchain" });
-    expect(prompt).toContain("base_url=http://proxy.test/v1");
-    expect(prompt).toContain("opentelemetry-distro opentelemetry-exporter-otlp-proto-http langchain");
-    expect(prompt).toContain("OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf");
+    const prompt = codingAgentPrompt("http://proxy.test", FRAMEWORKS[0], "openai/gpt-6-sol");
+    expect(prompt).toContain('OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://proxy.test/v1/traces"');
+    expect(prompt).toContain("Keep the existing model configuration");
+    expect(prompt).toContain('AGENT_NAME = "research_agent"');
+    expect(prompt).toContain("name=AGENT_NAME");
    expect(prompt).toContain("Lens > Traces");
-    expect(prompt).not.toMatch(/langsmith/i);
  });

  it("builds a shell-safe command for each coding agent", () => {
--- a/ui/litellm-dashboard/src/components/view_logs/TraceView/TracingSetupCard.tsx
+++ b/ui/litellm-dashboard/src/components/view_logs/TraceView/TracingSetupCard.tsx
@ -4,31 +4,23 @@ import { ArrowRight, ArrowUpRight, Check, Copy, KeyRound, Loader2, Send } from "
 import { useState } from "react";

 import { cn } from "@/lib/cva.config";
+import { LensPreviewButton } from "@/components/lens/LensPreviewButton";
 import { Button } from "@/components/ui/button";
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
 import { copyToClipboard } from "@/utils/dataUtils";

 import anthropicLogo from "../../../../public/assets/logos/anthropic.svg";
-import crewaiLogo from "../../../../public/assets/logos/crewai-color.svg";
-import langchainLogo from "../../../../public/assets/logos/langchain.svg";
-import langgraphLogo from "../../../../public/assets/logos/langgraph-color.svg";
-import llamaindexLogo from "../../../../public/assets/logos/llamaindex-color.svg";
-import openaiAgentsLogo from "../../../../public/assets/logos/openai-agents.svg";
 import openaiLogo from "../../../../public/assets/logos/openai_small.svg";
 import otelLogo from "../../../../public/assets/logos/opentelemetry.svg";
-import pydanticAiLogo from "../../../../public/assets/logos/pydantic-ai-color.svg";
-import vercelLogo from "../../../../public/assets/logos/vercel.svg";
 import { agentTraceCall, apiClient, getProxyBaseUrl, sendOtlpTraceCall } from "../../networking";
 import { ActiveDot } from "./ActiveDot";
 import { sampleTraceExport } from "./sampleTrace";
-import { TracePreview } from "./TracePreview";
+import { FRAMEWORKS, frameworkSnippet, type FrameworkGuide } from "./tracingSetupGuides";
 import type { TraceSummary } from "./traceTypes";

 const COPIED_RESET_MS = 1500;
 const DOCS_URL = "https://docs.litellm.ai/docs/proxy/lens";
-const OTEL_BASE_PACKAGES = "opentelemetry-distro opentelemetry-exporter-otlp-proto-http";
-const PY_RUN_SNIPPET = "opentelemetry-instrument python my_agent.py";
-const TS_RUN_SNIPPET = "npx tsx my_agent.ts";
+const EXAMPLE_MODEL = "openai/gpt-6-sol";
 const SAMPLE_TRACE_POLL_MS = 1000;
 export const TRACING_KEY_REQUEST = {
  key_alias: "Agent tracing",
@ -41,177 +33,36 @@ type Installer = "pip" | "uv";
 type CodingAgent = "Claude Code" | "Codex";

 const PY_INSTALL: Record<Installer, (packages: string) => string> = {
-  pip: (packages) => `pip install -U ${packages}`,
+  pip: (packages) => `pip install ${packages}`,
  uv: (packages) => `uv add ${packages}`,
 };

-interface FrameworkGuide {
-  id: string;
-  label: string;
-  logo: string;
-  packages: string;
-  quickstart: string;
-  typescript?: boolean;
-}
-
-const FRAMEWORKS: readonly FrameworkGuide[] = [
-  {
-    id: "deep-agents",
-    label: "Deep Agents",
-    logo: langgraphLogo.src,
-    packages: "deepagents langchain-openai openinference-instrumentation-langchain",
-    quickstart: `from deepagents import create_deep_agent
-from langchain_openai import ChatOpenAI
-
-llm = ChatOpenAI(model="claude-sonnet-4-5", base_url="{PROXY}/v1", api_key=os.environ["LITELLM_API_KEY"])
-agent = create_deep_agent(model=llm, tools=[], system_prompt="You are a careful researcher.")
-agent.invoke({"messages": [{"role": "user", "content": "What is LiteLLM?"}]})`,
-  },
-  {
-    id: "vercel-ai-sdk",
-    label: "Vercel AI SDK",
-    logo: vercelLogo.src,
-    typescript: true,
-    packages: "ai @ai-sdk/openai-compatible @vercel/otel @opentelemetry/api",
-    quickstart: `import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
-import { registerOTel } from "@vercel/otel";
-import { generateText } from "ai";
-
-registerOTel({ serviceName: process.env.OTEL_SERVICE_NAME ?? "my-agent" });
-
-const litellm = createOpenAICompatible({ name: "litellm", baseURL: "{PROXY}/v1", apiKey: process.env.LITELLM_API_KEY });
-
-async function main() {
-  const { text } = await generateText({
-    model: litellm("claude-sonnet-4-5"),
-    prompt: "What is LiteLLM?",
-    experimental_telemetry: { isEnabled: true, functionId: "my_agent" },
-  });
-  console.log(text);
-}
-
-main();`,
-  },
-  {
-    id: "langgraph",
-    label: "LangGraph",
-    logo: langgraphLogo.src,
-    packages: "langgraph langchain-openai openinference-instrumentation-langchain",
-    quickstart: `from langchain.agents import create_agent
-from langchain_openai import ChatOpenAI
-
-llm = ChatOpenAI(model="claude-sonnet-4-5", base_url="{PROXY}/v1", api_key=os.environ["LITELLM_API_KEY"])
-agent = create_agent(model=llm, tools=[], name="my_agent")
-agent.invoke({"messages": [{"role": "user", "content": "What is LiteLLM?"}]})`,
-  },
-  {
-    id: "langchain",
-    label: "LangChain",
-    logo: langchainLogo.src,
-    packages: "langchain langchain-openai openinference-instrumentation-langchain",
-    quickstart: `from langchain_openai import ChatOpenAI
-
-llm = ChatOpenAI(model="claude-sonnet-4-5", base_url="{PROXY}/v1", api_key=os.environ["LITELLM_API_KEY"])
-llm.invoke("What is LiteLLM?")`,
-  },
-  {
-    id: "openai-agents",
-    label: "OpenAI Agents SDK",
-    logo: openaiAgentsLogo.src,
-    packages: "openai-agents openinference-instrumentation-openai-agents",
-    quickstart: `from agents import Agent, OpenAIChatCompletionsModel, Runner
-from openai import AsyncOpenAI
-
-client = AsyncOpenAI(base_url="{PROXY}/v1", api_key=os.environ["LITELLM_API_KEY"])
-agent = Agent(name="my_agent", model=OpenAIChatCompletionsModel(model="claude-sonnet-4-5", openai_client=client))
-print(Runner.run_sync(agent, "What is LiteLLM?").final_output)`,
-  },
-  {
-    id: "crewai",
-    label: "CrewAI",
-    logo: crewaiLogo.src,
-    packages: "crewai openinference-instrumentation-crewai",
-    quickstart: `from crewai import LLM, Agent, Crew, Task
-
-llm = LLM(model="openai/claude-sonnet-4-5", base_url="{PROXY}/v1", api_key=os.environ["LITELLM_API_KEY"])
-agent = Agent(role="Researcher", goal="Answer questions", backstory="", llm=llm)
-task = Task(description="What is LiteLLM?", expected_output="A short answer", agent=agent)
-Crew(agents=[agent], tasks=[task]).kickoff()`,
-  },
-  {
-    id: "pydantic-ai",
-    label: "Pydantic AI",
-    logo: pydanticAiLogo.src,
-    packages: "pydantic-ai openinference-instrumentation-pydantic-ai",
-    quickstart: `from pydantic_ai import Agent
-from pydantic_ai.models.openai import OpenAIModel
-from pydantic_ai.providers.openai import OpenAIProvider
-
-provider = OpenAIProvider(base_url="{PROXY}/v1", api_key=os.environ["LITELLM_API_KEY"])
-agent = Agent(OpenAIModel("claude-sonnet-4-5", provider=provider), name="my_agent", instrument=True)
-print(agent.run_sync("What is LiteLLM?").output)`,
-  },
-  {
-    id: "llamaindex",
-    label: "LlamaIndex",
-    logo: llamaindexLogo.src,
-    packages: "llama-index llama-index-llms-openai-like openinference-instrumentation-llama-index",
-    quickstart: `from llama_index.llms.openai_like import OpenAILike
-
-llm = OpenAILike(model="claude-sonnet-4-5", api_base="{PROXY}/v1", api_key=os.environ["LITELLM_API_KEY"], is_chat_model=True)
-print(llm.complete("What is LiteLLM?"))`,
-  },
-  {
-    id: "otel",
-    label: "OpenTelemetry",
-    logo: otelLogo.src,
-    packages: "",
-    quickstart: `# Any OTEL SDK works. Use the gen_ai.* semantic conventions:
-# gen_ai.operation.name, gen_ai.agent.name, gen_ai.response.id, gen_ai.usage.*
-from opentelemetry import trace
-
-tracer = trace.get_tracer("my-agent")
-attrs = {"gen_ai.operation.name": "invoke_agent", "gen_ai.agent.name": "my_agent"}
-with tracer.start_as_current_span("my_agent", attributes=attrs):
-    ...`,
-  },
-];
-
-const installPackages = (guide: Pick<FrameworkGuide, "packages" | "typescript">): string =>
-  guide.typescript ? guide.packages : [OTEL_BASE_PACKAGES, guide.packages].filter(Boolean).join(" ");
-
-/** The endpoint is the proxy base URL: OTLP exporters append /v1/traces themselves. */
 export const tracingEnvSnippet = (proxyUrl: string, tracingKey: string | null = null): string =>
  [
    ...(tracingKey ? [`export LITELLM_TRACING_KEY=${tracingKey}`] : []),
-    `export OTEL_EXPORTER_OTLP_ENDPOINT=${proxyUrl}`,
-    "export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf",
-    `export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer $${tracingKey ? "LITELLM_TRACING_KEY" : "LITELLM_API_KEY"}"`,
-    "export OTEL_SERVICE_NAME=my-agent",
+    `export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="${proxyUrl}/v1/traces"`,
+    `export OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer $${tracingKey ? "LITELLM_TRACING_KEY" : "LITELLM_API_KEY"}"`,
+    'export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"',
+    'export OTEL_METRICS_EXPORTER="none"',
+    'export OTEL_LOGS_EXPORTER="none"',
  ].join("\n");

-export const codingAgentPrompt = (
-  proxyUrl: string,
-  guide: Pick<FrameworkGuide, "label" | "packages" | "typescript">,
-): string =>
+export const codingAgentPrompt = (proxyUrl: string, guide: FrameworkGuide, model: string): string =>
  [
    `Send this ${guide.label} project's OpenTelemetry traces to LiteLLM.`,
-    "",
-    `1. Add these dependencies: ${installPackages(guide)}`,
-    "2. Set these env vars wherever the project loads config (.env, settings, deployment manifests):",
-    `   OTEL_EXPORTER_OTLP_ENDPOINT=${proxyUrl}`,
-    "   OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf",
-    '   OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer $LITELLM_API_KEY"',
-    "   OTEL_SERVICE_NAME=<a short name for this agent>",
-    guide.typescript
-      ? "3. Call registerOTel() from @vercel/otel at startup and pass experimental_telemetry: { isEnabled: true } to every AI SDK call."
-      : "3. Start the app through OTEL auto-instrumentation: opentelemetry-instrument <existing start command>.",
-    `4. Point every LLM client at LiteLLM: base_url=${proxyUrl}/v1, api key from LITELLM_API_KEY.`,
-    "5. Give each agent and subagent a name so runs are easy to read.",
-    "6. Run the agent once and confirm the run shows up in the LiteLLM UI under Lens > Traces.",
-    "",
-    "Never hardcode the key. Read it from LITELLM_API_KEY.",
-  ].join("\n");
+    "Keep the existing model configuration, authentication, and application behavior. Never hardcode a key; read it from LITELLM_API_KEY.",
+    "Set the trace destination wherever this project loads environment variables:",
+    tracingEnvSnippet(proxyUrl),
+    guide.install ?? `Install and enable the ${guide.plugin?.label}: ${guide.plugin?.url}`,
+    guide.plugin?.instruction ??
+      "Initialize OpenTelemetry before creating the agent. If the app already configures a tracer provider, keep it and point its exporter at the destination above instead.",
+    "Adapt this example to the existing application, replacing research_agent with the agent's name:",
+    frameworkSnippet(guide, proxyUrl, model),
+    guide.note ?? "",
+    "Run the agent once and confirm its named run appears in Lens > Traces.",
+  ]
+    .filter(Boolean)
+    .join("\n\n");

 const shellQuote = (value: string): string => `'${value.replaceAll("'", "'\\''")}'`;

@ -222,10 +73,9 @@ export const maskSecret = (secret: string): string =>
  secret.length > 10 ? `${secret.slice(0, 5)}${"•".repeat(16)}${secret.slice(-4)}` : "•".repeat(secret.length);

 export const otlpEndpoints = (proxyUrl: string): readonly (readonly [string, string, boolean])[] => [
-  ["Traces endpoint (POST)", `${proxyUrl}/v1/traces`, true],
-  ["OTEL_EXPORTER_OTLP_ENDPOINT", proxyUrl, true],
+  ["Traces endpoint", `${proxyUrl}/v1/traces`, true],
  ["Auth header", "Authorization: Bearer <LiteLLM virtual key>", true],
-  ["Protocol", "OTLP/HTTP, protobuf or JSON (gRPC not supported)", false],
+  ["Protocol", "OTLP/HTTP (protobuf or JSON)", false],
 ];

 export const PROXY_CONFIG_SNIPPET = [
@ -270,8 +120,8 @@ function CodeBlock({
      </div>
      <pre
        className={cn(
-          "px-4 py-3 font-mono text-[12.5px] leading-6 text-foreground",
-          wrap ? "whitespace-pre-wrap" : "overflow-x-auto",
+          "m-0 px-4 py-3 font-mono text-xs leading-5 text-foreground",
+          wrap ? "whitespace-pre-wrap break-words" : "overflow-x-auto",
        )}
      >
        <code>{display}</code>
@ -322,7 +172,7 @@ function LineTabs<T extends string>({
 function Step({ title, children }: { title: React.ReactNode; children: React.ReactNode }) {
  return (
    <section className="mt-6">
-      <h3 className="mb-2 text-[13px] font-medium text-foreground">{title}</h3>
+      <h3 className="mb-3 text-sm font-medium text-foreground">{title}</h3>
      {children}
    </section>
  );
@ -395,7 +245,7 @@ function SendTestTrace({
  const busy = state.kind === "sending" || state.kind === "waiting";
  return (
    <div className="flex flex-wrap items-center gap-3">
-      <Button onClick={() => void send()} disabled={busy}>
+      <Button variant="outline" onClick={() => void send()} disabled={busy}>
        {busy ? (
          <Loader2 aria-hidden="true" className="size-4 animate-spin" />
        ) : (
@ -421,20 +271,18 @@ function TraceReceipt({
 }) {
  const missingAfterCheck = checked && !checking && !connected;
  return (
-    <Step title="Run your agent once">
-      <p className="text-sm leading-6 text-muted-foreground">
-        Keep this page open. Your runs will appear here when LiteLLM receives them.
-      </p>
-      <div className="mt-4 flex flex-wrap items-center gap-3">
+    <section className="mt-6 border-t pt-6" aria-label="Trace connection status">
+      <div className="flex flex-wrap items-center justify-between gap-3">
+        <div>
+          <p role="status" className="text-sm font-medium">
+            {connected ? "Traces connected" : "Waiting for your first trace"}
+          </p>
+          <p className="mt-1 text-sm text-muted-foreground">Run your agent once. Its traces will appear here.</p>
+        </div>
        <Button variant="outline" onClick={onCheck} disabled={checking}>
          {checking && <Loader2 aria-hidden="true" className="size-4 animate-spin" />}
          {checking ? "Checking…" : "Check for traces"}
        </Button>
-        {!connected && (
-          <p role="status" className="text-sm text-muted-foreground">
-            Waiting for your first trace
-          </p>
-        )}
      </div>
      {missingAfterCheck && (
        <p className="mt-3 text-sm leading-6 text-muted-foreground">
@ -442,7 +290,7 @@ function TraceReceipt({
          logs for export errors.
        </p>
      )}
-    </Step>
+    </section>
  );
 }

@ -526,19 +374,19 @@ function EndpointValue({ value }: { value: string }) {
  );
 }

-function Endpoints({ proxyUrl }: { proxyUrl: string }) {
+function Endpoints({ proxyUrl, children }: { proxyUrl: string; children?: React.ReactNode }) {
  return (
    <section className="mt-6" aria-labelledby="otel-endpoints">
-      <h3 id="otel-endpoints" className="inline-flex items-center gap-2 text-sm font-medium">
-        <img src={otelLogo.src} alt="" className="size-5" />
-        OpenTelemetry (OTEL) endpoints
-      </h3>
-      <p className="mt-1 text-sm text-muted-foreground">
-        Point any OpenTelemetry exporter here. The framework guides below set these for you.
-      </p>
-      <dl className="mt-3 grid gap-x-8 gap-y-3 rounded-md border border-l-2 border-border border-l-trace-brand bg-muted/30 px-4 py-3 md:grid-cols-2">
+      <div className="flex flex-wrap items-center justify-between gap-3">
+        <h3 id="otel-endpoints" className="inline-flex items-center gap-2 text-sm font-medium">
+          <img src={otelLogo.src} alt="" className="size-5" />
+          Connection details
+        </h3>
+        {children}
+      </div>
+      <dl className="mt-3 grid gap-x-6 gap-y-3 rounded-md border bg-muted/30 p-4 md:grid-cols-2">
        {otlpEndpoints(proxyUrl).map(([label, value, copyable]) => (
-          <div key={label} className="min-w-0">
+          <div key={label} className={cn("min-w-0", label === "Traces endpoint" && "md:col-span-2")}>
            <dt className="text-[12px] text-muted-foreground">{label}</dt>
            <dd className="mt-0.5">
              {copyable ? <EndpointValue value={value} /> : <span className="text-[12.5px]">{value}</span>}
@ -574,7 +422,7 @@ interface ConnectAgentProps {
 function EnableTracing({ checked, checking, onCheck }: { checked: boolean; checking: boolean; onCheck: () => void }) {
  return (
    <>
-      <Step title="Enable tracing on the proxy">
+      <Step title="Proxy configuration">
        <p className="mb-3 text-sm leading-6 text-muted-foreground">
          Set your ClickHouse URL, add this to config.yaml, then restart the proxy. Ask your proxy administrator if you
          don’t manage this deployment.
@ -594,14 +442,68 @@ function EnableTracing({ checked, checking, onCheck }: { checked: boolean; check
          Tracing is still unavailable. Check that the configuration was applied to this proxy and it has restarted.
        </p>
      )}
-      <Button className="mt-6" onClick={onCheck} disabled={checking}>
-        {checking && <Loader2 aria-hidden="true" className="size-4 animate-spin" />}
-        {checking ? "Checking…" : "Check setup"}
-      </Button>
+      <div className="mt-6 border-t pt-6">
+        <Button onClick={onCheck} disabled={checking}>
+          {checking && <Loader2 aria-hidden="true" className="size-4 animate-spin" />}
+          {checking ? "Checking…" : "Check setup"}
+        </Button>
+      </div>
    </>
  );
 }

+function CodingAgentSetup({ proxyUrl, guide, model }: { proxyUrl: string; guide: FrameworkGuide; model: string }) {
+  const [codingAgent, setCodingAgent] = useState<CodingAgent>("Claude Code");
+  const [copied, setCopied] = useState<string | null>(null);
+  const command = codingAgentCommand(codingAgent, codingAgentPrompt(proxyUrl, guide, model));
+  const copy = async () => {
+    if (await copyToClipboard(command)) {
+      setCopied(command);
+      window.setTimeout(() => setCopied(null), COPIED_RESET_MS);
+    }
+  };
+  return (
+    <section className="mt-6" aria-labelledby="connect-project">
+      <h3 id="connect-project" className="text-sm font-medium">
+        Connect your project
+      </h3>
+      <div className="mt-3 overflow-hidden rounded-md border">
+        <div className="border-b bg-muted/30 px-4">
+          <LineTabs
+            value={codingAgent}
+            options={["Claude Code", "Codex"]}
+            onChange={(value) => {
+              setCodingAgent(value);
+              setCopied(null);
+            }}
+            logos={CODING_AGENT_LOGOS}
+          />
+        </div>
+        <div className="p-4">
+          <p className="text-sm leading-6 text-muted-foreground">
+            Run the setup command in your agent’s project. It uses your <code className="text-xs">LITELLM_API_KEY</code>
+            .
+          </p>
+          <Button className="mt-3" onClick={() => void copy()}>
+            {copied === command ? (
+              <Check aria-hidden="true" className="size-4" />
+            ) : (
+              <Copy aria-hidden="true" className="size-4" />
+            )}
+            {copied === command ? "Copied" : "Copy setup command"}
+          </Button>
+          <details className="mt-3">
+            <summary className="w-fit cursor-pointer text-xs text-muted-foreground">View command</summary>
+            <pre className="mt-3 max-h-56 overflow-auto whitespace-pre-wrap rounded-md bg-muted/40 p-3 text-xs leading-5">
+              <code>{command}</code>
+            </pre>
+          </details>
+        </div>
+      </div>
+    </section>
+  );
+}
+
 function ConnectAgent({
  accessToken,
  onOpenTrace,
@ -615,27 +517,20 @@ function ConnectAgent({
  const proxyUrl = getProxyBaseUrl().replace(/\/$/, "");
  const [framework, setFramework] = useState(FRAMEWORKS[0].id);
  const [installer, setInstaller] = useState<Installer>("pip");
-  const [codingAgent, setCodingAgent] = useState<CodingAgent>("Claude Code");
  const [tracingKey, setTracingKey] = useState<string | null>(null);
  const guide = FRAMEWORKS.find((f) => f.id === framework) ?? FRAMEWORKS[0];
-  const packages = installPackages(guide);
-  const install = guide.typescript ? `npm install ${packages}` : PY_INSTALL[installer](packages);
-  const quickstart = guide.quickstart.replace("{PROXY}", proxyUrl);
+  const install = guide.install?.startsWith("pip install ")
+    ? PY_INSTALL[installer](guide.install.slice("pip install ".length))
+    : guide.install;
+  const model = EXAMPLE_MODEL;
+  const quickstart = frameworkSnippet(guide, proxyUrl, model, !!tracingKey);
  return (
    <>
-      {!readOnly && (
-        <Step title="See it work in one click">
-          <p className="mb-3 text-sm leading-6 text-muted-foreground">
-            Send a small sample run (an agent, an LLM call and a tool call) to confirm tracing works end to end.
-          </p>
-          <SendTestTrace accessToken={accessToken} onOpenTrace={onOpenTrace} />
-        </Step>
-      )}
-
-      <Endpoints proxyUrl={proxyUrl} />
-
+      <Endpoints proxyUrl={proxyUrl}>
+        {!readOnly && <SendTestTrace accessToken={accessToken} onOpenTrace={onOpenTrace} />}
+      </Endpoints>
      <div className="mt-6 space-y-2">
-        <label id="tracing-framework" className="text-sm font-medium">
+        <label id="tracing-framework" className="block text-sm font-medium">
          Your agent framework
        </label>
        <Select
@ -646,14 +541,14 @@ function ConnectAgent({
        >
          <SelectTrigger aria-labelledby="tracing-framework" className="w-full">
            <SelectValue>
-              <img src={guide.logo} alt="" className="size-4" />
+              <img src={guide.logo} alt="" className="size-4 shrink-0 object-contain" />
              {guide.label}
            </SelectValue>
          </SelectTrigger>
          <SelectContent>
            {FRAMEWORKS.map((f) => (
              <SelectItem key={f.id} value={f.id}>
-                <img src={f.logo} alt="" className="size-4" />
+                <img src={f.logo} alt="" className="size-4 shrink-0 object-contain" />
                {f.label}
              </SelectItem>
            ))}
@ -661,87 +556,91 @@ function ConnectAgent({
        </Select>
      </div>

-      <Step title="Get a LiteLLM key">
-        {canMintTracingKey && !readOnly ? (
-          <TracingKey accessToken={accessToken} tracingKey={tracingKey} onCreated={setTracingKey} />
-        ) : (
-          <p className="text-sm text-muted-foreground">
-            Use any LiteLLM virtual key you already have, or ask a proxy admin for one.
-          </p>
-        )}
-      </Step>
-
-      <Step
-        title={
-          <span className="inline-flex items-center gap-1.5">
-            Let <img src={anthropicLogo.src} alt="" className="size-3.5" /> Claude Code or
-            <img src={openaiLogo.src} alt="" className="size-3.5" /> Codex connect it
-          </span>
-        }
-      >
-        <p className="mb-3 text-sm leading-6 text-muted-foreground">
-          Run this in your agent’s project. It starts your coding agent with the setup task and reads the key from
-          LITELLM_API_KEY.
-        </p>
-        <CodeBlock
-          code={codingAgentCommand(codingAgent, codingAgentPrompt(proxyUrl, guide))}
-          wrap
-          tabs={
-            <LineTabs
-              value={codingAgent}
-              options={["Claude Code", "Codex"]}
-              onChange={setCodingAgent}
-              logos={CODING_AGENT_LOGOS}
-            />
-          }
-        />
-      </Step>
-
-      <details className="mt-6 border-y py-4">
-        <summary className="cursor-pointer text-sm font-medium">Set up manually</summary>
-        <Step title="Install dependencies">
-          <CodeBlock
-            code={install}
-            tabs={
-              guide.typescript ? (
-                <FileLabel>npm</FileLabel>
-              ) : (
-                <LineTabs value={installer} options={["pip", "uv"]} onChange={setInstaller} />
-              )
-            }
-          />
+      <CodingAgentSetup proxyUrl={proxyUrl} guide={guide} model={model} />
+      <details className="mt-6 border-t pt-6">
+        <summary className="w-fit cursor-pointer text-sm font-medium">Set up manually</summary>
+        <Step title="Get a LiteLLM key">
+          {canMintTracingKey && !readOnly ? (
+            <TracingKey accessToken={accessToken} tracingKey={tracingKey} onCreated={setTracingKey} />
+          ) : (
+            <p className="text-sm text-muted-foreground">
+              Use any LiteLLM virtual key you already have, or ask a proxy admin for one.
+            </p>
+          )}
        </Step>
+        {install && (
+          <Step title="Install dependencies">
+            <CodeBlock
+              code={install}
+              wrap
+              tabs={
+                guide.language === "typescript" ? (
+                  <FileLabel>npm</FileLabel>
+                ) : (
+                  <LineTabs value={installer} options={["pip", "uv"]} onChange={setInstaller} />
+                )
+              }
+            />
+          </Step>
+        )}
+        {guide.plugin && (
+          <Step title="Enable the plugin">
+            <p className="text-sm leading-6 text-muted-foreground">
+              Install and enable the{" "}
+              <a className="underline underline-offset-4" href={guide.plugin.url} target="_blank" rel="noreferrer">
+                {guide.plugin.label}
+              </a>
+              . {guide.plugin.instruction}
+            </p>
+          </Step>
+        )}
        <Step title="Configure environment">
+          <p className="mb-3 text-sm leading-6 text-muted-foreground">
+            {tracingKey ? (
+              <>
+                Tracing uses the key above. Set <code>LITELLM_API_KEY</code> to a key with model access.
+              </>
+            ) : (
+              <>
+                Set <code>LITELLM_API_KEY</code> to your LiteLLM key.
+              </>
+            )}
+          </p>
          <CodeBlock
            code={tracingEnvSnippet(proxyUrl, tracingKey)}
            display={tracingEnvSnippet(proxyUrl, tracingKey && maskSecret(tracingKey))}
            tabs={<FileLabel>Shell</FileLabel>}
+            wrap
          />
        </Step>
        <Step title="Run your agent">
-          <p className="mb-2 text-sm text-muted-foreground">
-            Replace the example model with a model configured on your proxy.
+          <p className="mb-3 text-sm leading-6 text-muted-foreground">
+            {guide.existingModel ? "Keep your existing model settings. " : "Save and run this example. "}
+            Replace <code>research_agent</code> with your agent’s name.
+            {!guide.existingModel && " Use a model configured on this proxy."}
          </p>
-          <CodeBlock
-            code={guide.typescript ? quickstart : `import os\n\n${quickstart}`}
-            tabs={<FileLabel>{guide.typescript ? "my_agent.ts" : "my_agent.py"}</FileLabel>}
-          />
-          <div className="mt-3">
-            <CodeBlock code={guide.typescript ? TS_RUN_SNIPPET : PY_RUN_SNIPPET} tabs={<FileLabel>Shell</FileLabel>} />
-          </div>
+          <CodeBlock code={quickstart} tabs={<FileLabel>{guide.fileName}</FileLabel>} wrap />
+          {guide.note && <p className="mt-3 text-sm leading-6 text-muted-foreground">{guide.note}</p>}
+          {!guide.existingModel && (
+            <div className="mt-3">
+              <CodeBlock
+                code={guide.language === "typescript" ? "npx tsx agent.mts" : "python agent.py"}
+                tabs={<FileLabel>Shell</FileLabel>}
+              />
+            </div>
+          )}
+          <a
+            href={`${DOCS_URL}?framework=${guide.id}#send-your-first-trace`}
+            className="mt-3 inline-flex items-center gap-1 text-sm underline underline-offset-4"
+            target="_blank"
+            rel="noreferrer"
+          >
+            View in docs <ArrowUpRight aria-hidden="true" className="size-3.5" />
+          </a>
        </Step>
      </details>

      <TraceReceipt connected={connected} checked={checked} checking={checking} onCheck={onCheck} />
-
-      {!connected && (
-        <section className="mt-6">
-          <h3 className="mb-2 text-sm font-medium">
-            Example run <span className="font-normal text-muted-foreground">(sample data, not your runs)</span>
-          </h3>
-          <TracePreview />
-        </section>
-      )}
    </>
  );
 }
@ -755,6 +654,7 @@ export function TracingSetupCard({
  checking = false,
  readOnly = false,
  canMintTracingKey = false,
+  onDemo,
 }: {
  detail: string | null;
  accessToken: string;
@ -764,6 +664,7 @@ export function TracingSetupCard({
  checking?: boolean;
  readOnly?: boolean;
  canMintTracingKey?: boolean;
+  onDemo?: () => void;
 }) {
  const [checked, setChecked] = useState(false);
  const enabled = detail === null;
@ -773,9 +674,18 @@ export function TracingSetupCard({
  };

  return (
-    <div className="w-full py-6 pb-12" data-testid="tracing-setup-card">
-      <div className="flex items-start gap-4">
+    <div className="w-full max-w-3xl pb-8" data-testid="tracing-setup-card">
+      {onDemo && <LensPreviewButton onClick={onDemo} />}
+      <div className="flex flex-wrap items-center gap-x-4 gap-y-2">
        <h2 className="text-xl font-semibold tracking-tight">{setupTitle(enabled, connected)}</h2>
+        <span role="status" className="inline-flex items-center gap-1.5 text-xs text-muted-foreground">
+          {enabled ? (
+            <ActiveDot />
+          ) : (
+            <span aria-hidden="true" className="size-1.5 rounded-full bg-muted-foreground/50" />
+          )}
+          {enabled ? "Tracing enabled" : "Tracing is not enabled"}
+        </span>
        <a
          className="ml-auto inline-flex shrink-0 items-center gap-1 text-sm underline underline-offset-4"
          href={DOCS_URL}
@ -790,10 +700,6 @@ export function TracingSetupCard({
          ? "Send your agent’s runs to LiteLLM to see its inputs, outputs, and tool calls."
          : "Tracing needs ClickHouse and a small update to your LiteLLM proxy configuration."}
      </p>
-      <p role="status" className="mt-4 flex items-center gap-2 text-sm">
-        {enabled && <ActiveDot />}
-        {enabled ? "Tracing enabled" : "Tracing is not enabled"}
-      </p>
      {enabled ? (
        <ConnectAgent
          accessToken={accessToken}
--- a/ui/litellm-dashboard/src/components/view_logs/TraceView/spanProvider.ts
+++ b/ui/litellm-dashboard/src/components/view_logs/TraceView/spanProvider.ts
@ -1,3 +1,4 @@
+import { useLensDemo } from "@/components/lens/LensDemoContext";
 import { useModelCostMap } from "@/app/(dashboard)/hooks/models/useModelCostMap";
 import { getProviderLogoAndName } from "@/components/provider_info_helpers";

@ -29,6 +30,7 @@ export function resolveSpanProvider(model: string | null, lookup: ProviderLookup
 }

 export function useSpanProvider(model: string | null): string | null {
-  const { data } = useModelCostMap();
+  const demo = useLensDemo();
+  const { data } = useModelCostMap(!demo && model !== null);
  return resolveSpanProvider(model, costMapLookup(data));
 }
--- a/ui/litellm-dashboard/src/components/view_logs/TraceView/tracingSetupGuides.ts
+++ b/ui/litellm-dashboard/src/components/view_logs/TraceView/tracingSetupGuides.ts
@ -0,0 +1,501 @@
+import langgraphLogo from "../../../../public/assets/logos/langgraph-color.svg";
+import langchainLogo from "../../../../public/assets/logos/langchain.svg";
+import openaiAgentsLogo from "../../../../public/assets/logos/openai-agents.svg";
+import anthropicLogo from "../../../../public/assets/logos/anthropic.svg";
+import crewaiLogo from "../../../../public/assets/logos/crewai-color.svg";
+import pydanticAiLogo from "../../../../public/assets/logos/pydantic-ai-color.svg";
+import llamaindexLogo from "../../../../public/assets/logos/llamaindex-color.svg";
+import vercelLogo from "../../../../public/assets/logos/vercel.svg";
+import otelLogo from "../../../../public/assets/logos/opentelemetry.svg";
+
+import adkLogo from "../../../../public/assets/logos/google-adk.png";
+import strandsLogo from "../../../../public/assets/logos/strands.svg";
+import hermesLogo from "../../../../public/assets/logos/hermes.png";
+import openclawLogo from "../../../../public/assets/logos/openclaw.png";
+
+export interface FrameworkGuide {
+  id: string;
+  label: string;
+  logo: string;
+  install?: string;
+  language: "python" | "typescript" | "json" | "yaml";
+  quickstart: string;
+  fileName: string;
+  existingModel?: boolean;
+  note?: string;
+  plugin?: { label: string; url: string; instruction: string };
+}
+
+export const FRAMEWORKS: readonly FrameworkGuide[] = [
+  {
+    id: "deepagents",
+    label: "DeepAgents",
+    logo: langgraphLogo.src,
+    install:
+      "pip install opentelemetry-distro opentelemetry-exporter-otlp-proto-http deepagents openinference-instrumentation-langchain langchain-openai",
+    language: "python",
+    quickstart: `import os
+
+AGENT_NAME = "research_agent"
+
+from opentelemetry.instrumentation.auto_instrumentation import initialize
+
+initialize()
+
+from deepagents import create_deep_agent
+
+from langchain_openai import ChatOpenAI
+
+model = ChatOpenAI(
+    model={MODEL},
+    base_url={BASE_URL},
+    api_key=os.environ["LITELLM_API_KEY"],
+)
+
+agent = create_deep_agent(name=AGENT_NAME, model=model, tools=[])
+result = agent.invoke({"messages": [{"role": "user", "content": "What is an agent trace?"}]})
+print(result["messages"][-1].content)`,
+    fileName: "agent.py",
+  },
+  {
+    id: "langgraph",
+    label: "LangGraph",
+    logo: langgraphLogo.src,
+    install:
+      "pip install opentelemetry-distro opentelemetry-exporter-otlp-proto-http langgraph openinference-instrumentation-langchain langchain-openai",
+    language: "python",
+    quickstart: `import os
+
+AGENT_NAME = "research_agent"
+
+from opentelemetry.instrumentation.auto_instrumentation import initialize
+
+initialize()
+
+from langgraph.graph import END, START, MessagesState, StateGraph
+from langchain_openai import ChatOpenAI
+
+model = ChatOpenAI(
+    model={MODEL},
+    base_url={BASE_URL},
+    api_key=os.environ["LITELLM_API_KEY"],
+)
+graph = StateGraph(MessagesState)
+graph.add_node("answer", lambda state: {"messages": [model.invoke(state["messages"])]})
+graph.add_edge(START, "answer")
+graph.add_edge("answer", END)
+agent = graph.compile(name=AGENT_NAME)
+result = agent.invoke({"messages": [{"role": "user", "content": "What is an agent trace?"}]})
+print(result["messages"][-1].content)`,
+    fileName: "agent.py",
+  },
+  {
+    id: "langchain",
+    label: "LangChain",
+    logo: langchainLogo.src,
+    install:
+      "pip install opentelemetry-distro opentelemetry-exporter-otlp-proto-http langchain openinference-instrumentation-langchain langchain-openai",
+    language: "python",
+    quickstart: `import os
+
+AGENT_NAME = "research_agent"
+
+from opentelemetry.instrumentation.auto_instrumentation import initialize
+
+initialize()
+
+from langchain.agents import create_agent
+
+from langchain_openai import ChatOpenAI
+
+model = ChatOpenAI(
+    model={MODEL},
+    base_url={BASE_URL},
+    api_key=os.environ["LITELLM_API_KEY"],
+)
+
+agent = create_agent(name=AGENT_NAME, model=model, tools=[])
+result = agent.invoke({"messages": [{"role": "user", "content": "What is an agent trace?"}]})
+print(result["messages"][-1].content)`,
+    fileName: "agent.py",
+  },
+  {
+    id: "openai-agents",
+    label: "OpenAI Agents",
+    logo: openaiAgentsLogo.src,
+    install:
+      "pip install opentelemetry-distro opentelemetry-exporter-otlp-proto-http openai-agents openinference-instrumentation-openai-agents",
+    language: "python",
+    quickstart: `import os
+
+AGENT_NAME = "research_agent"
+
+from opentelemetry.instrumentation.auto_instrumentation import initialize
+
+initialize()
+
+from agents import Agent, Runner
+
+from agents import OpenAIChatCompletionsModel
+from openai import AsyncOpenAI
+
+client = AsyncOpenAI(base_url={BASE_URL}, api_key=os.environ["LITELLM_API_KEY"])
+model = OpenAIChatCompletionsModel(model={MODEL}, openai_client=client)
+
+agent = Agent(name=AGENT_NAME, model=model)
+result = Runner.run_sync(agent, "What is an agent trace?")
+print(result.final_output)`,
+    fileName: "agent.py",
+  },
+  {
+    id: "claude",
+    label: "Claude Agent SDK",
+    logo: anthropicLogo.src,
+    install:
+      "pip install opentelemetry-distro opentelemetry-exporter-otlp-proto-http claude-agent-sdk openinference-instrumentation-claude-agent-sdk",
+    language: "python",
+    quickstart: `import asyncio
+import os
+
+AGENT_NAME = "research_agent"
+
+os.environ["OTEL_RESOURCE_ATTRIBUTES"] = f"gen_ai.agent.name={AGENT_NAME}"
+
+from opentelemetry.instrumentation.auto_instrumentation import initialize
+
+initialize()
+
+from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query
+
+options = ClaudeAgentOptions(
+    model={MODEL},
+    env={"ANTHROPIC_BASE_URL": {PROXY_URL}, "ANTHROPIC_AUTH_TOKEN": os.environ["LITELLM_API_KEY"]},
+    tools=[],
+    max_turns=1,
+)
+
+async def main():
+    async for message in query(prompt="What is an agent trace?", options=options):
+        if isinstance(message, ResultMessage):
+            print(message.result)
+
+asyncio.run(main())`,
+    fileName: "agent.py",
+    note: "This captures SDK input and output; internal model calls are not exposed by this instrumentor.",
+  },
+  {
+    id: "crewai",
+    label: "CrewAI",
+    logo: crewaiLogo.src,
+    install:
+      "pip install opentelemetry-distro opentelemetry-exporter-otlp-proto-http crewai openinference-instrumentation-crewai",
+    language: "python",
+    quickstart: `import os
+
+AGENT_NAME = "research_agent"
+
+from opentelemetry.instrumentation.auto_instrumentation import initialize
+
+initialize()
+
+from crewai import Agent, Crew, Task
+
+from crewai import LLM
+
+model = LLM(
+    model={OPENAI_MODEL},
+    base_url={BASE_URL},
+    api_key=os.environ["LITELLM_API_KEY"],
+)
+
+agent = Agent(
+    role=AGENT_NAME,
+    goal="Answer questions clearly",
+    backstory="You explain technical concepts.",
+    llm=model,
+)
+task = Task(description="What is an agent trace?", expected_output="A short answer", agent=agent)
+print(Crew(agents=[agent], tasks=[task]).kickoff())`,
+    fileName: "agent.py",
+  },
+  {
+    id: "pydantic-ai",
+    label: "Pydantic AI",
+    logo: pydanticAiLogo.src,
+    install: "pip install opentelemetry-distro opentelemetry-exporter-otlp-proto-http pydantic-ai",
+    language: "python",
+    quickstart: `import os
+
+AGENT_NAME = "research_agent"
+
+from opentelemetry.instrumentation.auto_instrumentation import initialize
+
+initialize()
+
+from pydantic_ai import Agent
+
+from pydantic_ai.models.openai import OpenAIChatModel
+from pydantic_ai.providers.openai import OpenAIProvider
+
+model = OpenAIChatModel(
+    {MODEL},
+    provider=OpenAIProvider(base_url={BASE_URL}, api_key=os.environ["LITELLM_API_KEY"]),
+)
+
+Agent.instrument_all()
+agent = Agent(model, name=AGENT_NAME)
+print(agent.run_sync("What is an agent trace?").output)`,
+    fileName: "agent.py",
+  },
+  {
+    id: "llamaindex",
+    label: "LlamaIndex",
+    logo: llamaindexLogo.src,
+    install:
+      "pip install opentelemetry-distro opentelemetry-exporter-otlp-proto-http llama-index-core openinference-instrumentation-llama-index llama-index-llms-openai-like",
+    language: "python",
+    quickstart: `import asyncio
+import os
+
+AGENT_NAME = "research_agent"
+
+
+os.environ["OTEL_RESOURCE_ATTRIBUTES"] = f"gen_ai.agent.name={AGENT_NAME}"
+
+from opentelemetry.instrumentation.auto_instrumentation import initialize
+
+initialize()
+
+from openinference.instrumentation.llama_index import LlamaIndexInstrumentor
+
+LlamaIndexInstrumentor().instrument()
+from llama_index.core.agent.workflow import FunctionAgent
+
+from llama_index.llms.openai_like import OpenAILike
+
+model = OpenAILike(
+    model={MODEL},
+    api_base={BASE_URL},
+    api_key=os.environ["LITELLM_API_KEY"],
+    is_chat_model=True,
+    is_function_calling_model=True,
+)
+
+agent = FunctionAgent(name=AGENT_NAME, llm=model, tools=[])
+async def main():
+    result = await agent.run(user_msg="What is an agent trace?")
+    print(result)
+
+asyncio.run(main())`,
+    fileName: "agent.py",
+    note: "The resource attribute supplies the agent name because this instrumentor does not export FunctionAgent.name.",
+  },
+  {
+    id: "adk",
+    label: "Google ADK",
+    logo: adkLogo.src,
+    install: "pip install opentelemetry-distro opentelemetry-exporter-otlp-proto-http google-adk",
+    language: "python",
+    quickstart: `import asyncio
+import os
+
+AGENT_NAME = "research_agent"
+
+os.environ["OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"] = "SPAN_ONLY"
+
+from opentelemetry.instrumentation.auto_instrumentation import initialize
+
+initialize()
+
+from google.adk.agents import Agent
+from google.adk.runners import InMemoryRunner
+
+from google.adk.models.lite_llm import LiteLlm
+
+model = LiteLlm(
+    model={OPENAI_MODEL},
+    api_base={BASE_URL},
+    api_key=os.environ["LITELLM_API_KEY"],
+)
+
+agent = Agent(name=AGENT_NAME, model=model)
+asyncio.run(InMemoryRunner(agent=agent).run_debug("What is an agent trace?"))`,
+    fileName: "agent.py",
+    note: "SPAN_ONLY records the messages needed to inspect and investigate the run.",
+  },
+  {
+    id: "strands",
+    label: "Strands",
+    logo: strandsLogo.src,
+    install: 'pip install opentelemetry-distro opentelemetry-exporter-otlp-proto-http "strands-agents[otel]" openai',
+    language: "python",
+    quickstart: `import os
+
+AGENT_NAME = "research_agent"
+
+
+os.environ["OTEL_SEMCONV_STABILITY_OPT_IN"] = "gen_ai_latest_experimental,gen_ai_span_attributes_only"
+
+from opentelemetry.instrumentation.auto_instrumentation import initialize
+
+initialize()
+
+from strands import Agent
+
+from strands.models.openai import OpenAIModel
+
+model = OpenAIModel(
+    client_args={"base_url": {BASE_URL}, "api_key": os.environ["LITELLM_API_KEY"]},
+    model_id={MODEL},
+)
+
+agent = Agent(name=AGENT_NAME, model=model)
+print(agent("What is an agent trace?"))`,
+    fileName: "agent.py",
+    note: "The semantic-convention setting enables message content in spans.",
+  },
+  {
+    id: "vercel",
+    label: "Vercel AI SDK",
+    logo: vercelLogo.src,
+    install:
+      "npm install ai @ai-sdk/otel @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http @ai-sdk/openai-compatible",
+    language: "typescript",
+    quickstart: `import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { OpenTelemetry } from "@ai-sdk/otel";
+import { generateText, registerTelemetry } from "ai";
+
+const sdk = new NodeSDK({ traceExporter: new OTLPTraceExporter() });
+sdk.start();
+registerTelemetry(new OpenTelemetry());
+
+const AGENT_NAME = "research_agent";
+const litellm = createOpenAICompatible({
+  name: "litellm",
+  baseURL: {BASE_URL},
+  apiKey: process.env.LITELLM_API_KEY,
+});
+const model = litellm({MODEL});
+
+try {
+  const { text } = await generateText({
+    model,
+    prompt: "What is an agent trace?",
+    telemetry: { functionId: AGENT_NAME },
+  });
+  console.log(text);
+} finally {
+  await sdk.shutdown();
+}`,
+    fileName: "agent.mts",
+  },
+  {
+    id: "openclaw",
+    label: "OpenClaw",
+    logo: openclawLogo.src,
+    language: "json",
+    quickstart: `{
+  "agents": {
+    "list": [{ "id": "research_agent" }]
+  },
+  "plugins": {
+    "entries": { "diagnostics-otel": { "enabled": true } }
+  },
+  "diagnostics": {
+    "enabled": true,
+    "otel": {
+      "enabled": true,
+      "tracesEndpoint": "{TRACE_URL}",
+      "headers": { "Authorization": "Bearer \${LITELLM_API_KEY}" },
+      "captureContent": true,
+      "traces": true,
+      "metrics": false,
+      "logs": false,
+      "sampleRate": 1
+    }
+  }
+}`,
+    existingModel: true,
+    fileName: "openclaw.json",
+    note: 'Set LITELLM_API_KEY to your LiteLLM key, then run openclaw agent --local --session-id first-trace --message "What is an agent trace?". Select research_agent in Lens. Restart an existing gateway after changing the config.',
+    plugin: {
+      label: "diagnostics-otel plugin",
+      url: "https://docs.openclaw.ai/plugins/reference/diagnostics-otel",
+      instruction:
+        "Set your agent ID once in ~/.openclaw/openclaw.json. Keep your existing model and workspace settings when adding the tracing configuration.",
+    },
+  },
+  {
+    id: "hermes",
+    label: "Hermes",
+    logo: hermesLogo.src,
+    language: "yaml",
+    quickstart: `resource_attributes:
+  gen_ai.agent.name: research_agent
+content_capture: full
+backends:
+  - type: otlp
+    endpoint: {TRACE_URL}
+    headers:
+      Authorization: "Bearer \${LITELLM_API_KEY}"
+    metrics: false
+    logs: false`,
+    existingModel: true,
+    fileName: "hermes_otel.yaml",
+    note: "Start a new Hermes session and ask a question. The configured name research_agent appears in Lens. Hermes' built-in diagnostic telemetry alone does not include the conversation content needed for investigations.",
+    plugin: {
+      label: "community hermes-otel plugin",
+      url: "https://github.com/briancaffey/hermes-otel#install",
+      instruction: "Set LITELLM_API_KEY to your LiteLLM key, then add this to ~/.hermes/hermes_otel.yaml.",
+    },
+  },
+  {
+    id: "otel",
+    label: "OpenTelemetry",
+    logo: otelLogo.src,
+    install: "pip install opentelemetry-distro opentelemetry-exporter-otlp-proto-http openai",
+    language: "python",
+    quickstart: `import os
+
+AGENT_NAME = "research_agent"
+
+from opentelemetry.instrumentation.auto_instrumentation import initialize
+
+initialize()
+
+from opentelemetry import trace
+from openai import OpenAI
+
+client = OpenAI(base_url={BASE_URL}, api_key=os.environ["LITELLM_API_KEY"])
+
+with trace.get_tracer(__name__).start_as_current_span(AGENT_NAME) as span:
+    span.set_attribute("gen_ai.agent.name", AGENT_NAME)
+    span.set_attribute("openinference.span.kind", "AGENT")
+    span.set_attribute("input.value", "What is an agent trace?")
+    result = client.chat.completions.create(
+        model={MODEL},
+        messages=[{"role": "user", "content": "What is an agent trace?"}],
+    )
+    answer = result.choices[0].message.content
+    span.set_attribute("output.value", str(answer))
+    print(answer)`,
+    fileName: "agent.py",
+  },
+];
+
+export function frameworkSnippet(guide: FrameworkGuide, proxyUrl: string, model: string, tracingKey = false): string {
+  const values: Record<string, string> = {
+    MODEL: JSON.stringify(model),
+    OPENAI_MODEL: JSON.stringify(`openai/${model}`),
+    BASE_URL: JSON.stringify(`${proxyUrl}/v1`),
+    PROXY_URL: JSON.stringify(proxyUrl),
+    TRACE_URL: `${proxyUrl}/v1/traces`,
+  };
+  const code = guide.quickstart.replace(
+    /\{(MODEL|OPENAI_MODEL|BASE_URL|PROXY_URL|TRACE_URL)\}/g,
+    (_, name: string) => values[name],
+  );
+  return tracingKey && guide.existingModel ? code.replaceAll("${LITELLM_API_KEY}", "${LITELLM_TRACING_KEY}") : code;
+}
--- a/ui/litellm-dashboard/src/components/view_logs/TraceView/useAgentTraces.ts
+++ b/ui/litellm-dashboard/src/components/view_logs/TraceView/useAgentTraces.ts
@ -1,3 +1,4 @@
+import { useLensDemo } from "@/components/lens/LensDemoContext";
 import { useInfiniteQuery, useQuery, type UseQueryOptions } from "@tanstack/react-query";
 import moment from "moment";
 import { useMemo } from "react";
@ -65,6 +66,7 @@ export function useAgentTraces({
  isLiveTail,
  enabled,
 }: UseAgentTracesOptions): AgentTracesResult {
+  const demo = useLensDemo();
  const fetchPage = (pageParam: unknown): Promise<TracePage> => {
    const nowMs = Date.now();
    const listOptions: Parameters<typeof agentTraceListCall>[0] = {
@ -73,7 +75,11 @@ export function useAgentTraces({
      endMs: isCustomDate ? moment(endTime).valueOf() : nowMs,
      cursor: pageParam as string | null,
    };
-    return agentTraceListCall(listOptions);
+    return demo
+      ? demo.client.get<TracePage>("/v1/traces", {
+          query: { start_ms: listOptions.startMs, end_ms: listOptions.endMs, cursor: listOptions.cursor },
+        })
+      : agentTraceListCall(listOptions);
  };
  const queryOptions: Parameters<typeof useInfiniteQuery<TracePage, Error>>[0] = {
    queryKey: ["agentTraces", accessToken, startTime, endTime, isCustomDate],
@ -106,9 +112,11 @@ export function useAgentTraces({
 }

 export function useTraceAvailability(accessToken: string, enabled: boolean) {
+  const demo = useLensDemo();
+  const client = demo?.client ?? apiClient;
  const options: UseQueryOptions<TracePage, Error, boolean> = {
    queryKey: ["trace-availability", accessToken],
-    queryFn: () => apiClient.get<TracePage>("/v1/traces", { accessToken, query: { start_ms: 0 } }),
+    queryFn: () => client.get<TracePage>("/v1/traces", { accessToken, query: { start_ms: 0 } }),
    select: (page: TracePage) => page.data.length > 0,
    enabled,
    retry: false,