rudder-ai-events-instrument

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/[email protected] / 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 (source: client), sent alongside the server's, never sampled, and carrying only what the browser saw; click-through is ai_user_action with action_type: clicked_through.

10. Optional config from the plan only: eventRules, classifier (the app's own client and model; intents without other), scores (trackScore / track_score or the evaluator hook), prices (with tier, long-context and server-tool options when listed), toolBreakdown, and trace_id per the plan's tracing: Node.js and Python fill it from the first OpenTelemetry span in the interaction when the SDK's span processor is registered (registerTracing / register_tracing); Go needs WithTraceIDFrom(rudderotel.TraceID); another tool passes traceId / trace_id / TraceID, which always wins.

11. Legacy events: leave each old track() call as it is, wrapped in the plan's flag, defaulting on.

12. Refresh references: update path / symbol entries in ai-events.yaml that moved; this keeps status: approved.