feat(agents): instrument /code/agents page with analytics events

Add AGENTS_VIEWED and AGENTS_ACTION events mirroring the inbox-reports
instrumentation. AGENTS_VIEWED fires once per visit via a new
useTrackAgentsViewed hook; AGENTS_ACTION covers change_autostart_priority,
open_mcp_servers, and run_setup_agent from ConfigureAgentsSection.

Author: andrewm4894

packages/shared/src/analytics-events.ts

@@ -738,6 +738,33 @@ export interface SignalSourceConnectedProperties {
   via_setup_wizard: boolean;
 }
 
+// Agents page events (the `/code/agents` configuration surface)
+export type AgentsActionType =
+  | "run_setup_agent"
+  | "change_autostart_priority"
+  | "open_mcp_servers";
+
+export interface AgentsViewedProperties {
+  /** Whether code access (GitHub) is connected — gates responder configuration. */
+  has_github_integration: boolean;
+  /** Total number of responder source products on the page. */
+  responder_total_count: number;
+  /** How many of those responders are currently enabled. */
+  responder_enabled_count: number;
+  /** User's PR auto-start threshold priority (P0–P4), or null when set to "Never". */
+  autostart_priority: string | null;
+  /** Whether the agent-driven setup entry point is shown (feature-flagged). */
+  setup_task_available: boolean;
+}
+
+export interface AgentsActionProperties {
+  action_type: AgentsActionType;
+  /** New threshold for `change_autostart_priority` (P0–P4, or null for "Never"). */
+  autostart_priority?: string | null;
+  /** Whether `run_setup_agent` successfully created the setup task. */
+  success?: boolean;
+}
+
 // Subscription / billing events
 
 export type UpgradePromptShownSurface = "usage_limit_modal" | "upgrade_dialog";
