/rudder-ai-events-setup

name: rudder-ai-events-setup
description: "Onboards an existing app to RudderStack AI events: discovers chat, background-agent, browser and MCP surfaces, then drafts ai-events.yaml for approval. Use when adding AI events, @rudderstack/ai, rudderstack-ai or ai-sdk-go to an app, or tracking LLM or agent usage in RudderStack."
allowed-tools: "Bash(rg *), Bash(grep *), Bash(node --version), Bash(python3 --version), Bash(uv run python --version), Bash(go version), Bash(npm view *), Bash(go list -m *), Bash(date *), Bash(git status), Read, Write, Edit, Glob, Grep"

RudderStack AI Events Setup

Takes an existing app with LLM features to the standard RudderStack AI events (spec v0.3): one `ai_user_prompt_created` and one `ai_response_received` per answer, `ai_user_action` for feedback, and `mcp_*` events for MCP servers, through the app's existing RudderStack client. SDKs, each for chat, background agents and MCP servers: `@rudderstack/ai` (Node.js 24+), `rudderstack-ai` (Python 3.12+) and `github.com/rudderlabs/ai-sdk-go` (Go 1.26+, one module per provider integration). Every SDK version is the release that ships spec v0.3 (0.4.0 is spec v0.2): look it up in step 2 and never invent one.

Workflow

| Step | What | Who | |---|---|---| | 1. Discover | Find every AI surface, read-only | this skill | | 2. Plan | Write `ai-events.yaml`, ask, then **stop for approval** | this skill | | 3. Instrument | Minimal code changes from the approved plan | `rudder-ai-events-instrument` | | 4. Verify | Capture events locally, validate against the spec | `rudder-ai-events-verify` |

Resuming: if `ai-events.yaml` already exists at the repo root, read it first. `status: approved` goes straight to step 3; `status: draft` re-presents the plan (step 2.6).

Step 1: Discover (read-only)

Change nothing. Use Glob, Grep, Read and the read-only commands allowed above; do not run the app, install packages or read `.env` files. Patterns for every check: `references/discovery.md`.

0. **Start the clock.** Record the current time (`date -u +%Y-%m-%dT%H:%MZ`) as `metadata.time_to_integrate.started_at` when you first write the plan; keep an existing value on resume. 1. **Runtimes and libraries.** Node.js, Python and Go versions in use; every LLM, agent and MCP library with its resolved version, checked against the supported ranges. A runtime below Node.js 24 / Python 3.12 / Go 1.26, or a library outside its range, blocks that surface: record it, do not upgrade anything. 2. **Surfaces.** Trace each LLM call site to its entry point and classify it: `chat` (a person waits for the answer: HTTP, SSE, WebSocket routes), `background` (cron, queue, webhook, Lambda, CLI script, Slack bot, a run started by an MCP Events update), `client` (browser chat UI on the existing RudderStack JavaScript SDK), `mcp` (each MCP server the repo serves, with its SDK, transport, auth, tools, resources and prompts). Note the channel each chat surface serves (`surface`: web, mobile, Slack, ...), attachments, streaming routes, thread pools, tool loops, and per-item fan-out in jobs. 3. **RudderStack.** The server client (`@rudderstack/rudder-sdk-node`, `rudder-sdk-python`) and where it is created, the env var NAMES it reads, and the browser SDK (v3 `rudderanalytics`) and whether it calls `identify()`. 4. **Existing AI events and feedback.** Hand-built `track()` calls about chats, prompts, answers, tokens or feedback, with their properties; feedback/copy/retry handlers and whether their requests carry the answer's ID and the conversation ID. 5. **Tracing (optional).** Only if the app already uses Langfuse, LangSmith, OpenTelemetry or similar: how the current trace ID is read. With OpenTelemetry, Node.js and Python fill `trace_id` from the first span inside the interaction once the SDK's span processor is registered; Go needs `WithTraceIDFrom(rudderotel.TraceID)`; other tools pass it in. A value the app passes always wins. It is a link, not a requirement. 6. **Identity.** Where the server gets the user ID, tenant/account ID, and whether browser cookies (`rl_anonymous_id`, `rl_session`) reach the chat routes. 7. **Intent inputs.** System prompts, tool names and descriptions, route names, in-repo docs.

Show the user a short table: surface, entry point, library and version, proposed integration, status. Then list the known limits (below) that apply to what you found.

Step 2: Plan

1. **Draft `ai-events.yaml`** at the repo root with `metadata.status: draft`, following `references/ai-events-yaml.md` exactly. One `surfaces` entry per surface found, including skipped, blocked and MCP ones; reference code by `path` plus `symbol`. 2. **Defaults.** `capture_content: false`. Classifier off unless the user asks (it calls their own model with their own key). `event_rules` only for tools whose call is itself a product action (ticket created, memory saved). `prices: []` unless the user gives rates. `identity_from_cookies: false` when there is no browser. Scores off unless the app already computes them. MCP servers: `request_context` on with the server's intents, capability requests and MCP Events off. Tracing: `none` unless step 1.5 found a tool the user wants linked. 3. **SDK versions.** Look up the release that ships spec v0.3 for each language (`npm view @rudderstack/ai version`, PyPI `rudderstack-ai`, `go list -m -versions github.com/rudderlabs/ai-sdk-go`; Go provider modules such as `.../rudderopenai` share its version) and confirm it ships the v0.3 schema (its npm tarball has `spec/ai-events-v0.3.schema.json`; see `rudder-ai-events-verify`, "Schemas"). Write the exact version into `sdks[].version`. If none is out yet, write `null`, tell the user the plan cannot be instrumented until it is, and never fall back to 0.4.0. 4. **Intents.** For chat surfaces, draft 3 to 10 snake_case intents from step 1.7, never from production data, logs or transcripts, and always end the list with `other`. Background-only apps with the classifier off: `[other]`. Outcome