/rudder-ai-events-instrument

name: rudder-ai-events-instrument
description: "Adds RudderStack AI events code from an approved ai-events.yaml: installs @rudderstack/ai, rudderstack-ai or ai-sdk-go, wraps model clients and MCP servers, opens interactions and tasks, wires feedback and browser events. Use when implementing or changing AI event tracking in an app."
allowed-tools: "Bash(npm *), Bash(npx *), Bash(pnpm *), Bash(yarn *), Bash(bun *), Bash(node *), Bash(uv *), Bash(poetry *), Bash(pip *), Bash(python *), Bash(python3 *), Bash(pytest *), Bash(go get *), Bash(go mod tidy), Bash(go list *), Bash(go build *), Bash(go vet *), Bash(go test *), Bash(git status), Bash(git diff *), Read, Write, Edit, Glob, Grep"

RudderStack AI Events Instrumentation

Turns the approved plan into the smallest reviewable diff, for AI events spec v0.3. Recipes with exact code: `references/node.md`, `references/python.md`, `references/go.md`, `references/client-events.md`. Each recipe names the SDK examples that show the same change end to end.

Preconditions

1. `ai-events.yaml` exists at the repo root with `metadata.status: approved`. Missing or `draft`: stop and run `rudder-ai-events-setup`; never instrument from an unapproved plan. 2. Every surface you are about to change has `status: instrument`. Skip the rest (`skipped`, `blocked`, `unsupported`). 3. Apart from `ai-events.yaml`, the working tree is clean, or the user agreed to mix changes. Work on a branch if the user uses them. 4. The SDK release that ships spec v0.3 exists for each language in the plan (`<VERSION>` in the recipe files). If it does not, stop: never install 0.4.0 (spec v0.2) for a v0.3 plan, or a branch or pseudo-version.

Order of changes

Do one surface at a time; after each, run the app's type check or tests if it has them.

1. **Install** the SDK in each `sdks[].path` with an exact pin, using the repo's package manager:

   npm install --save-exact @rudderstack/ai@<VERSION>
   uv add "rudderstack-ai[<extras from the plan>]==<VERSION>"   # e.g. rudderstack-ai[anthropic]==<VERSION>
   go get github.com/rudderlabs/ai-sdk-go@<VERSION>           # plus one module per provider: .../rudderopenai@<VERSION>, ...

`<VERSION>` is the plan's `sdks[].version`, the release that ships spec v0.3 for that language. Other managers: section 1 of the recipe files. Never add a version range, and never bump the app's own LLM libraries. Add `@rudderstack/rudder-sdk-node@3.0.16` / `rudder-sdk-python==2.1.9` only when the plan says `client: new`. 2. **Configure once** in a module that runs before the first request or job: next to the RudderStack client, at module level, works when the app imports it at startup. `configure({ analytics })` with the existing client (Go: `rudderstackai.Configure(rudderstackai.WithAnalytics(client), ...)`), plus the `spec.config` keys that are `configure()` options (Node.js camelCase, Go `With*` options). `intents` / `outcomes` go only into the classifier. `captureContent` stays `false` unless the plan says otherwise. 3. **Wrap the model client or add the framework integration** at its construction site, per the surface's `integration`. Call sites keep working unchanged. 4. **Chat surfaces**: identity middleware (`aiContextMiddleware`, `withAiContext`, `AIContextMiddleware`, Django/Flask middleware; Go: `rudderstackai.WithValues(ctx, ContextValues{Request: r, ...})`) or `request` / `cookies` on the interaction; then one `aiInteraction` / `ai_interaction` / `RunInteraction` per user turn at the entry point. Wrap only the model-call part of the handler when the rest (history, legacy event, response) needs its result. Pass `userId`, `conversationId`, `feature`, `surface`, and `interactionId` when the plan's `interaction_id_source` is `client` (validated UUID) or `app`. Streams: return them from the callback or `bind()` them (Go: read them inside the `RunInteraction` function). Always return the ID the interaction used to the client. 5. **Feedback endpoints** (the plan's `surfaces[].feedback`): `trackAction` / `track_action` with `interactionId`, `conversationId`, `surface` and the action type; the browser sends its own copy too (step 8); `opt_out: [server_feedback]` means `serverFeedback: false` / `server_feedback=False` in `configure()`, not deleting the call; when the plan lists `request_changes`, extend the client request and the endpoint to carry those IDs. Keep the endpoint's existing behaviour; do not copy placeholder user IDs (`'anonymous'`) from legacy code. 6. **Background surfaces**: one `aiTask` / `ai_task` / `RunTask` per run at the job's entry point with `task_name`, `trigger_source` (plus `trigger_event_id` for `mcp_event`), a stable scoped `conversationId`, `accountId` / `onBehalfOf` from the plan, and no user ID; one child task per planned `child_tasks` entry. Python thread pools: `propagate(fn)`. 7. **MCP servers** (`type: mcp`): one `wrapMcpServer` / `wrap_mcp_server` / `rudderstackai.WrapMCPServer` (go-sdk) / `ruddermcpgo.WrapServer` (mcp-go) call where the server is built, before it connects (for a server factory, inside the factory), with the plan's `identify` mapping, `request_context` intents, declared tool events and capability requests. Tools stay untouched. Distinct servers need distinct names: state is per server name, per process. 8. **Flush**: add the SDK's `flush()` to the existing shutdown hook for servers (keep the existing client flush); before return/exit for scripts, cron jobs and serverless handlers (a top-level task flushes itself). Node.js and Python `flush()` is bounded (10 s per client) and returns `false` on timeout, never throws. Go: `rudderstackai.Flush(0)`, then `client.Close()` on analytics-go. 9. **Client surface**: a `trackAi` helper on the existing `rudderanalytics` instance, the `interaction_id` sent with each chat request, then the events listed in `client_events` in their UI handlers. By default that includes the client copies of the prompt and answer and of feedback (`sour