Skip to content

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

feat(ai-gateway): show per-tool setup instructions after creating a gateway key (#19186)

Tobias Wochinger4d851c2ee759
diff --git a/web/src/__tests__/server/ai-gateway-control-plane.servertest.ts b/web/src/__tests__/server/ai-gateway-control-plane.servertest.ts
index 91524d122e..4710e1ed89 100644
--- a/web/src/__tests__/server/ai-gateway-control-plane.servertest.ts
+++ b/web/src/__tests__/server/ai-gateway-control-plane.servertest.ts
@@ -340,6 +340,29 @@ describe("AI gateway control plane", () => {
).resolves.toEqual({ isConfigured: false });
});
+ it("gives key owners the gateway URL and enabled providers without connection details", async () => {
+ const owner = await prepare();
+ const member = await createCallerForOrganizationRole(owner, Role.MEMBER);
+ const viewer = await createCallerForOrganizationRole(owner, Role.VIEWER);
+ await owner.caller.aiGateway.createConnection({
+ orgId: owner.org.id,
+ name: "OpenAI-primary",
+ provider: "OPENAI",
+ credential: "sk-test-client-setup",
+ });
+
+ const setup = await member.aiGateway.getClientSetup({
+ orgId: owner.org.id,
+ });
+ expect(setup).toEqual({
+ gatewayBaseUrl: expect.any(String),
+ providers: ["OPENAI"],
+ });
+ await expect(
+ viewer.aiGateway.getClientSetup({ orgId: owner.org.id }),
+ ).rejects.toMatchObject({ code: "FORBIDDEN" });
+ });
+
it("redirects gateway managers to Configuration until ingestion is set up", async () => {
const owner = await prepare();
const memberSession = {
diff --git a/web/src/components/design-system/Button/Button.tsx b/web/src/components/design-system/Button/Button.tsx
index d6df7c329e..2af095f03b 100644
--- a/web/src/components/design-system/Button/Button.tsx
+++ b/web/src/components/design-system/Button/Button.tsx
@@ -98,7 +98,13 @@ export function Button(props: ButtonProps) {
>
{Icon ? <Icon color={iconColor} aria-hidden /> : null}
{props.text}
- <ExternalLink size="sm" color={iconColor} aria-hidden />
+ {/* The glyph reaches the bottom of its box, so centered it dips below the text baseline. */}
+ <ExternalLink
+ size="sm"
+ color={iconColor}
+ aria-hidden
+ __rawClassName="-translate-y-px"
+ />
</a>
);
}
diff --git a/web/src/components/design-system/Dialog/Dialog.stories.tsx b/web/src/components/design-system/Dialog/Dialog.stories.tsx
index aaeb7a31e2..eb5b114fad 100644
--- a/web/src/components/design-system/Dialog/Dialog.stories.tsx
+++ b/web/src/components/design-system/Dialog/Dialog.stories.tsx
@@ -12,6 +12,7 @@ type Size = NonNullable<React.ComponentProps<typeof Dialog>["size"]>;
const allSizes = Object.keys({
sm: true,
default: true,
+ md: true,
lg: true,
xxl: true,
} satisfies Record<Size, true>) as Size[];
@@ -93,6 +94,26 @@ export const Autofocus = meta.story({
},
});
+export const CloseOnly = meta.story({
+ render: () => (
+ <DialogController
+ renderDialog={() => (
+ <Dialog
+ title="Import finished"
+ text="All prompts were imported."
+ closeLabel="Done"
+ />
+ )}
+ >
+ {({ openDialog }) => (
+ <button type="button" onClick={() => openDialog()}>
+ Open dialog
+ </button>
+ )}
+ </DialogController>
+ ),
+});
+
export const DestructiveAutofocus = meta.story({
name: "(Test) Destructive autofocus",
render: () => (
diff --git a/web/src/components/design-system/Dialog/Dialog.tsx b/web/src/components/design-system/Dialog/Dialog.tsx
index b79d08c02d..aa52c2282a 100644
--- a/web/src/components/design-system/Dialog/Dialog.tsx
+++ b/web/src/components/design-system/Dialog/Dialog.tsx
@@ -20,6 +20,7 @@ const dialogContentVariants = cva(
size: {
sm: "sm:max-w-md",
default: "sm:max-w-lg",
+ md: "sm:max-w-2xl",
lg: "sm:max-w-4xl",
xxl: "sm:h-[90vh] sm:max-w-[95vw]",
},
@@ -42,7 +43,8 @@ type DialogAction = {
};
type DialogProps = {
- actions?: ReadonlyArray<DialogAction>;
+ /** Defaults to "Cancel". Without `actions`, the close button is the only, primary button. */
+ closeLabel?: string;
closeOnInteractionOutside?: boolean;
/** Disable when a child interaction handles activation keys on the document. */
stopPropagationOnEnterSpace?: boolean;
@@ -51,11 +53,15 @@ type DialogProps = {
} & (
| { children?: React.ReactNode; text?: never }
| { children?: never; text: string }
-);
+) & {
+ /** Decision footer: the close button is added before these actions. */
+ actions?: ReadonlyArray<DialogAction>;
+ };
function DialogRoot({
actions,
children,
+ closeLabel,
closeOnInteractionOutside = false,
stopPropagationOnEnterSpace = true,
size,
@@ -65,7 +71,19 @@ function DialogRoot({
const container = useLayerContainer("modal");
const [popoverContainer, setPopoverContainer] =
React.useState<HTMLDivElement | null>(null);
- const cancelButtonRef = React.useRef<HTMLButtonElement>(null);
+ const closeButtonRef = React.useRef<HTMLButtonElement | null>(null);
+ // Radix auto-focuses only on open; a dialog that swaps to a close-only
+ // footer while open (e.g. after a submit) would otherwise drop focus to the
+ // document body.
+ const attachCloseOnlyButton = React.useCallback(
+ (button: HTMLButtonElement | null) => {
+ closeButtonRef.current = button;
+ button?.focus();
+ },
+ [],
+ );
+ const hasActions = Boolean(actions?.length);
+ const isCloseOnly = !hasActions && closeLabel !== undefined;
const actionButtonRefs = React.useRef<Array<HTMLButtonElement | null>>([]);
return (
@@ -84,6 +102,12 @@ function DialogRoot({
// Radix otherwise focuses Cancel because it is the first tabbable.
// Prefer the rightmost safe action, falling back to Cancel rather
// than immediately triggering a destructive action.
+ if (isCloseOnly) {
+ event.preventDefault();
+ closeButtonRef.current?.focus();
+ return;
+ }
+
if (text === undefined) return;
let safeActionButton: HTMLButtonElement | null = null;
@@ -106,7 +130,7 @@ function DialogRoot({
return;
}
- cancelButtonRef.current?.focus();
+ closeButtonRef.current?.focus();
}}
onClick={(event) => event.stopPropagation()}
onKeyDown={(event) => {
@@ -142,16 +166,24 @@ function DialogRoot({
<PopoverLayerProvider container={popoverContainer}>
{text !== undefined ? <DialogBody>{text}</DialogBody> : children}
</PopoverLayerProvider>
- {actions?.length ? (
+ {hasActions || isCloseOnly ? (
<DialogFooter>
<DialogPrimitive.Close asChild>
- <Button
- ref={cancelButtonRef}
- variant="secondary"
- text="Cancel"
- />
+ {isCloseOnly ? (
+ <Button
+ ref={attachCloseOnlyButton}
+ variant="primary"
+ text={closeLabel}
+ />
+ ) : (
+ <Button
+ ref={closeButtonRef}
+ variant="secondary"
+ text={closeLabel ?? "Cancel"}
+ />
+ )}
</DialogPrimitive.Close>
- {actions.map(
+ {actions?.map(
({ icon: Icon, label, variant, ...buttonProps }, index) => (
<Button
key={label}
diff --git a/web/src/components/design-system/ExpandableContentPeek/ExpandableContentPeek.stories.tsx b/web/src/components/design-system/ExpandableContentPeek/ExpandableContentPeek.stories.tsx
new file mode 100644
index 0000000000..75fca465dc
--- /dev/null
+++ b/web/src/components/design-system/ExpandableContentPeek/ExpandableContentPeek.stories.tsx
@@ -0,0 +1,25 @@
+import preview from "@/.storybook/preview";
+import { ExpandableContentPeek } from "./ExpandableContentPeek";
+
+const meta = preview.meta({ component: ExpandableContentPeek });
+
+const paragraphs = Array.from({ length: 8 }, (_, index) => (
+ <p key={index} className="text-sm">
+ Step {index + 1}: configure the client, then verify the connection before
+ moving on to the next step.
+ </p>
+));
+
+export const Overflowing = meta.story({
+ args: {
+ expandLabel: "Show all steps",
+ children: <div className="flex max-w-md flex-col gap-3">{paragraphs}</div>,
+ },
+});
+
+export const FitsWithoutPeek = meta.story({
+ args: {
+ expandLabel: "Show all steps",
+ children: <p className="max-w-md text-sm">Short content renders as is.</p>,
+ },
+});
diff --git a/web/src/components/design-system/ExpandableContentPeek/ExpandableContentPeek.tsx b/web/src/components/design-system/ExpandableContentPeek/ExpandableContentPeek.tsx
new file mode 100644
index 0000000000..9cc3a0bf91
--- /dev/null
+++ b/web/src/components/design-system/ExpandableContentPeek/ExpandableContentPeek.tsx
@@ -0,0 +1,105 @@
+"use client";
+
+import { cva } from "class-variance-authority";
+import { ChevronDown } from "@langfuse/icons";
+import {
+ useLayoutEffect,
+ useRef,
+ useState,
+ type PropsWithChildren,
+ type RefObject,
+} from "react";
+
+import { Button } from "@/src/components/design-system/Button/Button";
+import { cn } from "@/src/utils/tailwind";
+
+const peekVariants = cva("", {
+ variants: {
+ collapsedHeight: {
+ sm: "max-h-32",
+ md: "max-h-48",
+ lg: "max-h-64",
+ },
+ },
+});
+
+type ExpandableContentPeekProps = PropsWithChildren<{
+ /** Label of the button that reveals the rest, e.g. "Show all steps". */
+ expandLabel: string;
+ collapsedHeight?: "sm" | "md" | "lg";
+}>;
+
+function useIsOverflowing(
+ containerRef: RefObject<HTMLDivElement | null>,
+ contentRef: RefObject<HTMLDivElement | null>,
+ isEnabled: boolean,
+) {
+ const [isOverflowing, setIsOverflowing] = useState(false);
+
+ // Measured before paint so clamped content never flashes without its fade.
+ useLayoutEffect(() => {
+ const container = containerRef.current;
+ const content = contentRef.current;
+ if (!isEnabled || !container || !content) return;
+
+ const measure = () =>
+ setIsOverflowing(content.offsetHeight > container.clientHeight);
+ measure();
+
+ if (typeof ResizeObserver === "undefined") return;
+ const resizeObserver = new ResizeObserver(measure);
+ resizeObserver.observe(container);
+ resizeObserver.observe(content);
+ return () => resizeObserver.disconnect();
+ }, [containerRef, contentRef, isEnabled]);
+
+ return isOverflowing;
+}
+
+/**
+ * Shows the top of its content and fades the rest out behind an expand button.
+ * Expanding is one-way; remount (e.g. with a `key`) to collapse again. Content
+ * that already fits renders without fade or button.
+ */
+export function ExpandableContentPeek({
+ children,
+ expandLabel,
+ collapsedHeight = "md",
+}: ExpandableContentPeekProps) {
+ const [isExpanded, setIsExpanded] = useState(false);
+ const containerRef = useRef<HTMLDivElement>(null);
+ const contentRef = useRef<HTMLDivElement>(null);
+ const isOverflowing = useIsOverflowing(containerRef, contentRef, !isExpanded);
+ const isClamped = !isExpanded && isOverflowing;
+
+ const expand = () => setIsExpanded(true);
+
+ return (
+ <div className="relative">
+ <div
+ ref={containerRef}
+ className={cn(
+ !isExpanded && ["overflow-hidden", peekVariants({ collapsedHeight })],
+ isClamped &&
+ "[mask-image:linear-gradient(to_bottom,black_40%,transparent)]",
+ )}
+ // Keyboard users tabbing into the hidden part get the full content.
+ onFocus={isClamped ? expand : undefined}
+ >
+ <div ref={contentRef}>{children}</div>
+ </div>
+ {isClamped ? (
+ <div className="absolute inset-x-0 bottom-0 flex justify-center">
+ <Button
+ variant="ghost"
+ size="sm"
+ icon={ChevronDown}
+ text={expandLabel}
+ aria-expanded={false}
+ onClick={expand}
+ />
+ </div>
+ ) : null}
+ </div>
+ );
+}
diff --git a/web/src/features/evals/v2/components/Stepper/Stepper.stories.tsx b/web/src/components/design-system/Stepper/Stepper.stories.tsx
similarity index 58%
rename from web/src/features/evals/v2/components/Stepper/Stepper.stories.tsx
rename to web/src/components/design-system/Stepper/Stepper.stories.tsx
index 70aac6230b..92ef1d5d5f 100644
--- a/web/src/features/evals/v2/components/Stepper/Stepper.stories.tsx
+++ b/web/src/components/design-system/Stepper/Stepper.stories.tsx
@@ -1,6 +1,6 @@
import { fn } from "storybook/test";
-import preview from "../../../../../../.storybook/preview";
+import preview from "@/.storybook/preview";
import { Stepper } from "./Stepper";
const meta = preview.meta({ component: Stepper });
@@ -26,6 +26,36 @@ export const Collapsed = meta.story({
},
});
+export const OutlineStatic = meta.story({
+ render: () => (
+ <div className="flex max-w-xl flex-col">
+ <Stepper
+ number={1}
+ title="Log out of any existing session"
+ description="An existing login sends conflicting credentials."
+ variant="outline"
+ size="sm"
+ isCollapsible={false}
+ compactBottomSpacing
+ >
+ <div className="rounded-md border p-3 font-mono text-xs">
+ claude /logout
+ </div>
+ </Stepper>
+ <Stepper
+ number={2}
+ title="Start the agent"
+ variant="outline"
+ size="sm"
+ isCollapsible={false}
+ compactBottomSpacing
+ >
+ <div className="rounded-md border p-3 font-mono text-xs">claude</div>
+ </Stepper>
+ </div>
+ ),
+});
+
export const MultiStep = meta.story({
render: () => (
<div className="flex max-w-xl flex-col">
diff --git a/web/src/components/design-system/Stepper/Stepper.tsx b/web/src/components/design-system/Stepper/Stepper.tsx
new file mode 100644
index 0000000000..ba3b330bdb
--- /dev/null
+++ b/web/src/components/design-system/Stepper/Stepper.tsx
@@ -0,0 +1,156 @@
+import { useState, type ReactNode } from "react";
+import { cva } from "class-variance-authority";
+import { ChevronDown } from "@langfuse/icons";
+
+import { cn } from "@/src/utils/tailwind";
+
+const markerVariants = cva(
+ "flex shrink-0 items-center justify-center rounded-full",
+ {
+ variants: {
+ variant: {
+ filled: "bg-primary text-primary-foreground",
+ outline:
+ "bg-background text-foreground border-border-contrast border font-bold",
+ },
+ size: {
+ default: "size-7 text-sm",
+ sm: "size-5 text-xs",
+ },
+ },
+ },
+);
+
+const headerVariants = cva("flex items-center gap-1.5 text-left", {
+ variants: {
+ size: {
+ default: "min-h-7",
+ sm: "min-h-5",
+ },
+ },
+});
+
+const titleVariants = cva("font-bold", {
+ variants: {
+ size: {
+ default: "text-lg",
+ sm: "text-sm",
+ },
+ },
+});
+
+const descriptionVariants = cva("text-muted-foreground", {
+ variants: {
+ size: {
+ default: "text-sm",
+ sm: "text-xs",
+ },
+ },
+});
+
+type StepperProps = {
+ number: number;
+ title: string;
+ description?: ReactNode;
+ variant?: "filled" | "outline";
+ size?: "default" | "sm";
+ compactBottomSpacing?: boolean;
+ children: ReactNode;
+} & (
+ | {
+ /** Toggles the body from the step header; on by default. */
+ isCollapsible?: true;
+ defaultOpen?: boolean;
+ open?: boolean;
+ onOpenChange?: (open: boolean) => void;
+ }
+ | {
+ isCollapsible: false;
+ defaultOpen?: never;
+ open?: never;
+ onOpenChange?: never;
+ }
+);
+
+/**
+ * Datadog-style vertical stepper section: a numbered circle with a connector
+ * line down to the next step. Collapsible steps toggle their body from the
+ * header and support controlled expansion for progressive flows. Render steps
+ * as siblings — the last one drops its connector and trailing space via
+ * `:last-child`, so adding or reordering steps needs no bookkeeping.
+ */
+export function Stepper({
+ number,
+ title,
+ description,
+ variant = "filled",
+ size = "default",
+ compactBottomSpacing = false,
+ isCollapsible = true,
+ defaultOpen = true,
+ open,
+ onOpenChange,
+ children,
+}: StepperProps) {
+ const [internalOpen, setInternalOpen] = useState(defaultOpen);
+ const expanded = !isCollapsible || (open ?? internalOpen);
+
+ const toggle = () => {
+ const nextOpen = !expanded;
+ if (open === undefined) setInternalOpen(nextOpen);
+ onOpenChange?.(nextOpen);
+ };
+
+ return (
+ <div className="group/step flex gap-1.5">
+ <div className="flex flex-col items-center">
+ <div className={markerVariants({ variant, size })}>{number}</div>
+ <div className="bg-border my-1 w-px flex-1 group-last/step:hidden" />
+ </div>
+
+ <div
+ className={cn(
+ "flex min-w-0 flex-1 flex-col group-last/step:pb-0",
+ compactBottomSpacing ? "pb-3" : "pb-8",
+ )}
+ >
+ {isCollapsible ? (
+ <button
+ type="button"
+ className={headerVariants({ size })}
+ aria-label={`Step ${number}: ${title}`}
+ aria-expanded={expanded}
+ onClick={toggle}
+ >
+ <ChevronDown
+ size="base"
+ color="tertiary"
+ __rawClassName={cn(
+ "translate-y-px transition-transform",
+ !expanded && "-rotate-90",
+ )}
+ />
+ <span className={titleVariants({ size })}>{title}</span>
+ </button>
+ ) : (
+ <div className={headerVariants({ size })}>
+ <span className={titleVariants({ size })}>{title}</span>
+ </div>
+ )}
+ {expanded && (
+ <div
+ className={cn(
+ "flex flex-col",
+ isCollapsible ? "gap-4 pl-5" : "gap-2",
+ )}
+ >
+ {description ? (
+ <p className={descriptionVariants({ size })}>{description}</p>
+ ) : null}
+ {children}
+ </div>
+ )}
+ </div>
+ </div>
+ );
+}
diff --git a/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/CreateGatewayApiKeyDialogController/CreateGatewayApiKeyDialogController.tsx b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/CreateGatewayApiKeyDialogController/CreateGatewayApiKeyDialogController.tsx
index 25bd457c10..af15397d63 100644
--- a/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/CreateGatewayApiKeyDialogController/CreateGatewayApiKeyDialogController.tsx
+++ b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/CreateGatewayApiKeyDialogController/CreateGatewayApiKeyDialogController.tsx
@@ -1,8 +1,9 @@
-/* eslint-disable @typescript-eslint/no-deprecated -- Legacy UI usage retained during migration to design-system components. */
import { useState, type ReactNode } from "react";
import { ChevronRight, Plus, X } from "@langfuse/icons";
import { Alert } from "@/src/components/design-system/Alert/Alert";
+import { Dialog } from "@/src/components/design-system/Dialog/Dialog";
+import { DialogController } from "@/src/components/design-system/DialogController/DialogController";
import { Tabs } from "@/src/components/design-system/Tabs/Tabs";
import { Button } from "@/src/components/ui/button";
import {
@@ -10,13 +11,6 @@ import {
CollapsibleContent,
CollapsibleTrigger,
} from "@/src/components/ui/collapsible";
-import {
- DialogBody,
- DialogController,
- DialogFooter,
- DialogHeader,
- DialogTitle,
-} from "@/src/components/ui/dialog";
import { InfoTooltip } from "@/src/components/ui/InfoTooltip/InfoTooltip";
import { Input } from "@/src/components/ui/input";
import { Label } from "@/src/components/ui/label";
@@ -25,7 +19,7 @@ import {
type ApiKeyExpirationPreset,
resolveApiKeyExpiration,
} from "@/src/features/apiKey";
-import { GeneratedKeyContent } from "@/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent";
+import { GeneratedKeyContent } from "@/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/GeneratedKeyContent";
import { useHasOrganizationAccess } from "@/src/features/rbac";
import {
api,
@@ -67,10 +61,9 @@ export function CreateGatewayApiKeyDialogController({
organizationId,
scope: "gateway:manage",
});
- const [generatedKeys, setGeneratedKeys] = useState<{
- publicKey: string;
- secretKey: string;
- } | null>(null);
+ const [generatedSecretKey, setGeneratedSecretKey] = useState<string | null>(
+ null,
+ );
const utils = api.useUtils();
const create = api.aiGateway.createApiKey.useMutation({
onError: (error) =>
@@ -83,7 +76,7 @@ export function CreateGatewayApiKeyDialogController({
setCustomExpiry("");
setMetadata([{ id: 1, key: "", value: "" }]);
setIsMetadataOpen(false);
- setGeneratedKeys(null);
+ setGeneratedSecretKey(null);
setNextMetadataId(2);
setIssuedAs("user");
};
@@ -106,10 +99,7 @@ export function CreateGatewayApiKeyDialogController({
expiresAt,
issuedAs: canIssueServiceAccountKeys ? issuedAs : "user",
});
- setGeneratedKeys({
- publicKey: created.publicKey,
- secretKey: created.secretKey,
- });
+ setGeneratedSecretKey(created.secretKey);
await utils.aiGateway.listApiKeys.invalidate({
orgId: organizationId,
});
@@ -120,199 +110,198 @@ export function CreateGatewayApiKeyDialogController({
return (
<DialogController
- size="default"
- closeOnInteractionOutside={false}
onBeforeClose={() => !create.isPending}
- onDismiss={reset}
- renderContent={({ closeDialog }) => (
- <>
- <DialogHeader>
- <DialogTitle>
- {generatedKeys ? "Gateway API key created" : "Issue API key"}
- </DialogTitle>
- </DialogHeader>
- {generatedKeys ? (
- <GeneratedKeyContent generatedKeys={generatedKeys} />
- ) : (
- <>
- <DialogBody>
- <div>
- <Label
- htmlFor="gateway-key-name"
- className="flex items-center gap-1.5"
- >
- Description
- <InfoTooltip label="About gateway key descriptions">
- Shown in the key list. Use it to describe what consumes
- the key.
- </InfoTooltip>
- </Label>
- <Input
- id="gateway-key-name"
- className="mt-1.5"
- maxLength={500}
- placeholder="e.g. Checkout agent, backend service"
- value={name}
- onChange={(event) => setName(event.target.value)}
- />
- </div>
- {canIssueServiceAccountKeys ? (
- <div className="flex flex-col gap-1.5">
- <Label>Issued as</Label>
- <div>
- <Tabs
- activationMode="manual"
- value={issuedAs}
- onValueChange={(value) =>
- setIssuedAs(value as IssuedAs)
- }
- >
- <Tabs.List
- variant="inset"
- size="md"
- aria-label="Issued as"
- >
- <Tabs.Trigger value="user" label="My user" />
- <Tabs.Trigger
- value="serviceAccount"
- label="Service account"
- />
- </Tabs.List>
- </Tabs>
- </div>
- <p className="text-muted-foreground text-xs">
- {issuedAsDescriptions[issuedAs]}
- </p>
- </div>
- ) : null}
- <ApiKeyExpirationInput
- id="gateway-key-expiry"
- expiryPreset={expiryPreset}
- customExpiry={customExpiry}
- onExpiryPresetChange={setExpiryPreset}
- onCustomExpiryChange={setCustomExpiry}
- />
- <Collapsible
- open={isMetadataOpen}
- onOpenChange={setIsMetadataOpen}
+ renderDialog={() =>
+ generatedSecretKey ? (
+ <Dialog title="Gateway key created" size="md" closeLabel="Done">
+ <GeneratedKeyContent
+ organizationId={organizationId}
+ secretKey={generatedSecretKey}
+ />
+ </Dialog>
+ ) : (
+ <Dialog
+ title="Issue API key"
+ size="md"
+ actions={[
+ {
+ label: "Create key",
+ loading: create.isPending,
+ disabled: create.isPending || expiresAt === undefined,
+ onClick: submit,
+ },
+ ]}
+ >
+ <Dialog.Body>
+ <div>
+ <Label
+ htmlFor="gateway-key-name"
+ className="flex items-center gap-1.5"
>
- <div className="flex items-center gap-1.5">
- <CollapsibleTrigger asChild>
- <button
- type="button"
- className="group flex items-center gap-2 text-left text-sm"
+ Description
+ <InfoTooltip label="About gateway key descriptions">
+ Shown in the key list. Use it to describe what consumes the
+ key.
+ </InfoTooltip>
+ </Label>
+ <Input
+ id="gateway-key-name"
+ className="mt-1.5"
+ maxLength={500}
+ placeholder="e.g. Checkout agent, backend service"
+ value={name}
+ onChange={(event) => setName(event.target.value)}
+ />
+ </div>
+ {canIssueServiceAccountKeys ? (
+ <div className="flex flex-col gap-1.5">
+ <Label>Issued as</Label>
+ <div>
+ <Tabs
+ activationMode="manual"
+ value={issuedAs}
+ onValueChange={(value) => setIssuedAs(value as IssuedAs)}
+ >
+ <Tabs.List
+ variant="inset"
+ size="md"
+ aria-label="Issued as"
>
- <ChevronRight
- size="base"
- color="tertiary"
- __rawClassName="translate-y-px transition-transform group-data-[state=open]:rotate-90"
+ <Tabs.Trigger value="user" label="My user" />
+ <Tabs.Trigger
+ value="serviceAccount"
+ label="Service account"
/>
- <span>Metadata</span>
- <span className="text-muted-foreground font-normal">
- (optional)
- {metadataCount > 0 ? ` · ${metadataCount} set` : ""}
- </span>
- </button>
- </CollapsibleTrigger>
- <InfoTooltip label="About gateway key metadata">
- Attached to every trace from this key, so you can filter
- and group by it.
- </InfoTooltip>
+ </Tabs.List>
+ </Tabs>
</div>
- <CollapsibleContent className="mt-2 pl-5.5">
- <div className="flex flex-col gap-2">
- {metadata.map((field) => (
- <div
- key={field.id}
- className="ph-no-capture flex items-center gap-2"
- >
- <Input
- aria-label="Metadata key"
- placeholder="key"
- value={field.key}
- onChange={(event) =>
- setMetadata((current) =>
- current.map((item) =>
- item.id === field.id
- ? { ...item, key: event.target.value }
- : item,
- ),
- )
- }
- />
- <Input
- aria-label="Metadata value"
- placeholder="value"
- value={field.value}
- onChange={(event) =>
- setMetadata((current) =>
- current.map((item) =>
- item.id === field.id
- ? { ...item, value: event.target.value }
- : item,
- ),
- )
- }
- />
- <Button
- size="icon-xs"
- variant="ghost"
- aria-label="Remove metadata field"
- onClick={() =>
- setMetadata((current) =>
- current.filter((item) => item.id !== field.id),
- )
- }
- >
- <X size="sm" color="default" />
- </Button>
- </div>
- ))}
- </div>
+ <p className="text-muted-foreground text-xs">
+ {issuedAsDescriptions[issuedAs]}
+ </p>
+ </div>
+ ) : null}
+ <ApiKeyExpirationInput
+ id="gateway-key-expiry"
+ expiryPreset={expiryPreset}
+ customExpiry={customExpiry}
+ onExpiryPresetChange={setExpiryPreset}
+ onCustomExpiryChange={setCustomExpiry}
+ />
+ <Collapsible
+ open={isMetadataOpen}
+ onOpenChange={setIsMetadataOpen}
+ >
+ <div className="flex items-center gap-1.5">
+ <CollapsibleTrigger asChild>
<button
type="button"
- className="text-primary mt-2 flex items-center gap-1 text-sm hover:underline"
- onClick={() => {
- setMetadata((current) => [
- ...current,
- { id: nextMetadataId, key: "", value: "" },
- ]);
- setNextMetadataId((current) => current + 1);
- }}
+ className="group flex items-center gap-2 text-left text-sm"
>
- <Plus size="base" />
- Add metadata
+ <ChevronRight
+ size="base"
+ color="tertiary"
+ __rawClassName="translate-y-px transition-transform group-data-[state=open]:rotate-90"
+ />
+ <span>Metadata</span>
+ <span className="text-muted-foreground font-normal">
+ (optional)
+ {metadataCount > 0 ? ` · ${metadataCount} set` : ""}
+ </span>
</button>
- </CollapsibleContent>
- </Collapsible>
- {create.isError ? (
- <Alert variant="destructive">
- <Alert.Title>Gateway key could not be created</Alert.Title>
- <Alert.Description>
- {create.error?.message ??
- "Check the metadata and try again."}
- </Alert.Description>
- </Alert>
- ) : null}
- </DialogBody>
- <DialogFooter>
- <Button variant="secondary" onClick={closeDialog}>
- Cancel
- </Button>
- <Button
- loading={create.isPending}
- disabled={create.isPending || expiresAt === undefined}
- onClick={submit}
- >
- Create key
- </Button>
- </DialogFooter>
- </>
- )}
- </>
- )}
+ </CollapsibleTrigger>
+ <InfoTooltip label="About gateway key metadata">
+ Attached to every trace from this key, so you can filter and
+ group by it.
+ </InfoTooltip>
+ </div>
+ <CollapsibleContent className="mt-2 pl-5.5">
+ <div className="flex flex-col gap-2">
+ {metadata.map((field) => (
+ <div
+ key={field.id}
+ className="ph-no-capture flex items-center gap-2"
+ >
+ <Input
+ aria-label="Metadata key"
+ placeholder="key"
+ value={field.key}
+ onChange={(event) =>
+ setMetadata((current) =>
+ current.map((item) =>
+ item.id === field.id
+ ? { ...item, key: event.target.value }
+ : item,
+ ),
+ )
+ }
+ />
+ <Input
+ aria-label="Metadata value"
+ placeholder="value"
+ value={field.value}
+ onChange={(event) =>
+ setMetadata((current) =>
+ current.map((item) =>
+ item.id === field.id
+ ? { ...item, value: event.target.value }
+ : item,
+ ),
+ )
+ }
+ />
+ <Button
+ size="icon-xs"
+ variant="ghost"
+ aria-label="Remove metadata field"
+ onClick={() =>
+ setMetadata((current) =>
+ current.filter((item) => item.id !== field.id),
+ )
+ }
+ >
+ <X size="sm" color="default" />
+ </Button>
+ </div>
+ ))}
+ </div>
+ <button
+ type="button"
+ className="text-primary mt-2 flex items-center gap-1 text-sm hover:underline"
+ onClick={() => {
+ setMetadata((current) => [
+ ...current,
+ { id: nextMetadataId, key: "", value: "" },
+ ]);
+ setNextMetadataId((current) => current + 1);
+ }}
+ >
+ <Plus size="base" />
+ Add metadata
+ </button>
+ </CollapsibleContent>
+ </Collapsible>
+ {create.isError ? (
+ <Alert variant="destructive">
+ <Alert.Title>Gateway key could not be created</Alert.Title>
+ <Alert.Description>
+ {create.error?.message ??
+ "Check the metadata and try again."}
+ </Alert.Description>
+ </Alert>
+ ) : null}
+ </Dialog.Body>
+ </Dialog>
+ )
+ }
>
- {({ openDialog }) => children({ openDialog })}
+ {({ openDialog }) =>
+ children({
+ openDialog: () => {
+ reset();
+ openDialog();
+ },
+ })
+ }
</DialogController>
);
}
diff --git a/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent.tsx b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent.tsx
deleted file mode 100644
index 9c6f31625b..0000000000
--- a/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent.tsx
+++ /dev/null
@@ -1,23 +0,0 @@
-/* eslint-disable @typescript-eslint/no-deprecated -- Legacy UI usage retained during migration to design-system components. */
-import { CodeSection } from "@/src/components/design-system/CodeSection/CodeSection";
-import { DialogBody } from "@/src/components/ui/dialog";
-
-export function GeneratedKeyContent({
- generatedKeys,
-}: {
- generatedKeys: { publicKey: string; secretKey: string };
-}) {
- return (
- <DialogBody className="ph-no-capture">
- <div>
- <p className="text-muted-foreground text-sm">
- This key can only be viewed once. You can always create new keys in
- the organization settings.
- </p>
- <div className="mt-2">
- <CodeSection variant="outline" content={generatedKeys.secretKey} />
- </div>
- </div>
- </DialogBody>
- );
-}
diff --git a/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/GeneratedKeyContent.tsx b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/GeneratedKeyContent.tsx
new file mode 100644
index 0000000000..0cebcf98a3
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/GeneratedKeyContent.tsx
@@ -0,0 +1,120 @@
+import { useState } from "react";
+import { Braces, SquareTerminal, type IconComponent } from "@langfuse/icons";
+import { SiClaude, SiOpenai } from "@langfuse/icons/si";
+
+import { Alert } from "@/src/components/design-system/Alert/Alert";
+import { Button } from "@/src/components/design-system/Button/Button";
+import { Dialog } from "@/src/components/design-system/Dialog/Dialog";
+import { ExpandableContentPeek } from "@/src/components/design-system/ExpandableContentPeek/ExpandableContentPeek";
+import { Tabs } from "@/src/components/design-system/Tabs/Tabs";
+import { Skeleton } from "@/src/components/ui/skeleton";
+import type { AgentSetupInstructions } from "@/src/features/ai-gateway/types/agentSetupInstructions";
+import { AgentSetupSteps } from "./components/AgentSetupSteps";
+import { CopyForAgentButton } from "./components/CopyForAgentButton";
+import { MaskedGatewayKey } from "./components/MaskedGatewayKey";
+import { useAgentSetupInstructions } from "./hooks/useAgentSetupInstructions";
+
+const DEFAULT_TAB: AgentSetupInstructions["id"] = "api";
+
+const TAB_ICONS: Record<AgentSetupInstructions["id"], IconComponent> = {
+ api: Braces,
+ "claude-desktop": SiClaude,
+ "claude-code": SiClaude,
+ codex: SiOpenai,
+ opencode: SquareTerminal,
+};
+
+type SetupInstructionsProps = {
+ organizationId: string;
+};
+
+function SetupInstructions({ organizationId }: SetupInstructionsProps) {
+ const { instructions, isPending, isError } =
+ useAgentSetupInstructions(organizationId);
+ const [activeTab, setActiveTab] = useState<string>(DEFAULT_TAB);
+
+ if (isPending) {
+ return <Skeleton className="h-48 w-full" />;
+ }
+ if (isError || !instructions) {
+ return (
+ <Alert variant="destructive">
+ <Alert.Title>Setup instructions could not be loaded</Alert.Title>
+ <Alert.Description>
+ Your key works. Follow the docs to connect your tools.
+ </Alert.Description>
+ </Alert>
+ );
+ }
+
+ const activeEntry =
+ instructions.find((entry) => entry.id === activeTab) ?? instructions[0];
+
+ return (
+ <div className="flex flex-col gap-2">
+ <div className="flex items-baseline gap-1">
+ <h3 className="font-bold">Usage instructions</h3>
+ {activeEntry ? (
+ <Button
+ variant="text"
+ size="sm"
+ text="Docs"
+ href={activeEntry.docsUrl}
+ />
+ ) : null}
+ </div>
+ <Tabs value={activeTab} onValueChange={setActiveTab}>
+ <div className="flex h-9 items-center border-b">
+ <Tabs.List
+ variant="underline"
+ overflow="menu"
+ aria-label="Setup instructions"
+ >
+ {instructions.map((entry) => (
+ <Tabs.Trigger
+ key={entry.id}
+ value={entry.id}
+ label={entry.label}
+ icon={TAB_ICONS[entry.id]}
+ />
+ ))}
+ </Tabs.List>
+ </div>
+ {instructions.map((entry) => (
+ <Tabs.Content key={entry.id} value={entry.id}>
+ <div className="flex flex-col items-start gap-3 pt-4">
+ <CopyForAgentButton instructions={entry} />
+ {/* Inactive tabs unmount, so switching tabs collapses the peek again. */}
+ <div className="w-full">
+ <ExpandableContentPeek expandLabel="Show all steps">
+ <AgentSetupSteps instructions={entry} />
+ </ExpandableContentPeek>
+ </div>
+ </div>
+ </Tabs.Content>
+ ))}
+ </Tabs>
+ </div>
+ );
+}
+
+type GeneratedKeyContentProps = {
+ organizationId: string;
+ secretKey: string;
+};
+
+export function GeneratedKeyContent({
+ organizationId,
+ secretKey,
+}: GeneratedKeyContentProps) {
+ return (
+ <Dialog.Body>
+ <p className="text-muted-foreground">
+ Copy the key now. It is shown only once.
+ </p>
+ <MaskedGatewayKey secretKey={secretKey} />
+ <hr className="-mx-4" />
+ <SetupInstructions organizationId={organizationId} />
+ </Dialog.Body>
+ );
+}
diff --git a/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/components/AgentSetupSteps.tsx b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/components/AgentSetupSteps.tsx
new file mode 100644
index 0000000000..80a5f7824c
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/components/AgentSetupSteps.tsx
@@ -0,0 +1,42 @@
+import { Alert } from "@/src/components/design-system/Alert/Alert";
+import { CodeSection } from "@/src/components/design-system/CodeSection/CodeSection";
+import { Stepper } from "@/src/components/design-system/Stepper/Stepper";
+import type { AgentSetupInstructions } from "@/src/features/ai-gateway/types/agentSetupInstructions";
+
+type AgentSetupStepsProps = {
+ instructions: AgentSetupInstructions;
+};
+
+export function AgentSetupSteps({ instructions }: AgentSetupStepsProps) {
+ return (
+ <div className="flex flex-col gap-3">
+ {instructions.warning ? (
+ <Alert variant="warning" size="sm">
+ <Alert.Description>{instructions.warning}</Alert.Description>
+ </Alert>
+ ) : null}
+ <div className="flex flex-col">
+ {instructions.steps.map((step, index) => (
+ <Stepper
+ key={step.title}
+ number={index + 1}
+ title={step.title}
+ description={step.description}
+ variant="outline"
+ size="sm"
+ isCollapsible={false}
+ compactBottomSpacing
+ >
+ {step.code === undefined ? null : (
+ <CodeSection
+ variant="outline"
+ content={step.code}
+ shouldWrapLines={false}
+ />
+ )}
+ </Stepper>
+ ))}
+ </div>
+ </div>
+ );
+}
diff --git a/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/components/CopyForAgentButton.tsx b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/components/CopyForAgentButton.tsx
new file mode 100644
index 0000000000..244a6a02ac
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/components/CopyForAgentButton.tsx
@@ -0,0 +1,32 @@
+import { Check, Copy } from "@langfuse/icons";
+
+import { Button } from "@/src/components/design-system/Button/Button";
+import { formatAgentSetupMarkdown } from "@/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/fns/agentSetupInstructions/formatAgentSetupMarkdown";
+import type { AgentSetupInstructions } from "@/src/features/ai-gateway/types/agentSetupInstructions";
+import { useCopyToClipboard } from "@/src/hooks/useCopyToClipboard";
+
+type CopyForAgentButtonProps = {
+ instructions: AgentSetupInstructions;
+};
+
+export function CopyForAgentButton({ instructions }: CopyForAgentButtonProps) {
+ const { copy, isCopied } = useCopyToClipboard({ successDuration: 2_000 });
+
+ const handleCopy = async () => {
+ try {
+ await copy(formatAgentSetupMarkdown(instructions));
+ } catch {
+ // Clipboard writes can be rejected when the browser denies permission.
+ }
+ };
+
+ return (
+ <Button
+ variant="secondary"
+ size="sm"
+ icon={isCopied ? Check : Copy}
+ text={isCopied ? "Copied" : "Copy for agent"}
+ onClick={handleCopy}
+ />
+ );
+}
diff --git a/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/components/MaskedGatewayKey.tsx b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/components/MaskedGatewayKey.tsx
new file mode 100644
index 0000000000..1c19ff1dd8
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/components/MaskedGatewayKey.tsx
@@ -0,0 +1,75 @@
+import { useState } from "react";
+import { Check, Copy, Eye, EyeOff } from "@langfuse/icons";
+
+import { IconButton } from "@/src/components/design-system/IconButton/IconButton";
+import { Tooltip } from "@/src/components/design-system/Tooltip/Tooltip";
+import { useCopyToClipboard } from "@/src/hooks/useCopyToClipboard";
+
+const SECRET_KEY_PREFIX = "sk-lf-";
+const VISIBLE_CHARACTERS = 4;
+const MASK = "•".repeat(20);
+
+/** Keeps the `sk-lf-` prefix plus the first and last four characters readable. */
+function maskSecretKey(secretKey: string) {
+ const prefixLength = secretKey.startsWith(SECRET_KEY_PREFIX)
+ ? SECRET_KEY_PREFIX.length
+ : 0;
+ const secretPart = secretKey.slice(prefixLength);
+ if (secretPart.length <= VISIBLE_CHARACTERS * 2) return MASK;
+ return `${secretKey.slice(0, prefixLength + VISIBLE_CHARACTERS)}${MASK}${secretKey.slice(-VISIBLE_CHARACTERS)}`;
+}
+
+type MaskedGatewayKeyProps = {
+ secretKey: string;
+};
+
+export function MaskedGatewayKey({ secretKey }: MaskedGatewayKeyProps) {
+ const [isRevealed, setIsRevealed] = useState(false);
+ const { copy, isCopied } = useCopyToClipboard();
+ const revealLabel = isRevealed ? "Hide key" : "Show key";
+ const copyLabel = isCopied ? "Copied" : "Copy key";
+
+ const toggleReveal = () => setIsRevealed((current) => !current);
+ const handleCopy = async () => {
+ try {
+ await copy(secretKey);
+ } catch {
+ // The key is shown only once, so a denied clipboard write must leave
+ // it selectable by hand.
+ setIsRevealed(true);
+ }
+ };
+
+ return (
+ <div className="ph-no-capture bg-background flex items-center gap-2 rounded-md border py-1.5 pr-1.5 pl-3">
+ <code className="min-w-0 flex-1 font-mono text-sm break-all">
+ {isRevealed ? secretKey : maskSecretKey(secretKey)}
+ </code>
+ <Tooltip label={revealLabel}>
+ {({ getTriggerProps }) => (
+ <IconButton
+ {...getTriggerProps()}
+ icon={isRevealed ? EyeOff : Eye}
+ label={revealLabel}
+ size="sm"
+ variant="outline"
+ aria-pressed={isRevealed}
+ onClick={toggleReveal}
+ />
+ )}
+ </Tooltip>
+ <Tooltip label={copyLabel}>
+ {({ getTriggerProps }) => (
+ <IconButton
+ {...getTriggerProps()}
+ icon={isCopied ? Check : Copy}
+ label={copyLabel}
+ size="sm"
+ variant="outline"
+ onClick={handleCopy}
+ />
+ )}
+ </Tooltip>
+ </div>
+ );
+}
diff --git a/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/fns/agentSetupInstructions/AGENTS.md b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/fns/agentSetupInstructions/AGENTS.md
new file mode 100644
index 0000000000..7063347d9f
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/fns/agentSetupInstructions/AGENTS.md
@@ -0,0 +1,25 @@
+# Agent setup instructions
+
+Snippets shown after a gateway API key is created, one builder per tab.
+
+## Source of truth
+
+The Langfuse docs own this content. These builders are a condensed copy:
+
+- API: https://langfuse.com/docs/ai-gateway/get-started
+- Claude Code: https://langfuse.com/docs/ai-gateway/coding-agents/claude-code
+- Codex: https://langfuse.com/docs/ai-gateway/coding-agents/codex
+- OpenCode: https://langfuse.com/docs/ai-gateway/coding-agents/opencode
+
+Change the docs first (`langfuse/langfuse-docs`), then mirror the change here.
+Do not add steps, paths or env vars that the docs do not describe.
+
+## Rules
+
+- Never put the secret key into a snippet. Use `GATEWAY_KEY_PLACEHOLDER`; the
+ key is shown and copied only by the key field above the tabs.
+- Snippets set only `langfuse-user-id` from the recommended headers.
+- Paths differ per tool (`/anthropic` vs `/anthropic/v1`); keep them as the
+ docs list them under "Base URLs at a glance".
+- Builders are pure: `(context: AgentSetupContext) => AgentSetupInstructions`.
+ `formatAgentSetupMarkdown` renders the same data for "Copy for agent".
diff --git a/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/fns/agentSetupInstructions/__tests__/agentSetupInstructions.clienttest.ts b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/fns/agentSetupInstructions/__tests__/agentSetupInstructions.clienttest.ts
new file mode 100644
index 0000000000..1cd4062c3a
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/fns/agentSetupInstructions/__tests__/agentSetupInstructions.clienttest.ts
@@ -0,0 +1,64 @@
+import { GATEWAY_KEY_PLACEHOLDER } from "@/src/features/ai-gateway/constants/agentSetupInstructions";
+import { buildAgentSetupInstructions } from "../buildAgentSetupInstructions";
+import { buildApiInstructions } from "../buildApiInstructions";
+import { buildOpenCodeInstructions } from "../buildOpenCodeInstructions";
+import { formatAgentSetupMarkdown } from "../formatAgentSetupMarkdown";
+
+const context = {
+ gatewayOrigin: "https://gateway.example.com",
+ userId: "[email protected]",
+ providers: ["ANTHROPIC" as const],
+};
+
+describe("agent setup instructions", () => {
+ it("only checks the routes of configured providers", () => {
+ const codes = buildApiInstructions(context).steps.flatMap(
+ (s) => s.code ?? [],
+ );
+
+ expect(codes.some((code) => code.includes("/anthropic/v1/models"))).toBe(
+ true,
+ );
+ expect(codes.some((code) => code.includes("/openai/v1/models"))).toBe(
+ false,
+ );
+ });
+
+ it("falls back to every provider and warns when none is enabled", () => {
+ const api = buildApiInstructions({ ...context, providers: [] });
+ const openCodeConfig = buildOpenCodeInstructions({
+ ...context,
+ providers: [],
+ }).steps.find((step) => step.language === "json")?.code;
+
+ expect(api.warning).toBeDefined();
+ expect(api.steps.map((s) => s.code).join("\n")).toContain(
+ "/openai/v1/models",
+ );
+ expect(JSON.parse(openCodeConfig ?? "{}").providers).toHaveProperty(
+ "openai",
+ );
+ });
+
+ it("puts the key placeholder into the commands of every terminal setup", () => {
+ for (const instructions of buildAgentSetupInstructions(context)) {
+ // Claude Desktop takes the key in a settings field, not a command.
+ if (instructions.id === "claude-desktop") continue;
+ const code = instructions.steps.flatMap((s) => s.code ?? []).join("\n");
+
+ expect(code).toContain(GATEWAY_KEY_PLACEHOLDER);
+ }
+ });
+
+ it("copies markdown with a heading and docs link", () => {
+ for (const instructions of buildAgentSetupInstructions(context)) {
+ const markdown = formatAgentSetupMarkdown(instructions);
+
+ expect(markdown).toMatch(/^# /);
+ expect(markdown).not.toContain("undefined");
+ expect(markdown.trimEnd()).toMatch(
+ new RegExp(`Docs: ${instructions.docsUrl}$`),
+ );
+ }
+ });
+});
diff --git a/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/fns/agentSetupInstructions/buildAgentSetupInstructions.ts b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/fns/agentSetupInstructions/buildAgentSetupInstructions.ts
new file mode 100644
index 0000000000..e3246dfbe3
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/fns/agentSetupInstructions/buildAgentSetupInstructions.ts
@@ -0,0 +1,17 @@
+import type { AgentSetupContext } from "@/src/features/ai-gateway/types/agentSetupInstructions";
+import { buildApiInstructions } from "./buildApiInstructions";
+import { buildClaudeCodeInstructions } from "./buildClaudeCodeInstructions";
+import { buildClaudeDesktopInstructions } from "./buildClaudeDesktopInstructions";
+import { buildCodexInstructions } from "./buildCodexInstructions";
+import { buildOpenCodeInstructions } from "./buildOpenCodeInstructions";
+
+/** Tab order of the "Gateway key created" dialog. */
+export function buildAgentSetupInstructions(context: AgentSetupContext) {
+ return [
+ buildApiInstructions(context),
+ buildClaudeDesktopInstructions(context),
+ buildClaudeCodeInstructions(context),
+ buildCodexInstructions(context),
+ buildOpenCodeInstructions(context),
+ ];
+}
diff --git a/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/fns/agentSetupInstructions/buildApiInstructions.ts b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/fns/agentSetupInstructions/buildApiInstructions.ts
new file mode 100644
index 0000000000..cbdf01dc5f
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/fns/agentSetupInstructions/buildApiInstructions.ts
@@ -0,0 +1,64 @@
+import {
+ AGENT_SETUP_DOCS_URLS,
+ GATEWAY_KEY_PLACEHOLDER,
+} from "@/src/features/ai-gateway/constants/agentSetupInstructions";
+import type {
+ AgentSetupContext,
+ AgentSetupInstructions,
+ AgentSetupStep,
+} from "@/src/features/ai-gateway/types/agentSetupInstructions";
+import type { GatewayProvider } from "@/src/features/ai-gateway/types/gatewayProvider";
+
+const LIST_MODELS_STEPS: Record<GatewayProvider, AgentSetupStep> = {
+ OPENAI: {
+ title: "List models through the OpenAI route",
+ description: "A model list means the key and the provider connection work.",
+ language: "sh",
+ code: [
+ 'curl -s "$LANGFUSE_GATEWAY_HOST/openai/v1/models" \\',
+ ' -H "Authorization: Bearer $LANGFUSE_GATEWAY_KEY"',
+ ].join("\n"),
+ },
+ ANTHROPIC: {
+ title: "List models through the Anthropic route",
+ description: "A model list means the key and the provider connection work.",
+ language: "sh",
+ code: [
+ 'curl -s "$LANGFUSE_GATEWAY_HOST/anthropic/v1/models?limit=1000" \\',
+ ' -H "x-api-key: $LANGFUSE_GATEWAY_KEY" \\',
+ ' -H "anthropic-version: 2023-06-01"',
+ ].join("\n"),
+ },
+};
+
+export function buildApiInstructions(
+ context: AgentSetupContext,
+): AgentSetupInstructions {
+ const providers: GatewayProvider[] =
+ context.providers.length > 0 ? context.providers : ["OPENAI", "ANTHROPIC"];
+
+ return {
+ id: "api",
+ label: "API",
+ heading: "Call the Langfuse AI Gateway over HTTP",
+ summary:
+ "Export the gateway host and key, then list the models through the provider routes to check the setup.",
+ docsUrl: AGENT_SETUP_DOCS_URLS.api,
+ warning:
+ context.providers.length === 0
+ ? "No provider connection is enabled yet. Requests fail until an organization admin adds one."
+ : undefined,
+ steps: [
+ {
+ title: "Export the gateway host and key",
+ description: "Replace the placeholder with your gateway key.",
+ language: "sh",
+ code: [
+ `export LANGFUSE_GATEWAY_HOST="${context.gatewayOrigin}"`,
+ `export LANGFUSE_GATEWAY_KEY="${GATEWAY_KEY_PLACEHOLDER}"`,
+ ].join("\n"),
+ },
+ ...providers.map((provider) => LIST_MODELS_STEPS[provider]),
+ ],
+ };
+}
diff --git a/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/fns/agentSetupInstructions/buildClaudeCodeInstructions.ts b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/fns/agentSetupInstructions/buildClaudeCodeInstructions.ts
new file mode 100644
index 0000000000..a2b84e48e4
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/fns/agentSetupInstructions/buildClaudeCodeInstructions.ts
@@ -0,0 +1,50 @@
+import {
+ AGENT_SETUP_DOCS_URLS,
+ GATEWAY_KEY_PLACEHOLDER,
+} from "@/src/features/ai-gateway/constants/agentSetupInstructions";
+import type {
+ AgentSetupContext,
+ AgentSetupInstructions,
+} from "@/src/features/ai-gateway/types/agentSetupInstructions";
+
+export function buildClaudeCodeInstructions(
+ context: AgentSetupContext,
+): AgentSetupInstructions {
+ return {
+ id: "claude-code",
+ label: "Claude Code",
+ heading: "Route Claude Code through the Langfuse AI Gateway",
+ summary:
+ "Point the Claude Code CLI at the gateway so every model call is recorded in Langfuse.",
+ docsUrl: AGENT_SETUP_DOCS_URLS["claude-code"],
+ warning: context.providers.includes("ANTHROPIC")
+ ? undefined
+ : "Claude Code needs an Anthropic provider connection, and none is enabled yet.",
+ steps: [
+ {
+ title: "Log out of any existing session",
+ description: "An existing Claude login sends conflicting credentials.",
+ language: "sh",
+ code: "claude /logout",
+ },
+ {
+ title: "Point Claude Code at the gateway",
+ description:
+ "No /v1 in the base URL. Claude Code appends it. Leave ANTHROPIC_API_KEY unset.",
+ language: "sh",
+ code: [
+ `export ANTHROPIC_BASE_URL="${context.gatewayOrigin}/anthropic"`,
+ `export ANTHROPIC_AUTH_TOKEN="${GATEWAY_KEY_PLACEHOLDER}"`,
+ "unset ANTHROPIC_API_KEY",
+ `export ANTHROPIC_CUSTOM_HEADERS="langfuse-user-id: ${context.userId}"`,
+ ].join("\n"),
+ },
+ {
+ title: "Start Claude Code",
+ description: "Your sessions appear in Langfuse under Sessions.",
+ language: "sh",
+ code: "claude",
+ },
+ ],
+ };
+}
diff --git a/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/fns/agentSetupInstructions/buildClaudeDesktopInstructions.ts b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/fns/agentSetupInstructions/buildClaudeDesktopInstructions.ts
new file mode 100644
index 0000000000..814c475163
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/fns/agentSetupInstructions/buildClaudeDesktopInstructions.ts
@@ -0,0 +1,50 @@
+import { AGENT_SETUP_DOCS_URLS } from "@/src/features/ai-gateway/constants/agentSetupInstructions";
+import type {
+ AgentSetupContext,
+ AgentSetupInstructions,
+} from "@/src/features/ai-gateway/types/agentSetupInstructions";
+
+export function buildClaudeDesktopInstructions(
+ context: AgentSetupContext,
+): AgentSetupInstructions {
+ return {
+ id: "claude-desktop",
+ label: "Claude Desktop",
+ heading: "Route Claude Desktop through the Langfuse AI Gateway",
+ summary:
+ "Configure third-party inference in the Claude Desktop app so every model call is recorded in Langfuse.",
+ docsUrl: AGENT_SETUP_DOCS_URLS["claude-desktop"],
+ warning: context.providers.includes("ANTHROPIC")
+ ? undefined
+ : "Claude Desktop needs an Anthropic provider connection, and none is enabled yet.",
+ steps: [
+ {
+ title: "Open the third-party inference settings",
+ description:
+ "Open Developer → Configure Third-Party Inference and set Inference provider to Gateway. If the Developer menu is missing, enable Developer Mode under Help → Troubleshooting.",
+ },
+ {
+ title: "Set the gateway base URL",
+ description: "No /v1 in the base URL. Claude Desktop appends it.",
+ language: "text",
+ code: `${context.gatewayOrigin}/anthropic`,
+ },
+ {
+ title: "Add your gateway key",
+ description:
+ "Set Credential kind to Static API key, paste your gateway key as Gateway API key, and select Bearer as the auth scheme.",
+ },
+ {
+ title: "Add the user header",
+ description: "Under Custom headers, add this header.",
+ language: "text",
+ code: `langfuse-user-id: ${context.userId}`,
+ },
+ {
+ title: "Apply and restart",
+ description:
+ "Test the connection, select Apply Changes, then Save & Restart.",
+ },
+ ],
+ };
+}
diff --git a/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/fns/agentSetupInstructions/buildCodexInstructions.ts b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/fns/agentSetupInstructions/buildCodexInstructions.ts
new file mode 100644
index 0000000000..0f71d462c3
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/fns/agentSetupInstructions/buildCodexInstructions.ts
@@ -0,0 +1,63 @@
+import {
+ AGENT_SETUP_DOCS_URLS,
+ GATEWAY_KEY_PLACEHOLDER,
+} from "@/src/features/ai-gateway/constants/agentSetupInstructions";
+import type {
+ AgentSetupContext,
+ AgentSetupInstructions,
+} from "@/src/features/ai-gateway/types/agentSetupInstructions";
+
+export function buildCodexInstructions(
+ context: AgentSetupContext,
+): AgentSetupInstructions {
+ return {
+ id: "codex",
+ label: "Codex",
+ heading: "Route Codex through the Langfuse AI Gateway",
+ summary:
+ "Register the gateway as a Codex model provider so every turn is recorded in Langfuse.",
+ docsUrl: AGENT_SETUP_DOCS_URLS.codex,
+ warning: context.providers.includes("OPENAI")
+ ? undefined
+ : "Codex needs an OpenAI provider connection, and none is enabled yet.",
+ steps: [
+ {
+ title: "Store the key in Codex's .env",
+ description:
+ "Codex loads this file every time it starts. Replace the placeholder with your gateway key.",
+ language: "sh",
+ code: [
+ 'CODEX_DIR="${CODEX_HOME:-$HOME/.codex}"',
+ 'mkdir -p -m 700 "$CODEX_DIR"',
+ 'touch "$CODEX_DIR/.env" && chmod 600 "$CODEX_DIR/.env"',
+ `cat >> "$CODEX_DIR/.env" <<'EOF'`,
+ `LANGFUSE_GATEWAY_KEY=${GATEWAY_KEY_PLACEHOLDER}`,
+ `LF_USER_ID=${context.userId}`,
+ "EOF",
+ ].join("\n"),
+ },
+ {
+ title: "Add the gateway provider",
+ description:
+ "Add this to the top of config.toml in the same directory ($CODEX_HOME, or ~/.codex by default), before any [table] section, so model_provider stays a top-level key.",
+ language: "toml",
+ code: [
+ 'model_provider = "langfuse"',
+ "",
+ "[model_providers.langfuse]",
+ 'name = "Langfuse AI Gateway"',
+ `base_url = "${context.gatewayOrigin}/openai/v1"`,
+ 'env_key = "LANGFUSE_GATEWAY_KEY"',
+ 'wire_api = "responses"',
+ 'env_http_headers = { "langfuse-user-id" = "LF_USER_ID" }',
+ ].join("\n"),
+ },
+ {
+ title: "Start Codex",
+ description: "Each turn appears in Langfuse as one trace.",
+ language: "sh",
+ code: "codex",
+ },
+ ],
+ };
+}
diff --git a/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/fns/agentSetupInstructions/buildOpenCodeInstructions.ts b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/fns/agentSetupInstructions/buildOpenCodeInstructions.ts
new file mode 100644
index 0000000000..85f746cc95
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/fns/agentSetupInstructions/buildOpenCodeInstructions.ts
@@ -0,0 +1,75 @@
+import {
+ AGENT_SETUP_DOCS_URLS,
+ GATEWAY_KEY_PLACEHOLDER,
+} from "@/src/features/ai-gateway/constants/agentSetupInstructions";
+import type {
+ AgentSetupContext,
+ AgentSetupInstructions,
+} from "@/src/features/ai-gateway/types/agentSetupInstructions";
+import type { GatewayProvider } from "@/src/features/ai-gateway/types/gatewayProvider";
+
+/** OpenCode appends only `/messages`, so its Anthropic base URL keeps `/v1`. */
+const OPENCODE_PROVIDERS: Record<
+ GatewayProvider,
+ { id: string; path: string }
+> = {
+ ANTHROPIC: { id: "anthropic", path: "/anthropic/v1" },
+ OPENAI: { id: "openai", path: "/openai/v1" },
+};
+
+export function buildOpenCodeInstructions(
+ context: AgentSetupContext,
+): AgentSetupInstructions {
+ const providers: GatewayProvider[] =
+ context.providers.length > 0 ? context.providers : ["ANTHROPIC", "OPENAI"];
+ const config = {
+ $schema: "https://opencode.ai/config.json",
+ providers: Object.fromEntries(
+ providers.map((provider) => [
+ OPENCODE_PROVIDERS[provider].id,
+ {
+ settings: {
+ baseURL: `${context.gatewayOrigin}${OPENCODE_PROVIDERS[provider].path}`,
+ apiKey: "{env:LANGFUSE_GATEWAY_KEY}",
+ },
+ headers: { "langfuse-user-id": context.userId },
+ },
+ ]),
+ ),
+ };
+
+ return {
+ id: "opencode",
+ label: "OpenCode",
+ heading: "Route OpenCode through the Langfuse AI Gateway",
+ summary:
+ "Override OpenCode's built-in providers so every model call is recorded in Langfuse.",
+ docsUrl: AGENT_SETUP_DOCS_URLS.opencode,
+ warning:
+ context.providers.length === 0
+ ? "OpenCode needs an Anthropic or OpenAI provider connection, and none is enabled yet."
+ : undefined,
+ steps: [
+ {
+ title: "Export the gateway key",
+ description:
+ "Replace the placeholder with your gateway key. After changing it, run opencode service restart.",
+ language: "sh",
+ code: `export LANGFUSE_GATEWAY_KEY="${GATEWAY_KEY_PLACEHOLDER}"`,
+ },
+ {
+ title: "Add the gateway providers",
+ description:
+ "Add this to ~/.config/opencode/opencode.json. Remove stored OpenCode account connections for these providers first; they take precedence.",
+ language: "json",
+ code: JSON.stringify(config, null, 2),
+ },
+ {
+ title: "Start OpenCode",
+ description: "Your sessions appear in Langfuse under Sessions.",
+ language: "sh",
+ code: "opencode",
+ },
+ ],
+ };
+}
diff --git a/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/fns/agentSetupInstructions/formatAgentSetupMarkdown.ts b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/fns/agentSetupInstructions/formatAgentSetupMarkdown.ts
new file mode 100644
index 0000000000..0f20b5a711
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/fns/agentSetupInstructions/formatAgentSetupMarkdown.ts
@@ -0,0 +1,28 @@
+import { GATEWAY_KEY_PLACEHOLDER } from "@/src/features/ai-gateway/constants/agentSetupInstructions";
+import type { AgentSetupInstructions } from "@/src/features/ai-gateway/types/agentSetupInstructions";
+
+/** Markdown for "Copy for agent"; it carries the key placeholder, never the key. */
+export function formatAgentSetupMarkdown(instructions: AgentSetupInstructions) {
+ const steps = instructions.steps.map((step, index) =>
+ [
+ `## ${index + 1}. ${step.title}`,
+ step.description,
+ step.code === undefined
+ ? undefined
+ : `\`\`\`${step.language}\n${step.code}\n\`\`\``,
+ ]
+ .filter(Boolean)
+ .join("\n\n"),
+ );
+
+ return [
+ `# ${instructions.heading}`,
+ `${instructions.summary} Ask the user for their Langfuse gateway key and use it in place of \`${GATEWAY_KEY_PLACEHOLDER}\`. Never write the key into a repository or a shared file.`,
+ instructions.warning ? `> Note: ${instructions.warning}` : undefined,
+ ...steps,
+ `Docs: ${instructions.docsUrl}`,
+ ]
+ .filter(Boolean)
+ .join("\n\n")
+ .concat("\n");
+}
diff --git a/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/hooks/useAgentSetupInstructions.ts b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/hooks/useAgentSetupInstructions.ts
new file mode 100644
index 0000000000..14c22c347a
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/hooks/useAgentSetupInstructions.ts
@@ -0,0 +1,33 @@
+import { useSession } from "next-auth/react";
+
+import { GATEWAY_USER_ID_PLACEHOLDER } from "@/src/features/ai-gateway/constants/agentSetupInstructions";
+import { buildAgentSetupInstructions } from "@/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent/fns/agentSetupInstructions/buildAgentSetupInstructions";
+import { api } from "@/src/utils/api";
+
+/** Characters that would need escaping in a shell, TOML or JSON string. */
+const UNSAFE_SNIPPET_CHARACTERS = /["'`$\\\s]/;
+
+export function useAgentSetupInstructions(organizationId: string) {
+ const { data: session } = useSession();
+ const clientSetup = api.aiGateway.getClientSetup.useQuery({
+ orgId: organizationId,
+ });
+
+ const email = session?.user?.email;
+ const userId =
+ email && !UNSAFE_SNIPPET_CHARACTERS.test(email)
+ ? email
+ : GATEWAY_USER_ID_PLACEHOLDER;
+
+ return {
+ instructions: clientSetup.data
+ ? buildAgentSetupInstructions({
+ gatewayOrigin: new URL(clientSetup.data.gatewayBaseUrl).origin,
+ userId,
+ providers: clientSetup.data.providers,
+ })
+ : undefined,
+ isPending: clientSetup.isPending,
+ isError: clientSetup.isError,
+ };
+}
diff --git a/web/src/features/ai-gateway/constants/agentSetupInstructions.ts b/web/src/features/ai-gateway/constants/agentSetupInstructions.ts
new file mode 100644
index 0000000000..aa8a44e0e5
--- /dev/null
+++ b/web/src/features/ai-gateway/constants/agentSetupInstructions.ts
@@ -0,0 +1,12 @@
+export const GATEWAY_KEY_PLACEHOLDER = "<your-gateway-key>";
+export const GATEWAY_USER_ID_PLACEHOLDER = "<you>@example.com";
+
+const GATEWAY_DOCS_URL = "https://langfuse.com/docs/ai-gateway";
+
+export const AGENT_SETUP_DOCS_URLS = {
+ api: `${GATEWAY_DOCS_URL}/get-started`,
+ "claude-desktop": `${GATEWAY_DOCS_URL}/coding-agents/claude-code#claude-desktop`,
+ "claude-code": `${GATEWAY_DOCS_URL}/coding-agents/claude-code#claude-code-cli`,
+ codex: `${GATEWAY_DOCS_URL}/coding-agents/codex`,
+ opencode: `${GATEWAY_DOCS_URL}/coding-agents/opencode`,
+} as const;
diff --git a/web/src/features/ai-gateway/server/router.ts b/web/src/features/ai-gateway/server/router.ts
index 120ab4ad43..5719fcfc10 100644
--- a/web/src/features/ai-gateway/server/router.ts
+++ b/web/src/features/ai-gateway/server/router.ts
@@ -135,6 +135,23 @@ export const aiGatewayRouter = createTRPCRouter({
return new GatewayConfigService(ctx.prisma).getSetupStatus(input.orgId);
}),
+ /** What a key owner needs to point a client at the gateway; no connection details. */
+ getClientSetup: protectedOrganizationProcedure
+ .input(organizationInput)
+ .query(async ({ input, ctx }) => {
+ requireGatewayInvoke({ session: ctx.session, orgId: input.orgId });
+ const connections = await new GatewayProviderService(ctx.prisma).listAll(
+ input.orgId,
+ GatewayConnectionStatus.ENABLED,
+ );
+ return {
+ gatewayBaseUrl: getGatewayBaseUrl(getProductBaseUrl()),
+ providers: [
+ ...new Set(connections.map((connection) => connection.provider)),
+ ],
+ };
+ }),
+
updateConfig: protectedOrganizationProcedure
.input(
organizationInput.extend({
diff --git a/web/src/features/ai-gateway/types/agentSetupInstructions.ts b/web/src/features/ai-gateway/types/agentSetupInstructions.ts
new file mode 100644
index 0000000000..4d6f6622d5
--- /dev/null
+++ b/web/src/features/ai-gateway/types/agentSetupInstructions.ts
@@ -0,0 +1,32 @@
+import type { GatewayProvider } from "@/src/features/ai-gateway/types/gatewayProvider";
+
+/** What the snippets are rendered from; the secret key is deliberately not part of it. */
+export type AgentSetupContext = {
+ /** Gateway origin without a path, e.g. `https://staging.langfuse.com`. */
+ gatewayOrigin: string;
+ /** Sent as `langfuse-user-id`; already safe to embed in shell, TOML and JSON strings. */
+ userId: string;
+ /** Providers with an enabled connection in the organization. */
+ providers: GatewayProvider[];
+};
+
+export type AgentSetupStep = {
+ title: string;
+ description?: string;
+} & (
+ | { language: "sh" | "toml" | "json" | "text"; code: string }
+ /** A step done in a settings UI, with nothing to paste. */
+ | { language?: never; code?: never }
+);
+
+export type AgentSetupInstructions = {
+ id: "api" | "claude-desktop" | "claude-code" | "codex" | "opencode";
+ label: string;
+ /** First line of the "Copy for agent" Markdown. */
+ heading: string;
+ summary: string;
+ docsUrl: string;
+ /** Set when the organization lacks a provider connection the tool needs. */
+ warning?: string;
+ steps: AgentSetupStep[];
+};
diff --git a/web/src/features/evals/v2/components/Evaluators/EvaluatorSetupEditor/components/DefinitionStep/DefinitionStep.tsx b/web/src/features/evals/v2/components/Evaluators/EvaluatorSetupEditor/components/DefinitionStep/DefinitionStep.tsx
index ce06f8f5ac..cecae54bbd 100644
--- a/web/src/features/evals/v2/components/Evaluators/EvaluatorSetupEditor/components/DefinitionStep/DefinitionStep.tsx
+++ b/web/src/features/evals/v2/components/Evaluators/EvaluatorSetupEditor/components/DefinitionStep/DefinitionStep.tsx
@@ -2,7 +2,7 @@ import type { EvalTemplateType } from "@langfuse/shared";
import type { ReactNode } from "react";
import { EvaluationTypeConfiguration } from "@/src/features/evals/v2/components/Evaluators/EvaluationTypeConfiguration/EvaluationTypeConfiguration";
-import { Stepper } from "@/src/features/evals/v2/components/Stepper/Stepper";
+import { Stepper } from "@/src/components/design-system/Stepper/Stepper";
type DefinitionStepProps = {
open: boolean;
diff --git a/web/src/features/evals/v2/components/Evaluators/EvaluatorSetupEditor/components/NameStep/NameStep.tsx b/web/src/features/evals/v2/components/Evaluators/EvaluatorSetupEditor/components/NameStep/NameStep.tsx
index 7e54c8c9f3..ad7c8885dd 100644
--- a/web/src/features/evals/v2/components/Evaluators/EvaluatorSetupEditor/components/NameStep/NameStep.tsx
+++ b/web/src/features/evals/v2/components/Evaluators/EvaluatorSetupEditor/components/NameStep/NameStep.tsx
@@ -3,7 +3,7 @@ import type { ComponentProps } from "react";
import { AIAssistedInput } from "@/src/components/ui/AIAssistedInput";
import { Label } from "@/src/components/ui/label";
import { InfoTooltip } from "@/src/components/ui/InfoTooltip/InfoTooltip";
-import { Stepper } from "@/src/features/evals/v2/components/Stepper/Stepper";
+import { Stepper } from "@/src/components/design-system/Stepper/Stepper";
const COPY = {
default: {
diff --git a/web/src/features/evals/v2/components/Evaluators/EvaluatorSetupEditor/components/VariableMappingStep/VariableMappingStep.tsx b/web/src/features/evals/v2/components/Evaluators/EvaluatorSetupEditor/components/VariableMappingStep/VariableMappingStep.tsx
index f913b9526b..1ed0ba6b90 100644
--- a/web/src/features/evals/v2/components/Evaluators/EvaluatorSetupEditor/components/VariableMappingStep/VariableMappingStep.tsx
+++ b/web/src/features/evals/v2/components/Evaluators/EvaluatorSetupEditor/components/VariableMappingStep/VariableMappingStep.tsx
@@ -1,6 +1,6 @@
import type { ReactNode } from "react";
-import { Stepper } from "@/src/features/evals/v2/components/Stepper/Stepper";
+import { Stepper } from "@/src/components/design-system/Stepper/Stepper";
const COPY = {
variables: {
diff --git a/web/src/features/evals/v2/components/Rules/RuleSetup/components/RuleEvaluatorsStep.tsx b/web/src/features/evals/v2/components/Rules/RuleSetup/components/RuleEvaluatorsStep.tsx
index 1a6ecf6320..7a57c47892 100644
--- a/web/src/features/evals/v2/components/Rules/RuleSetup/components/RuleEvaluatorsStep.tsx
+++ b/web/src/features/evals/v2/components/Rules/RuleSetup/components/RuleEvaluatorsStep.tsx
@@ -1,7 +1,7 @@
/* eslint-disable no-nested-ternary */
import { useStore } from "zustand";
-import { Stepper } from "@/src/features/evals/v2/components/Stepper/Stepper";
+import { Stepper } from "@/src/components/design-system/Stepper/Stepper";
import { EvaluatorAssignmentsEditor } from "@/src/features/evals/v2/components/Rules/EvaluatorAssignmentsEditor/EvaluatorAssignmentsEditor";
import { buildSelectedSampleObject } from "@/src/features/evals/v2/fns/evaluatorTesting/buildSelectedSampleObject";
import type {
diff --git a/web/src/features/evals/v2/components/Rules/RuleSetup/components/RuleFilterStep.tsx b/web/src/features/evals/v2/components/Rules/RuleSetup/components/RuleFilterStep.tsx
index 808412e136..9f1dedda70 100644
--- a/web/src/features/evals/v2/components/Rules/RuleSetup/components/RuleFilterStep.tsx
+++ b/web/src/features/evals/v2/components/Rules/RuleSetup/components/RuleFilterStep.tsx
@@ -2,7 +2,7 @@ import { useState } from "react";
import { useStore } from "zustand";
import { RuleSampleObservationSelector } from "@/src/features/evals/v2/components/Evaluators/Testing/components/RuleSampleObservationSelector/RuleSampleObservationSelector";
-import { Stepper } from "@/src/features/evals/v2/components/Stepper/Stepper";
+import { Stepper } from "@/src/components/design-system/Stepper/Stepper";
import type { RuleSetupStore } from "@/src/features/evals/v2/types/rules";
import { RULE_SAMPLE_FIELD_REGISTRY } from "@/src/features/evals/v2/constants/evaluatorSearchRegistry";
import { env } from "@/src/env.mjs";
diff --git a/web/src/features/evals/v2/components/Rules/RuleSetup/components/RuleNameStep.tsx b/web/src/features/evals/v2/components/Rules/RuleSetup/components/RuleNameStep.tsx
index a09e0cbcd5..b8faf40adc 100644
--- a/web/src/features/evals/v2/components/Rules/RuleSetup/components/RuleNameStep.tsx
+++ b/web/src/features/evals/v2/components/Rules/RuleSetup/components/RuleNameStep.tsx
@@ -2,7 +2,7 @@ import type { ComponentProps } from "react";
import { useStore } from "zustand";
import { AIAssistedInput } from "@/src/components/ui/AIAssistedInput";
-import { Stepper } from "@/src/features/evals/v2/components/Stepper/Stepper";
+import { Stepper } from "@/src/components/design-system/Stepper/Stepper";
import type { RuleSetupStore } from "@/src/features/evals/v2/types/rules";
export function RuleNameStep({
diff --git a/web/src/features/evals/v2/components/Stepper/Stepper.tsx b/web/src/features/evals/v2/components/Stepper/Stepper.tsx
deleted file mode 100644
index 1402516e29..0000000000
--- a/web/src/features/evals/v2/components/Stepper/Stepper.tsx
+++ /dev/null
@@ -1,84 +0,0 @@
-import { useState, type ReactNode } from "react";
-import { ChevronDown } from "@langfuse/icons";
-
-import { cn } from "@/src/utils/tailwind";
-
-/**
- * Datadog-style vertical stepper section: a numbered circle with a connector
- * line down to the next step, and a collapsible header that toggles the step
- * body. Supports controlled expansion for progressive flows. Render steps as
- * siblings — the last one drops its connector and trailing space via
- * `:last-child`, so adding or reordering steps needs no bookkeeping.
- */
-export function Stepper({
- number,
- title,
- description,
- compactBottomSpacing = false,
- defaultOpen = true,
- open,
- onOpenChange,
- children,
-}: {
- number: number;
- title: string;
- description?: ReactNode;
- compactBottomSpacing?: boolean;
- defaultOpen?: boolean;
- open?: boolean;
- onOpenChange?: (open: boolean) => void;
- children: ReactNode;
-}) {
- const [internalOpen, setInternalOpen] = useState(defaultOpen);
- const expanded = open ?? internalOpen;
-
- const toggle = () => {
- const nextOpen = !expanded;
- if (open === undefined) setInternalOpen(nextOpen);
- onOpenChange?.(nextOpen);
- };
-
- return (
- <div className="group/step flex gap-1.5">
- <div className="flex flex-col items-center">
- <div className="bg-primary text-primary-foreground flex h-7 w-7 shrink-0 items-center justify-center rounded-full text-sm">
- {number}
- </div>
- <div className="bg-border my-1 w-px flex-1 group-last/step:hidden" />
- </div>
-
- <div
- className={cn(
- "flex min-w-0 flex-1 flex-col group-last/step:pb-0",
- compactBottomSpacing ? "pb-3" : "pb-8",
- )}
- >
- <button
- type="button"
- className="flex min-h-7 items-center gap-1.5 text-left"
- aria-label={`Step ${number}: ${title}`}
- aria-expanded={expanded}
- onClick={toggle}
- >
- <ChevronDown
- size="base"
- color="tertiary"
- __rawClassName={cn(
- "translate-y-px transition-transform",
- !expanded && "-rotate-90",
- )}
- />
- <span className="text-lg font-bold">{title}</span>
- </button>
- {expanded && (
- <div className="flex flex-col gap-4 pl-5">
- {description ? (
- <p className="text-muted-foreground text-sm">{description}</p>
- ) : null}
- {children}
- </div>
- )}
- </div>
- </div>
- );
-}
diff --git a/web/src/features/in-app-agent/components/InAppAgentMessage.stories.tsx b/web/src/features/in-app-agent/components/InAppAgentMessage.stories.tsx
index e576c3e616..adae23854d 100644
--- a/web/src/features/in-app-agent/components/InAppAgentMessage.stories.tsx
+++ b/web/src/features/in-app-agent/components/InAppAgentMessage.stories.tsx
@@ -677,16 +677,23 @@ export const CopyMessageInteraction = meta.story({
},
play: async ({ canvasElement }) => {
const canvas = within(canvasElement);
- await userEvent.hover(canvasElement);
- await userEvent.click(
- await canvas.findByRole("button", { name: "Copy message" }),
- );
+ const write = spyOn(navigator.clipboard, "write").mockResolvedValue();
- await waitFor(() =>
- expect(
- canvas.getByRole("button", { name: "Message copied" }),
- ).toBeVisible(),
- );
+ try {
+ await userEvent.hover(canvasElement);
+ await userEvent.click(
+ await canvas.findByRole("button", { name: "Copy message" }),
+ );
+
+ await waitFor(() =>
+ expect(
+ canvas.getByRole("button", { name: "Message copied" }),
+ ).toBeVisible(),
+ );
+ expect(write).toHaveBeenCalledOnce();
+ } finally {
+ write.mockRestore();
+ }
},
});
diff --git a/web/src/features/topics/ConfigureTopicsDialog.tsx b/web/src/features/topics/ConfigureTopicsDialog.tsx
index a3df061932..71ffed39c6 100644
--- a/web/src/features/topics/ConfigureTopicsDialog.tsx
+++ b/web/src/features/topics/ConfigureTopicsDialog.tsx
@@ -14,7 +14,7 @@ import {
} from "@/src/components/ui/tooltip";
import { Tabs } from "@/src/components/design-system/Tabs/Tabs";
import { Badge } from "@/src/components/design-system/Badge/Badge";
-import { Stepper } from "@/src/features/evals/v2/components/Stepper/Stepper";
+import { Stepper } from "@/src/components/design-system/Stepper/Stepper";
import {
JudgeModelPicker,
JudgeModelPickerTrigger,
diff --git a/web/src/features/topics/ManualTopicsDialog.tsx b/web/src/features/topics/ManualTopicsDialog.tsx
index 54f7931eea..e7ed3e60dd 100644
--- a/web/src/features/topics/ManualTopicsDialog.tsx
+++ b/web/src/features/topics/ManualTopicsDialog.tsx
@@ -14,7 +14,7 @@ import { Checkbox } from "@/src/components/design-system/Checkbox/Checkbox";
import { Dialog } from "@/src/components/design-system/Dialog/Dialog";
import { Switch } from "@/src/components/design-system/Switch/Switch";
import { Tabs } from "@/src/components/design-system/Tabs/Tabs";
-import { Stepper } from "@/src/features/evals/v2/components/Stepper/Stepper";
+import { Stepper } from "@/src/components/design-system/Stepper/Stepper";
export function ManualTopicsDialog({
operation,
diff --git a/web/src/hooks/useCopyToClipboard.clienttest.ts b/web/src/hooks/useCopyToClipboard.clienttest.ts
index 36531eec79..8cec89526c 100644
--- a/web/src/hooks/useCopyToClipboard.clienttest.ts
+++ b/web/src/hooks/useCopyToClipboard.clienttest.ts
@@ -55,6 +55,24 @@ describe("useCopyToClipboard", () => {
expect(result.current.isCopied).toBe(true);
});
+ it("does not report success when the clipboard write is rejected", async () => {
+ Object.defineProperty(navigator, "clipboard", {
+ configurable: true,
+ value: {
+ writeText: vi.fn().mockRejectedValue(new Error("permission denied")),
+ },
+ });
+ const { result } = renderHook(() => useCopyToClipboard());
+
+ await act(async () => {
+ await expect(result.current.copy("sk-lf-secret")).rejects.toThrow(
+ "permission denied",
+ );
+ });
+
+ expect(result.current.isCopied).toBe(false);
+ });
+
it("falls back to plain text when the browser rejects a rich clipboard write", async () => {
const write = vi.fn().mockRejectedValue(new Error("unsupported type"));
const writeText = vi.fn().mockResolvedValue(undefined);
diff --git a/web/src/hooks/useCopyToClipboard.ts b/web/src/hooks/useCopyToClipboard.ts
index 61abfc234f..9b12212624 100644
--- a/web/src/hooks/useCopyToClipboard.ts
+++ b/web/src/hooks/useCopyToClipboard.ts
@@ -24,18 +24,15 @@ export function useCopyToClipboard({
}, []);
const runCopy = async (copyToClipboard: () => Promise<void> | void) => {
+ await copyToClipboard();
setIsCopied(true);
- try {
- await copyToClipboard();
- } finally {
- if (timeoutRef.current) {
- clearTimeout(timeoutRef.current);
- }
-
- timeoutRef.current = setTimeout(() => {
- setIsCopied(false);
- }, successDuration);
+ if (timeoutRef.current) {
+ clearTimeout(timeoutRef.current);
}
+
+ timeoutRef.current = setTimeout(() => {
+ setIsCopied(false);
+ }, successDuration);
};
const copy = async (text: string) => runCopy(() => copyTextToClipboard(text));