Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

feat(web): AI Gateway onboarding (#19390)

Trang Nguyendf7480dd0c75
diff --git a/web/src/__tests__/organization-settings-pages.clienttest.tsx b/web/src/__tests__/organization-settings-pages.clienttest.tsx
index 2f06a0fd9a..5abb49f02f 100644
--- a/web/src/__tests__/organization-settings-pages.clienttest.tsx
+++ b/web/src/__tests__/organization-settings-pages.clienttest.tsx
@@ -111,7 +111,12 @@ vi.mock("next-auth/react", () => ({ useSession: vi.fn() }));
const getSetupStatusQuery = vi.hoisted(() => vi.fn());
vi.mock("@/src/utils/api", () => ({
- api: { aiGateway: { getSetupStatus: { useQuery: getSetupStatusQuery } } },
+ api: {
+ aiGateway: {
+ getSetupStatus: { useQuery: getSetupStatusQuery },
+ listApiKeys: { useQuery: () => ({ data: undefined }) },
+ },
+ },
}));
vi.mock("@/src/features/ai-gateway", () => ({
diff --git a/web/src/components/PagedSettingsContainer.tsx b/web/src/components/PagedSettingsContainer.tsx
index 396a7ce271..dd3c0396d0 100644
--- a/web/src/components/PagedSettingsContainer.tsx
+++ b/web/src/components/PagedSettingsContainer.tsx
@@ -21,6 +21,8 @@ type SettingsPage = {
show?: boolean | (() => boolean);
/** Lists the page but blocks opening it; shown as the entry's tooltip */
disabledReason?: string;
+ /** Marks the entry with a dot when something there needs the user */
+ indicator?: boolean;
} & (
| { content: ReactNode }
| {
@@ -36,6 +38,8 @@ type SettingsProps = {
fullHeight?: boolean;
/** Replaces a section's label; rendered even when the section has no pages */
sectionHeaders?: Record<string, ReactNode>;
+ /** Shown next to a section's default label, e.g. a Beta badge */
+ sectionBadges?: Record<string, ReactNode>;
};
const pageKey = (page: SettingsPage) => `${page.section ?? ""}:${page.slug}`;
@@ -45,6 +49,7 @@ export const PagedSettingsContainer = ({
activeSlug,
fullHeight = false,
sectionHeaders = {},
+ sectionBadges = {},
}: SettingsProps) => {
const router = useRouter();
const availablePages = pages.filter((page) =>
@@ -107,7 +112,10 @@ export const PagedSettingsContainer = ({
{groups.map((group) => (
<SelectGroup key={group.section ?? "default"}>
{group.section ? (
- <SelectLabel>{group.section}</SelectLabel>
+ <SelectLabel className="flex items-center gap-2">
+ {group.section}
+ {sectionBadges[group.section]}
+ </SelectLabel>
) : null}
{group.pages.map((page) => (
<SelectItem
@@ -146,8 +154,9 @@ export const PagedSettingsContainer = ({
>
{group.section
? (sectionHeaders[group.section] ?? (
- <span className="text-foreground flex h-8 items-center px-2 text-xs font-bold">
+ <span className="text-foreground flex h-8 items-center gap-2 px-2 text-xs font-bold">
{group.section}
+ {sectionBadges[group.section]}
</span>
))
: null}
@@ -199,6 +208,7 @@ function NavEntry({
className="hover:bg-muted hover:text-foreground flex h-8 flex-row items-center gap-2 rounded-sm px-2"
>
{page.title}
+ {page.indicator && <NavIndicator />}
{!page.internal && <ArrowUpRight size="base" __rawClassName="inline" />}
</Link>
);
@@ -211,15 +221,25 @@ function NavEntry({
<span
onClick={handleSelect}
className={cn(
- "hover:bg-muted hover:text-foreground flex h-8 cursor-pointer items-center rounded-sm px-2",
+ "hover:bg-muted hover:text-foreground flex h-8 cursor-pointer items-center gap-2 rounded-sm px-2",
isActive && "bg-muted text-primary font-bold",
)}
>
{page.title}
+ {page.indicator && <NavIndicator />}
</span>
);
}
+function NavIndicator() {
+ return (
+ <span
+ aria-label="Needs your attention"
+ className="size-1.75 shrink-0 rounded-full bg-orange-400"
+ />
+ );
+}
+
function DisabledNavEntry({
title,
reason,
diff --git a/web/src/features/ai-gateway/components/GatewayLaunch/GatewayHero.stories.tsx b/web/src/features/ai-gateway/components/GatewayLaunch/GatewayHero.stories.tsx
new file mode 100644
index 0000000000..4febd66ee1
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewayLaunch/GatewayHero.stories.tsx
@@ -0,0 +1,6 @@
+import preview from "@/.storybook/preview";
+import { GatewayHero } from "./GatewayHero";
+
+const meta = preview.meta({ component: GatewayHero });
+
+export const Default = meta.story({});
diff --git a/web/src/features/ai-gateway/components/GatewayLaunch/GatewayHero.tsx b/web/src/features/ai-gateway/components/GatewayLaunch/GatewayHero.tsx
new file mode 100644
index 0000000000..d654c796ac
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewayLaunch/GatewayHero.tsx
@@ -0,0 +1,41 @@
+import { ArrowRight } from "@langfuse/icons";
+import { SiAnthropic, SiOpenai } from "@langfuse/icons/si";
+
+import styles from "@/src/features/ai-gateway/components/GatewayLaunch/gatewayLaunch.module.css";
+import { GatewayReceipt } from "@/src/features/ai-gateway/components/GatewayLaunch/GatewayReceipt";
+import { cn } from "@/src/utils/tailwind";
+
+/** Illustration: provider spend flowing into a per-person receipt; shrinks first in short dialogs. */
+export function GatewayHero() {
+ return (
+ <div
+ className={cn(
+ "bg-surface-section flex h-72 min-h-48 items-center justify-center gap-5 overflow-hidden border-b px-8",
+ styles.dotGrid,
+ )}
+ >
+ <div className="flex flex-col gap-2">
+ <span className="text-muted-foreground text-2xs font-mono tracking-wider whitespace-nowrap">
+ WHAT THE PROVIDERS SEND YOU
+ </span>
+ <div className="bg-background flex items-center gap-6 border px-3 py-2.5">
+ <span className="flex items-center gap-2">
+ <SiAnthropic size="base" />
+ <SiOpenai size="base" />
+ </span>
+ <span className="font-mono text-xs font-bold">$58,240.22</span>
+ </div>
+ </div>
+ <div
+ aria-hidden="true"
+ className="text-muted-foreground mt-6 flex items-center"
+ >
+ <span className="border-muted-foreground w-10 border-t border-dashed" />
+ <ArrowRight size="sm" color="muted" __rawClassName="-ml-1" />
+ </div>
+ <div className="w-64 shrink-0">
+ <GatewayReceipt variant="dialog" />
+ </div>
+ </div>
+ );
+}
diff --git a/web/src/features/ai-gateway/components/GatewayLaunch/GatewayLaunchBanner.stories.tsx b/web/src/features/ai-gateway/components/GatewayLaunch/GatewayLaunchBanner.stories.tsx
new file mode 100644
index 0000000000..f5c4e4bb52
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewayLaunch/GatewayLaunchBanner.stories.tsx
@@ -0,0 +1,108 @@
+import { PostHog } from "posthog-js";
+import { PostHogProvider } from "posthog-js/react";
+import { expect, fn, waitFor, within } from "storybook/test";
+
+import preview from "@/.storybook/preview";
+import { GatewayLaunchBanner } from "./GatewayLaunchBanner";
+
+const acmeRobotics = {
+ organizationId: "org-acme-robotics",
+ organizationName: "Acme Robotics",
+ canManage: true,
+};
+const acmeResearch = {
+ organizationId: "org-acme-research",
+ organizationName: "Acme Research",
+ canManage: true,
+};
+
+const capture = fn<PostHog["capture"]>();
+const client = new PostHog();
+client.capture = capture;
+
+const meta = preview.meta({
+ component: GatewayLaunchBanner,
+ decorators: [
+ (Story) => (
+ <PostHogProvider client={client}>
+ <Story />
+ </PostHogProvider>
+ ),
+ ],
+ beforeEach: () => {
+ capture.mockClear();
+ // Dismissals persist in localStorage; every story load starts with the banner shown.
+ for (const key of Object.keys(localStorage)) {
+ if (key.startsWith("ai-gateway-launch:")) localStorage.removeItem(key);
+ }
+ },
+});
+
+export const Setup = meta.story({
+ args: {
+ userId: "user-maya",
+ target: {
+ organizationId: acmeRobotics.organizationId,
+ state: "setup",
+ setupOptions: [acmeRobotics],
+ },
+ },
+});
+
+export const SetupSeveralOrgs = meta.story({
+ args: {
+ userId: "user-maya",
+ target: {
+ organizationId: acmeRobotics.organizationId,
+ state: "setup",
+ setupOptions: [acmeRobotics, acmeResearch],
+ },
+ },
+});
+
+export const AskAdmin = meta.story({
+ args: {
+ userId: "user-priya",
+ target: {
+ organizationId: acmeRobotics.organizationId,
+ state: "ask-admin",
+ setupOptions: [],
+ },
+ },
+});
+
+export const GetApiKey = meta.story({
+ args: {
+ userId: "user-priya",
+ target: {
+ organizationId: acmeRobotics.organizationId,
+ state: "get-key",
+ setupOptions: [],
+ },
+ },
+});
+
+export const OpensOrgPicker = SetupSeveralOrgs.extend({
+ name: "(Test) Opens Org Picker",
+ play: async ({ canvas, canvasElement, userEvent }) => {
+ const body = within(canvasElement.ownerDocument.body);
+
+ await userEvent.click(canvas.getByRole("button", { name: "Set up" }));
+ await expect(capture).toHaveBeenCalledWith(
+ "ai_gateway_launch:banner_cta_clicked",
+ { state: "setup", orgCount: 2 },
+ undefined,
+ );
+
+ await userEvent.click(body.getByRole("button", { name: "Set up gateway" }));
+ // The dialog fades in, so wait until its menu is fully shown.
+ await waitFor(async () => {
+ await expect(
+ body.getByRole("menuitem", { name: "Acme Robotics" }),
+ ).toBeVisible();
+ await expect(
+ body.getByRole("menuitem", { name: "Acme Research" }),
+ ).toBeVisible();
+ });
+ },
+});
diff --git a/web/src/features/ai-gateway/components/GatewayLaunch/GatewayLaunchBanner.tsx b/web/src/features/ai-gateway/components/GatewayLaunch/GatewayLaunchBanner.tsx
new file mode 100644
index 0000000000..32b9b33b0f
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewayLaunch/GatewayLaunchBanner.tsx
@@ -0,0 +1,111 @@
+import { ArrowRight, X } from "@langfuse/icons";
+import { useState } from "react";
+
+import { DismissController } from "@/src/components/DismissController";
+import { Badge } from "@/src/components/design-system/Badge/Badge";
+import { IconButton } from "@/src/components/design-system/IconButton/IconButton";
+import { Button } from "@/src/components/ui/button";
+import styles from "@/src/features/ai-gateway/components/GatewayLaunch/gatewayLaunch.module.css";
+import { GatewayLaunchDialog } from "@/src/features/ai-gateway/components/GatewayLaunch/GatewayLaunchDialog";
+import { GatewayReceipt } from "@/src/features/ai-gateway/components/GatewayLaunch/GatewayReceipt";
+import {
+ type GatewayLaunchState,
+ type GatewayLaunchTarget,
+} from "@/src/features/ai-gateway/hooks/useGatewayLaunchEligibility";
+import { usePostHogClientCapture } from "@/src/features/posthog-analytics/usePostHogClientCapture";
+import { cn } from "@/src/utils/tailwind";
+
+function ctaLabel(state: GatewayLaunchState) {
+ if (state === "get-key") return "Get API key";
+ if (state === "ask-admin") return "Learn more";
+ return "Set up";
+}
+
+/** Organizations-page banner; the page renders it only when there is a target. */
+export function GatewayLaunchBanner({
+ target,
+ userId,
+}: {
+ target: GatewayLaunchTarget;
+ userId: string;
+}) {
+ const [open, setOpen] = useState(false);
+ const capture = usePostHogClientCapture();
+ const { state, setupOptions } = target;
+ const { organizationId } = target;
+ const captureCta = () =>
+ capture("ai_gateway_launch:banner_cta_clicked", {
+ state,
+ orgCount: setupOptions.length,
+ });
+ const arrow = (
+ <ArrowRight size="base" __rawClassName="ml-1.5" aria-hidden="true" />
+ );
+
+ return (
+ <>
+ <DismissController
+ id={`ai-gateway-launch:v2:${userId}:${state}:${target.organizationId}`}
+ family="callouts"
+ >
+ {({ onDismiss }) => (
+ <div
+ className={cn(
+ "bg-surface-section relative mt-2 mb-4 flex h-24 items-center gap-6 overflow-hidden rounded-lg pr-12 pl-6",
+ styles.dotGrid,
+ styles.bannerDots,
+ )}
+ >
+ <div className="flex min-w-0 flex-1 flex-col gap-1">
+ <div className="flex items-center gap-2">
+ <span className="text-base font-bold">AI Gateway</span>
+ <Badge text="Beta" color="blue" size="sm" font="mono" />
+ </div>
+ <p
+ className="text-muted-foreground truncate text-base"
+ title="One gateway key for full visibility into what your agents cost."
+ >
+ One gateway key for full visibility into what your agents cost.
+ </p>
+ </div>
+ <div className="relative mr-12 hidden h-full w-72 shrink-0 xl:block">
+ <div className="absolute inset-x-0 -top-2">
+ <GatewayReceipt variant="banner" />
+ </div>
+ </div>
+ <div className="flex shrink-0 items-center gap-2">
+ <Button
+ onClick={() => {
+ captureCta();
+ setOpen(true);
+ }}
+ >
+ {ctaLabel(state)}
+ {arrow}
+ </Button>
+ </div>
+ <span className="absolute top-2 right-2">
+ <IconButton
+ icon={X}
+ label="Dismiss"
+ size="sm"
+ onClick={() => {
+ capture("ai_gateway_launch:banner_dismissed", { state });
+ onDismiss();
+ }}
+ />
+ </span>
+ </div>
+ )}
+ </DismissController>
+ <GatewayLaunchDialog
+ key={organizationId}
+ organizationId={organizationId}
+ state={state}
+ setupOptions={setupOptions}
+ open={open}
+ onOpenChange={setOpen}
+ />
+ </>
+ );
+}
diff --git a/web/src/features/ai-gateway/components/GatewayLaunch/GatewayLaunchDialog.stories.tsx b/web/src/features/ai-gateway/components/GatewayLaunch/GatewayLaunchDialog.stories.tsx
new file mode 100644
index 0000000000..9f8f810feb
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewayLaunch/GatewayLaunchDialog.stories.tsx
@@ -0,0 +1,97 @@
+import { getRouter } from "@storybook/nextjs-vite/router.mock";
+import { PostHog } from "posthog-js";
+import { PostHogProvider } from "posthog-js/react";
+import { expect, fn, within } from "storybook/test";
+
+import preview from "@/.storybook/preview";
+import { GatewayLaunchDialog } from "./GatewayLaunchDialog";
+
+const acmeRobotics = {
+ organizationId: "org-acme-robotics",
+ organizationName: "Acme Robotics",
+ canManage: true,
+};
+const acmeResearch = {
+ organizationId: "org-acme-research",
+ organizationName: "Acme Research",
+ canManage: true,
+};
+
+const capture = fn<PostHog["capture"]>();
+const client = new PostHog();
+client.capture = capture;
+
+const meta = preview.meta({
+ component: GatewayLaunchDialog,
+ decorators: [
+ (Story) => (
+ <PostHogProvider client={client}>
+ <Story />
+ </PostHogProvider>
+ ),
+ ],
+ beforeEach: () => {
+ capture.mockClear();
+ },
+});
+
+export const SetupOneOrg = meta.story({
+ args: {
+ organizationId: acmeRobotics.organizationId,
+ state: "setup",
+ setupOptions: [acmeRobotics],
+ open: true,
+ onOpenChange: fn(),
+ },
+});
+
+export const SetupSeveralOrgs = meta.story({
+ args: {
+ organizationId: acmeRobotics.organizationId,
+ state: "setup",
+ setupOptions: [acmeRobotics, acmeResearch],
+ open: true,
+ onOpenChange: fn(),
+ },
+});
+
+export const AskAdmin = meta.story({
+ args: {
+ organizationId: acmeRobotics.organizationId,
+ state: "ask-admin",
+ setupOptions: [],
+ open: true,
+ onOpenChange: fn(),
+ },
+});
+
+export const GetApiKey = meta.story({
+ args: {
+ organizationId: acmeRobotics.organizationId,
+ state: "get-key",
+ setupOptions: [],
+ open: true,
+ onOpenChange: fn(),
+ },
+});
+
+export const PicksOrg = SetupSeveralOrgs.extend({
+ name: "(Test) Picks Org",
+ play: async ({ canvasElement, userEvent }) => {
+ const body = within(canvasElement.ownerDocument.body);
+
+ await userEvent.click(body.getByRole("button", { name: "Set up gateway" }));
+ await userEvent.click(
+ body.getByRole("menuitem", { name: "Acme Research" }),
+ );
+
+ await expect(capture).toHaveBeenCalledWith(
+ "ai_gateway_launch:dialog_setup_clicked",
+ undefined,
+ undefined,
+ );
+ await expect(getRouter().push).toHaveBeenCalledWith(
+ "/organization/org-acme-research/settings/ai-gateway",
+ );
+ },
+});
diff --git a/web/src/features/ai-gateway/components/GatewayLaunch/GatewayLaunchDialog.tsx b/web/src/features/ai-gateway/components/GatewayLaunch/GatewayLaunchDialog.tsx
new file mode 100644
index 0000000000..627d41d73a
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewayLaunch/GatewayLaunchDialog.tsx
@@ -0,0 +1,174 @@
+import { ArrowUpRight, Check } from "@langfuse/icons";
+import Link from "next/link";
+import { useRouter } from "next/router";
+import { useState } from "react";
+
+import { Button } from "@/src/components/design-system/Button/Button";
+import { DropdownIndicator } from "@/src/components/design-system/DropdownIndicator/DropdownIndicator";
+import { DropdownMenu } from "@/src/components/design-system/DropdownMenu/DropdownMenu";
+import { Button as MenuTriggerButton } from "@/src/components/ui/button";
+import { Dialog, DialogContent, DialogTitle } from "@/src/components/ui/dialog";
+import { PopoverLayerProvider } from "@/src/context/LayerContext/PopoverLayerProvider";
+import {
+ type GatewayLaunchState,
+ type GatewayLaunchTarget,
+} from "@/src/features/ai-gateway/hooks/useGatewayLaunchEligibility";
+import { usePostHogClientCapture } from "@/src/features/posthog-analytics/usePostHogClientCapture";
+import { GatewayHero } from "@/src/features/ai-gateway/components/GatewayLaunch/GatewayHero";
+
+const copy = {
+ admin: {
+ title: "Introducing Langfuse AI Gateway",
+ lead: "Point Claude Code, Codex or your SDK at one Langfuse endpoint. See what every member spends.",
+ points: [
+ "A key for every member, cost attributed per person",
+ "Turn models on or off for your org",
+ "Every call traced in Langfuse",
+ ],
+ },
+ member: {
+ title: "Get your own AI Gateway key",
+ lead: "Access Anthropic and OpenAI models with a single key you create yourself.",
+ points: ["Create your own keys", "One key for Anthropic and OpenAI models"],
+ },
+};
+
+export function GatewayLaunchDialog({
+ organizationId,
+ state,
+ setupOptions,
+ open,
+ onOpenChange,
+}: {
+ organizationId: string;
+ state: GatewayLaunchState;
+ setupOptions: GatewayLaunchTarget["setupOptions"];
+ open: boolean;
+ onOpenChange: (open: boolean) => void;
+}) {
+ const capture = usePostHogClientCapture();
+ const router = useRouter();
+ // Menus inside the dialog portal here, so the modal does not hide them from assistive tech.
+ const [popoverContainer, setPopoverContainer] =
+ useState<HTMLDivElement | null>(null);
+ const { title, lead, points } =
+ copy[state === "get-key" ? "member" : "admin"];
+ const setupHref = (orgId: string) =>
+ `/organization/${orgId}/settings/ai-gateway`;
+
+ return (
+ // eslint-disable-next-line @typescript-eslint/no-deprecated -- design-system Dialog has no hero slot
+ <Dialog open={open} onOpenChange={onOpenChange}>
+ {/* eslint-disable-next-line @typescript-eslint/no-deprecated -- design-system Dialog has no hero slot */}
+ <DialogContent
+ className="max-w-160 overflow-visible"
+ closeOnInteractionOutside
+ overlayMode="subtle"
+ >
+ <PopoverLayerProvider container={popoverContainer}>
+ <div className="flex min-h-0 flex-1 flex-col overflow-hidden sm:rounded-lg">
+ <div className="flex min-h-0 flex-1 flex-col overflow-y-auto">
+ <GatewayHero />
+ <div className="flex shrink-0 flex-col gap-2 px-8 pt-6 pb-8">
+ {/* eslint-disable-next-line @typescript-eslint/no-deprecated -- design-system Dialog has no hero slot */}
+ <DialogTitle className="text-xl font-bold tracking-tight">
+ {title}
+ </DialogTitle>
+ <p className="text-muted-foreground text-base leading-relaxed">
+ {lead}
+ </p>
+ <ul className="text-muted-foreground mt-2 flex flex-col gap-1 text-sm">
+ {points.map((point) => (
+ <li key={point} className="flex items-center gap-2">
+ <span className="text-dark-green flex">
+ <Check size="sm" color="inherit" aria-hidden="true" />
+ </span>
+ {point}
+ </li>
+ ))}
+ </ul>
+ </div>
+ </div>
+ <div className="flex shrink-0 items-center justify-between border-t px-8 py-4">
+ <Link
+ href="https://langfuse.com/docs/ai-gateway"
+ target="_blank"
+ rel="noopener noreferrer"
+ onClick={() =>
+ capture("ai_gateway_launch:dialog_learn_more_clicked", {
+ state,
+ })
+ }
+ className="text-muted-foreground hover:text-foreground flex items-center gap-1 text-sm"
+ >
+ Learn more
+ <ArrowUpRight size="sm" aria-hidden="true" />
+ </Link>
+ {state === "setup" && setupOptions.length > 1 && (
+ <DropdownMenu
+ title="Select an organization"
+ items={setupOptions.map((option) => ({
+ type: "item",
+ id: option.organizationId,
+ title: option.organizationName,
+ onClick: () => {
+ capture("ai_gateway_launch:dialog_setup_clicked");
+ router.push(setupHref(option.organizationId));
+ },
+ }))}
+ >
+ {({ getTriggerProps }) => (
+ /** The design-system Button does not forward floating-ui trigger handlers. */
+ <MenuTriggerButton
+ className="gap-1.5"
+ {...getTriggerProps()}
+ >
+ Set up gateway
+ <DropdownIndicator nudge />
+ </MenuTriggerButton>
+ )}
+ </DropdownMenu>
+ )}
+ {state === "setup" && setupOptions.length <= 1 && (
+ <span
+ onClick={() =>
+ capture("ai_gateway_launch:dialog_setup_clicked")
+ }
+ >
+ <Button
+ variant="primary"
+ text="Set up gateway"
+ href={setupHref(organizationId)}
+ />
+ </span>
+ )}
+ {state === "get-key" && (
+ <span
+ onClick={() =>
+ capture("ai_gateway_launch:dialog_get_key_clicked")
+ }
+ >
+ <Button
+ variant="primary"
+ text="Get API key"
+ href={`/organization/${organizationId}/settings/ai-gateway-api-keys`}
+ />
+ </span>
+ )}
+ {state === "ask-admin" && (
+ <p role="status" className="text-muted-foreground text-sm">
+ Ask your admin to set it up.
+ </p>
+ )}
+ </div>
+ </div>
+ </PopoverLayerProvider>
+ <div
+ className="isolate"
+ data-layer="popover"
+ ref={setPopoverContainer}
+ />
+ </DialogContent>
+ </Dialog>
+ );
+}
diff --git a/web/src/features/ai-gateway/components/GatewayLaunch/GatewayReceipt.stories.tsx b/web/src/features/ai-gateway/components/GatewayLaunch/GatewayReceipt.stories.tsx
new file mode 100644
index 0000000000..b6236ea94d
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewayLaunch/GatewayReceipt.stories.tsx
@@ -0,0 +1,12 @@
+import preview from "@/.storybook/preview";
+import { GatewayReceipt } from "./GatewayReceipt";
+
+const meta = preview.meta({ component: GatewayReceipt });
+
+export const Banner = meta.story({
+ args: { variant: "banner" },
+});
+
+export const Dialog = meta.story({
+ args: { variant: "dialog" },
+});
diff --git a/web/src/features/ai-gateway/components/GatewayLaunch/GatewayReceipt.tsx b/web/src/features/ai-gateway/components/GatewayLaunch/GatewayReceipt.tsx
new file mode 100644
index 0000000000..4fc4f5f3cc
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewayLaunch/GatewayReceipt.tsx
@@ -0,0 +1,56 @@
+import { cn } from "@/src/utils/tailwind";
+
+type ReceiptRow = {
+ label: string;
+ amount: string;
+ kind: "team" | "person";
+ highlight?: boolean;
+};
+
+const fullRows: ReceiptRow[] = [
+ { label: "ENGINEERING", amount: "$48,215.40", kind: "team", highlight: true },
+ { label: "@maya · claude code", amount: "$21,402.10", kind: "person" },
+ { label: "@priya · claude code", amount: "$13,852.45", kind: "person" },
+ { label: "SUPPORT", amount: "$6,904.22", kind: "team" },
+ { label: "support-bot · haiku", amount: "$6,904.22", kind: "person" },
+];
+
+/** Illustrative spend receipt for the AI Gateway launch surfaces. */
+export function GatewayReceipt({ variant }: { variant: "banner" | "dialog" }) {
+ const rows = fullRows;
+
+ return (
+ <div
+ aria-hidden="true"
+ className={cn(
+ "bg-background text-foreground font-mono shadow-lg select-none",
+ "text-2xs -rotate-2 px-4 pt-4 pb-5",
+ )}
+ >
+ {variant !== "banner" && (
+ <div className="text-muted-foreground border-border mb-2 flex justify-between border-b border-dashed pb-2 tracking-widest">
+ <span>AI GATEWAY</span>
+ {variant === "dialog" && <span>OCT 2026</span>}
+ </div>
+ )}
+ <div className="flex flex-col gap-1">
+ {rows.map((row) => (
+ <div
+ key={row.label}
+ className={cn(
+ "flex justify-between gap-3",
+ row.kind === "team"
+ ? "font-bold tracking-wide"
+ : "text-muted-foreground pl-3",
+ row.kind === "team" && row !== rows[0] && "mt-2",
+ row.highlight && "bg-light-blue -mx-1 px-1",
+ )}
+ >
+ <span className="whitespace-nowrap">{row.label}</span>
+ <span>{row.amount}</span>
+ </div>
+ ))}
+ </div>
+ </div>
+ );
+}
diff --git a/web/src/features/ai-gateway/components/GatewayLaunch/gatewayLaunch.module.css b/web/src/features/ai-gateway/components/GatewayLaunch/gatewayLaunch.module.css
new file mode 100644
index 0000000000..fccf51a39b
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewayLaunch/gatewayLaunch.module.css
@@ -0,0 +1,12 @@
+.dotGrid {
+ background-image: radial-gradient(
+ circle at 1px 1px,
+ hsl(var(--foreground) / 0.1) 1px,
+ transparent 0
+ );
+ background-size: 20px 20px;
+}
+
+.bannerDots {
+ background-position: 8px 6px;
+}
diff --git a/web/src/features/ai-gateway/hooks/useGatewayKeyReminder.ts b/web/src/features/ai-gateway/hooks/useGatewayKeyReminder.ts
new file mode 100644
index 0000000000..5043fd5e12
--- /dev/null
+++ b/web/src/features/ai-gateway/hooks/useGatewayKeyReminder.ts
@@ -0,0 +1,22 @@
+import { useGatewaySettingsAccess } from "@/src/features/ai-gateway/hooks/useGatewaySettingsAccess";
+import { api } from "@/src/utils/api";
+
+/** Members of an org with a set-up gateway who have no key yet. */
+export function useGatewayKeyReminder(organizationId: string | undefined) {
+ const { showManagement, showApiKeys, isIngestionConfigured } =
+ useGatewaySettingsAccess(organizationId);
+ const isMember = showApiKeys && !showManagement;
+ const ownKeys = api.aiGateway.listApiKeys.useQuery(
+ { orgId: organizationId ?? "", page: 0, limit: 1 },
+ {
+ enabled:
+ organizationId !== undefined &&
+ isMember &&
+ isIngestionConfigured === true,
+ },
+ );
+
+ return (
+ isMember && isIngestionConfigured === true && ownKeys.data?.totalCount === 0
+ );
+}
diff --git a/web/src/features/ai-gateway/hooks/useGatewayLaunchEligibility.ts b/web/src/features/ai-gateway/hooks/useGatewayLaunchEligibility.ts
new file mode 100644
index 0000000000..fa8eb6a08c
--- /dev/null
+++ b/web/src/features/ai-gateway/hooks/useGatewayLaunchEligibility.ts
@@ -0,0 +1,74 @@
+import { api } from "@/src/utils/api";
+
+export type GatewayLaunchState = "setup" | "ask-admin" | "get-key";
+
+export type GatewayLaunchCandidate = {
+ organizationId: string;
+ organizationName: string;
+ canManage: boolean;
+};
+
+export type GatewayLaunchTarget = {
+ organizationId: string;
+ state: GatewayLaunchState;
+ /** Orgs the user can set up from the dialog; a picker shows when several. */
+ setupOptions: ReadonlyArray<GatewayLaunchCandidate>;
+};
+
+/**
+ * Picks the org the launch banner speaks for: an unconfigured org the user can
+ * set up, else a configured org where a member has no key yet, else an
+ * unconfigured org where they ask an admin.
+ */
+export function useGatewayLaunchTarget(
+ candidates: ReadonlyArray<GatewayLaunchCandidate>,
+): GatewayLaunchTarget | null {
+ const statuses = api.useQueries((t) =>
+ candidates.map((candidate) =>
+ t.aiGateway.getSetupStatus({ orgId: candidate.organizationId }),
+ ),
+ );
+ // Members only see their own keys, so one row answers "has a key".
+ const ownKeys = api.useQueries((t) =>
+ candidates.map((candidate, index) =>
+ t.aiGateway.listApiKeys(
+ { orgId: candidate.organizationId, page: 0, limit: 1 },
+ {
+ enabled:
+ !candidate.canManage &&
+ statuses[index]?.data?.isConfigured === true,
+ },
+ ),
+ ),
+ );
+ const unconfigured = candidates.filter(
+ (_, index) => statuses[index]?.data?.isConfigured === false,
+ );
+ const setupOptions = unconfigured.filter((candidate) => candidate.canManage);
+ if (setupOptions[0]) {
+ return {
+ organizationId: setupOptions[0].organizationId,
+ state: "setup",
+ setupOptions,
+ };
+ }
+ const keyTarget = candidates.find(
+ (candidate, index) =>
+ !candidate.canManage &&
+ statuses[index]?.data?.isConfigured === true &&
+ ownKeys[index]?.data?.totalCount === 0,
+ );
+ if (keyTarget) {
+ return {
+ organizationId: keyTarget.organizationId,
+ state: "get-key",
+ setupOptions: [],
+ };
+ }
+ if (!unconfigured[0]) return null;
+ return {
+ organizationId: unconfigured[0].organizationId,
+ state: "ask-admin",
+ setupOptions: [],
+ };
+}
diff --git a/web/src/features/organizations/OrganizationSettingsPage.tsx b/web/src/features/organizations/OrganizationSettingsPage.tsx
index 64e30387f6..1d259528b3 100644
--- a/web/src/features/organizations/OrganizationSettingsPage.tsx
+++ b/web/src/features/organizations/OrganizationSettingsPage.tsx
@@ -33,6 +33,7 @@ import {
GatewaySetupPage,
} from "@/src/features/ai-gateway";
import { useGatewaySettingsAccess } from "@/src/features/ai-gateway/hooks/useGatewaySettingsAccess";
+import { useGatewayKeyReminder } from "@/src/features/ai-gateway/hooks/useGatewayKeyReminder";
import useSessionStorage from "@/src/components/useSessionStorage";
import { api } from "@/src/utils/api";
import { ConnectedLLMApiKeySettingsTable } from "@/src/features/public-api/components/LLMApiKeySettingsTable/ConnectedLLMApiKeySettingsTable";
@@ -46,6 +47,7 @@ type OrganizationSettingsPage = {
section?: string;
show?: boolean | (() => boolean);
disabledReason?: string;
+ indicator?: boolean;
cmdKKeywords?: string[];
} & ({ content: React.ReactNode } | { href: string });
@@ -64,6 +66,7 @@ export function useOrganizationSettingsPages(): OrganizationSettingsPage[] {
scope: "organization:update",
});
const gatewayAccess = useGatewaySettingsAccess(organization?.id);
+ const gatewayKeyReminder = useGatewayKeyReminder(organization?.id);
const canReadOrganizationLlmConnections = useHasOrganizationAccess({
organizationId: organization?.id,
scope: "organizationLlmApiKeys:read",
@@ -95,6 +98,7 @@ export function useOrganizationSettingsPages(): OrganizationSettingsPage[] {
showAiGatewayNotDeployedNotice: gatewayAccess.showNotDeployedNotice,
showAiGatewayModels: gatewayAccess.showModels,
showAiGatewayApiKeys: gatewayAccess.showApiKeys,
+ gatewayKeyReminder,
/** Only managers get disabled entries; others see a notice on the page. */
gatewaySetupDisabledReason:
gatewayAccess.showManagement &&
@@ -119,6 +123,7 @@ const getOrganizationSettingsPages = ({
showAiGatewayNotDeployedNotice,
showAiGatewayModels,
showAiGatewayApiKeys,
+ gatewayKeyReminder,
gatewaySetupDisabledReason,
showOrganizationLlmConnections,
showFeaturePreviews,
@@ -144,6 +149,7 @@ const getOrganizationSettingsPages = ({
showAiGatewayNotDeployedNotice: boolean;
showAiGatewayModels: boolean;
showAiGatewayApiKeys: boolean;
+ gatewayKeyReminder: boolean;
gatewaySetupDisabledReason: string | undefined;
showOrganizationLlmConnections: boolean;
showFeaturePreviews: boolean;
@@ -364,6 +370,7 @@ const getOrganizationSettingsPages = ({
cmdKKeywords: ["gateway", "api", "keys", "metadata", "credentials"],
content: <GatewayApiKeysPage organizationId={organization.id} />,
show: showAiGatewayApiKeys,
+ indicator: gatewayKeyReminder,
disabledReason: gatewaySetupDisabledReason,
},
{
diff --git a/web/src/features/organizations/components/OrganizationProjectOverview.tsx b/web/src/features/organizations/components/OrganizationProjectOverview.tsx
index 41ee8b214a..57200b9bef 100644
--- a/web/src/features/organizations/components/OrganizationProjectOverview.tsx
+++ b/web/src/features/organizations/components/OrganizationProjectOverview.tsx
@@ -6,6 +6,7 @@ import {
Settings,
Users,
PlusIcon,
+ Waypoints,
} from "@langfuse/icons";
import {
Card,
@@ -21,9 +22,12 @@ import { Button } from "@/src/components/ui/button";
import Link from "next/link";
import { StringParam, useQueryParams } from "use-query-params";
import { Input } from "@/src/components/ui/input";
-import { useHasOrganizationAccess } from "@/src/features/rbac";
+import {
+ hasOrganizationAccess,
+ useHasOrganizationAccess,
+} from "@/src/features/rbac";
import { env } from "@/src/env.mjs";
-import { Fragment } from "react";
+import { Fragment, type ReactNode } from "react";
import { useRouter } from "next/router";
import { useSession } from "next-auth/react";
import {
@@ -46,6 +50,23 @@ import { useV4UpgradeUiEnabled } from "@/src/features/v4-migration/useV4UpgradeU
import { useAccountV4MigrationData } from "@/src/features/v4-migration/hooks/useV4MigrationData";
import { getProjectMigrationReadiness } from "@/src/features/v4-migration/migrationData";
import { ErrorPage } from "@/src/components/error-page";
+import { GatewayLaunchBanner } from "@/src/features/ai-gateway/components/GatewayLaunch/GatewayLaunchBanner";
+import { useGatewayKeyReminder } from "@/src/features/ai-gateway/hooks/useGatewayKeyReminder";
+import { useGatewayLaunchTarget } from "@/src/features/ai-gateway/hooks/useGatewayLaunchEligibility";
+import { useGatewaySettingsAccess } from "@/src/features/ai-gateway/hooks/useGatewaySettingsAccess";
+import { getContextualFeatureFlags } from "@/src/features/feature-flags/utils";
+
+const lastTraceLabel = (lastTraceAt: Date | string | null | undefined) =>
+ lastTraceAt
+ ? `Last trace ${formatCompactRelativeTime(new Date(lastTraceAt))}`
+ : "No traces in the last 30d";
+
+/** Marks the project that receives the org's AI Gateway traces. */
+const GatewayProjectMark = () => (
+ <span className="flex shrink-0" title="Receives AI Gateway traces">
+ <Waypoints size="base" color="default" aria-label="AI Gateway project" />
+ </span>
+);
const OrganizationProjectTiles = ({
org,
@@ -55,6 +76,17 @@ const OrganizationProjectTiles = ({
search?: string;
}) => {
const v4UpgradeUiEnabled = useV4UpgradeUiEnabled();
+ const gatewayAccess = useGatewaySettingsAccess(org.id);
+ // Gateway managers see which project receives the gateway's traces.
+ const markGatewayProject =
+ gatewayAccess.showManagement &&
+ gatewayAccess.isIngestionConfigured === true;
+ const gatewayConfigQuery = api.aiGateway.getConfig.useQuery(
+ { orgId: org.id },
+ { enabled: markGatewayProject },
+ );
+ const gatewayProjectId =
+ gatewayConfigQuery.data?.config?.defaultIngestionProjectId;
const lastTraceQuery = api.organizations.lastTraceByProject.useQuery(
{ orgId: org.id },
{ enabled: v4UpgradeUiEnabled },
@@ -97,12 +129,17 @@ const OrganizationProjectTiles = ({
)}
<CardHeader>
<div className="flex items-start justify-between gap-2">
- <CardTitle
- className="truncate text-base"
- title={project.name}
- >
- {project.name}
- </CardTitle>
+ <div className="flex min-w-0 items-center gap-2">
+ {markGatewayProject && project.id === gatewayProjectId && (
+ <GatewayProjectMark />
+ )}
+ <CardTitle
+ className="truncate text-base"
+ title={project.name}
+ >
+ {project.name}
+ </CardTitle>
+ </div>
{!project.deletedAt &&
(migrationReadiness === "action-needed" ||
migrationReadiness === "partner-managed") && (
@@ -117,14 +154,11 @@ const OrganizationProjectTiles = ({
<CardContent className="min-h-7 pb-3">
<p className="text-muted-foreground text-xs">
{lastTraceQuery.isSuccess
- ? (() => {
- const lastTraceAt = lastTraceQuery.data?.find(
+ ? lastTraceLabel(
+ lastTraceQuery.data?.find(
(t) => t.projectId === project.id,
- )?.lastTraceAt;
- return lastTraceAt
- ? `Last trace ${formatCompactRelativeTime(new Date(lastTraceAt))}`
- : "No traces in the last 30d";
- })()
+ )?.lastTraceAt,
+ )
: null}
</p>
</CardContent>
@@ -138,9 +172,17 @@ const OrganizationProjectTiles = ({
) : (
<Card key={project.id}>
<CardHeader>
- <CardTitle className="truncate text-base" title={project.name}>
- {project.name}
- </CardTitle>
+ <div className="flex min-w-0 items-center gap-2">
+ {markGatewayProject && project.id === gatewayProjectId && (
+ <GatewayProjectMark />
+ )}
+ <CardTitle
+ className="truncate text-base"
+ title={project.name}
+ >
+ {project.name}
+ </CardTitle>
+ </div>
</CardHeader>
{!project.deletedAt ? (
<CardFooter className="gap-2">
@@ -210,12 +252,26 @@ const OrganizationActionButtons = ({
organizationId: orgId,
scope: "projects:create",
});
+ const gatewayKeyReminder = useGatewayKeyReminder(orgId);
return (
<>
- <Button asChild variant="ghost">
- <Link href={`/organization/${orgId}/settings`}>
+ <Button asChild variant="ghost" className="relative">
+ <Link
+ href={`/organization/${orgId}/settings`}
+ aria-label={
+ gatewayKeyReminder
+ ? "Organization settings: get your AI Gateway API key"
+ : "Organization settings"
+ }
+ >
<Settings size="base" color="default" />
+ {gatewayKeyReminder && (
+ <span
+ aria-hidden="true"
+ className="absolute top-1.5 right-1.5 size-1.75 rounded-full bg-orange-400"
+ />
+ )}
</Link>
</Button>
{membersViewAccess && (
@@ -333,6 +389,30 @@ export const OrganizationProjectOverview = () => {
const organizations = session.data?.user?.organizations;
const [{ search }, setQueryParams] = useQueryParams({ search: StringParam });
const v4MigrationBannerState = useV4MigrationBannerState(v4UpgradeUiEnabled);
+ const gatewayLaunchCandidates = (organizations ?? [])
+ .filter(
+ (org) =>
+ org.id !== env.NEXT_PUBLIC_DEMO_ORG_ID &&
+ getContextualFeatureFlags(session.data?.user, {
+ organizationId: org.id,
+ })?.aiGateway === true &&
+ hasOrganizationAccess({
+ session: session.data,
+ organizationId: org.id,
+ scope: "gateway:invoke",
+ }),
+ )
+ .map((org) => ({
+ organizationId: org.id,
+ organizationName: org.name,
+ canManage: hasOrganizationAccess({
+ session: session.data,
+ organizationId: org.id,
+ scope: "gateway:manage",
+ }),
+ }));
+ const gatewayLaunchTarget = useGatewayLaunchTarget(gatewayLaunchCandidates);
+ const userId = session.data?.user?.id;
if (organizations === undefined) {
return "loading...";
@@ -380,7 +460,11 @@ export const OrganizationProjectOverview = () => {
onChange={(e) => setQueryParams({ search: e.target.value })}
/>
{canCreateOrg && (
- <Button data-testid="create-organization-btn" asChild>
+ <Button
+ data-testid="create-organization-btn"
+ variant="secondary"
+ asChild
+ >
<Link href={createOrganizationRoute}>
<PlusIcon
size="base"
@@ -396,18 +480,14 @@ export const OrganizationProjectOverview = () => {
),
}}
>
- {v4UpgradeUiEnabled ? (
- v4MigrationBannerState.projectsNeedingMigration > 0 && (
- <V4MigrationBanner
- projectsNeedingMigration={
- v4MigrationBannerState.projectsNeedingMigration
- }
- totalProjects={v4MigrationBannerState.totalProjects}
- />
- )
- ) : (
- <AgentToolsBanner />
- )}
+ {pageBanner({
+ v4UpgradeUiEnabled,
+ v4MigrationBannerState,
+ gatewayBanner:
+ gatewayLaunchTarget && userId ? (
+ <GatewayLaunchBanner target={gatewayLaunchTarget} userId={userId} />
+ ) : null,
+ })}
{showOnboarding && <Onboarding />}
{organizations
.map((org) => {
@@ -436,6 +516,33 @@ export const OrganizationProjectOverview = () => {
);
};
+/** One banner at a time: v4 migration work first, then the gateway launch. */
+const pageBanner = ({
+ v4UpgradeUiEnabled,
+ v4MigrationBannerState,
+ gatewayBanner,
+}: {
+ v4UpgradeUiEnabled: boolean;
+ v4MigrationBannerState: ReturnType<typeof useV4MigrationBannerState>;
+ gatewayBanner: ReactNode;
+}): ReactNode => {
+ if (
+ v4UpgradeUiEnabled &&
+ v4MigrationBannerState.projectsNeedingMigration > 0
+ ) {
+ return (
+ <V4MigrationBanner
+ projectsNeedingMigration={
+ v4MigrationBannerState.projectsNeedingMigration
+ }
+ totalProjects={v4MigrationBannerState.totalProjects}
+ />
+ );
+ }
+ if (gatewayBanner) return gatewayBanner;
+ return v4UpgradeUiEnabled ? null : <AgentToolsBanner />;
+};
+
const Onboarding = () => {
const session = useSession();
const canCreateOrgs = session.data?.user?.canCreateOrganizations;
diff --git a/web/src/features/posthog-analytics/usePostHogClientCapture.ts b/web/src/features/posthog-analytics/usePostHogClientCapture.ts
index 862e3cca5d..d8543548d7 100644
--- a/web/src/features/posthog-analytics/usePostHogClientCapture.ts
+++ b/web/src/features/posthog-analytics/usePostHogClientCapture.ts
@@ -484,6 +484,15 @@ const events = {
],
cmd_k_menu: ["opened", "search_entered", "navigated"],
spend_alert: ["created", "updated", "deleted"],
+ // Launch surfaces answer "which entry point and state lead people into
+ // gateway setup or key creation?" Props are state enums and counts only.
+ ai_gateway_launch: [
+ "banner_cta_clicked",
+ "banner_dismissed",
+ "dialog_setup_clicked",
+ "dialog_get_key_clicked",
+ "dialog_learn_more_clicked",
+ ],
sidebar: [
"book_a_call_clicked",
"v4_beta_toggled",
diff --git a/web/src/features/settings/SettingsPage.tsx b/web/src/features/settings/SettingsPage.tsx
index cca5c289e0..58ac8e832b 100644
--- a/web/src/features/settings/SettingsPage.tsx
+++ b/web/src/features/settings/SettingsPage.tsx
@@ -3,6 +3,7 @@ import { useRouter } from "next/router";
import { useSession } from "next-auth/react";
import { PagedSettingsContainer } from "@/src/components/PagedSettingsContainer";
import ContainerPage from "@/src/components/layouts/ContainerPage";
+import { Badge } from "@/src/components/design-system/Badge/Badge";
import { NoDataOrLoading } from "@/src/components/NoDataOrLoading";
import { OrganizationDropdownMenu } from "@/src/components/OrganizationDropdownMenu/OrganizationDropdownMenu";
import { DropdownIndicator } from "@/src/components/design-system/DropdownIndicator/DropdownIndicator";
@@ -62,6 +63,11 @@ export function SettingsPage({ scope }: SettingsPageProps) {
sectionHeaders={{
[ORGANIZATION_SECTION]: <OrganizationSectionHeader />,
}}
+ sectionBadges={{
+ "AI Gateway": (
+ <Badge text="Beta" color="blue" size="sm" font="mono" />
+ ),
+ }}
/>
</ContainerPage>
);