@@ -885,6 +912,10 @@ export const ANALYTICS_EVENTS = {
   INBOX_REPORT_SCROLLED: "Inbox report scrolled",
   SIGNAL_SOURCE_CONNECTED: "Signal source connected",
 
+  // Agents page events
+  AGENTS_VIEWED: "Agents viewed",
+  AGENTS_ACTION: "Agents action",
+
   // Scout events
   SCOUT_FLEET_VIEWED: "Scout fleet viewed",
   SCOUT_DETAIL_VIEWED: "Scout detail viewed",
@@ -1015,6 +1046,10 @@ export type EventPropertyMap = {
   [ANALYTICS_EVENTS.INBOX_REPORT_SCROLLED]: InboxReportScrolledProperties;
   [ANALYTICS_EVENTS.SIGNAL_SOURCE_CONNECTED]: SignalSourceConnectedProperties;
 
+  // Agents page events
+  [ANALYTICS_EVENTS.AGENTS_VIEWED]: AgentsViewedProperties;
+  [ANALYTICS_EVENTS.AGENTS_ACTION]: AgentsActionProperties;
+
   // Scout events
   [ANALYTICS_EVENTS.SCOUT_FLEET_VIEWED]: ScoutFleetViewedProperties;
   [ANALYTICS_EVENTS.SCOUT_DETAIL_VIEWED]: ScoutDetailViewedProperties;

packages/ui/src/features/agents/hooks/useTrackAgentsViewed.ts

@@ -0,0 +1,52 @@
+import { ANALYTICS_EVENTS } from "@posthog/shared/analytics-events";
+import { track } from "@posthog/ui/shell/analytics";
+import { useEffect, useRef } from "react";
+
+export interface TrackAgentsViewedInput {
+  /** Gate the event until responder / integration / autonomy data has settled. */
+  isLoading: boolean;
+  hasGithubIntegration: boolean;
+  responderTotalCount: number;
+  responderEnabledCount: number;
+  /** P0–P4, or null when the user's auto-start threshold is "Never". */
+  autostartPriority: string | null;
+  setupTaskAvailable: boolean;
+}
+
+/**
+ * Fires `AGENTS_VIEWED` once per visit to the `/code/agents` configuration page,
+ * after the responder/integration/autonomy data settles, with the state the user
+ * sees on load. Mirrors `useTrackInboxViewed`; mounted from `ConfigureAgentsSection`
+ * where the data already lives, so it fires once and survives re-renders.
+ */
+export function useTrackAgentsViewed(input: TrackAgentsViewedInput): void {
+  const {
+    isLoading,
+    hasGithubIntegration,
+    responderTotalCount,
+    responderEnabledCount,
+    autostartPriority,
+    setupTaskAvailable,
+  } = input;
+
+  const firedRef = useRef(false);
+  useEffect(() => {
+    if (firedRef.current) return;
+    if (isLoading) return;
+    firedRef.current = true;
+    track(ANALYTICS_EVENTS.AGENTS_VIEWED, {
+      has_github_integration: hasGithubIntegration,
+      responder_total_count: responderTotalCount,
+      responder_enabled_count: responderEnabledCount,
+      autostart_priority: autostartPriority,
+      setup_task_available: setupTaskAvailable,
+    });
+  }, [
+    isLoading,
+    hasGithubIntegration,
+    responderTotalCount,
+    responderEnabledCount,
+    autostartPriority,
+    setupTaskAvailable,
+  ]);
+}

packages/ui/src/features/inbox/components/ConfigureAgentsSection.tsx

@@ -13,6 +13,7 @@ import { Button } from "@posthog/quill";
 import { ANALYTICS_EVENTS, getCloudUrlFromRegion } from "@posthog/shared";
 import { SELF_DRIVING_SETUP_TASK_FLAG } from "@posthog/shared/constants";
 import type { SignalReportPriority } from "@posthog/shared/types";
+import { useTrackAgentsViewed } from "@posthog/ui/features/agents/hooks/useTrackAgentsViewed";
 import { useAuthStateValue } from "@posthog/ui/features/auth/store";
 import { useFeatureFlag } from "@posthog/ui/features/feature-flags/useFeatureFlag";
 import { DataSourceSetup } from "@posthog/ui/features/inbox/components/DataSourceSetup";
@@ -94,6 +95,15 @@ export function ConfigureAgentsSection() {
   const userAutostartPriority =
     userAutonomyConfig?.autostart_priority ?? NEVER_AUTOSTART_VALUE;
 
+  useTrackAgentsViewed({
+    isLoading: isLoading || isLoadingIntegrations || userAutonomyConfigLoading,
+    hasGithubIntegration,
+    responderTotalCount: Object.keys(displayValues).length,
+    responderEnabledCount: Object.values(displayValues).filter(Boolean).length,
+    autostartPriority: userAutonomyConfig?.autostart_priority ?? null,
+    setupTaskAvailable: showSetupTask,
+  });
+
   return (
     <Flex direction="column" gap="8">
       {showSetupTask ? <SetupTaskSection /> : null}
@@ -210,11 +220,14 @@ export function ConfigureAgentsSection() {
               options={USER_AUTOSTART_OPTIONS}
               ariaLabel="PR auto-start threshold"
               className="min-w-[260px] max-w-[300px]"
-              onValueChange={(value) =>
-                void handleUpdateUserAutonomyPriority(
-                  value === NEVER_AUTOSTART_VALUE ? null : value,
-                )
-              }
+              onValueChange={(value) => {
+                const priority = value === NEVER_AUTOSTART_VALUE ? null : value;
+                track(ANALYTICS_EVENTS.AGENTS_ACTION, {
+                  action_type: "change_autostart_priority",
+                  autostart_priority: priority,
+                });
+                void handleUpdateUserAutonomyPriority(priority);
+              }}
             />
           )}
         </Flex>
@@ -226,6 +239,11 @@ export function ConfigureAgentsSection() {
       >
         <Link
           to="/mcp-servers"
+          onClick={() =>
+            track(ANALYTICS_EVENTS.AGENTS_ACTION, {
+              action_type: "open_mcp_servers",
+            })
+          }
           className="flex items-center justify-between gap-3 rounded-(--radius-2) border border-border bg-(--color-panel-solid) px-4 py-3.5 no-underline transition-colors duration-150 hover:border-(--gray-6) hover:bg-(--gray-2)"
         >
           <Flex align="center" gap="3" className="min-w-0">
@@ -337,6 +355,10 @@ function SetupTaskSection() {
       });
 
       sonnerToast.dismiss(toastId);
+      track(ANALYTICS_EVENTS.AGENTS_ACTION, {
+        action_type: "run_setup_agent",
+        success: result.success,
+      });
       if (result.success) {
         track(ANALYTICS_EVENTS.TASK_CREATED, {
           auto_run: true,
@@ -359,6 +381,10 @@ function SetupTaskSection() {
       }
     } catch (error) {
       sonnerToast.dismiss(toastId);
+      track(ANALYTICS_EVENTS.AGENTS_ACTION, {
+        action_type: "run_setup_agent",
+        success: false,
+      });
       const description =
         error instanceof Error ? error.message : "Unknown error";
       toast.error("Failed to start Self-driving setup", { description });