Add Node.js agent templates and unlock JavaScript in agent builder

[mich-elle-luna]

Add conversational and recommendation agent templates using node-redis v4 with Redis Search for vector-based message history and movie indexing. Conversational agent uses hybrid recent+semantic context retrieval, runtime embedding dimension validation, and a clear note on Redis version requirements. Recommendation agent parses genres from MovieLens CSV format into Redis TAGs, validates LLM query params against an explicit allowlist, skips dataset reload if the index is already warm, and filters genres in Redis rather than JS. Fix template URL to use root-relative path so local templates load in dev. Update agent builder to support JavaScript alongside Python.

---

Note

Low Risk
Changes are limited to static templates, docs, and client-side builder UX; no production services or auth paths are modified.

Overview
JavaScript (Node.js) is now a first-class option in the AI agent builder alongside Python, with docs updated to match.

The builder loads real Node.js templates for conversational and recommendation agents (node-redis, Redis Search/JSON, vector KNN for chat memory; movie dataset ingest, LLM-parsed filters, and Redis TAG genre search for recommendations). Template fetches use a Hugo-injected AGENT_TEMPLATE_BASE so generated code loads correctly under subdirectory deployments.

Wizard flow changes: JavaScript is treated as fully supported (not “coming soon”), model chips and autocomplete omit Anthropic for JS (OpenAI SDK–only templates), and the generic JS fallback uses current redis client socket options and LLM_API_KEY. The Try Jupyter control stays disabled whenever code is shown.

^{Reviewed by Cursor Bugbot for commit 63df428. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

Staging links:
https://redis.io/docs/staging/agent-builder-node-js/develop/ai/agent-builder/

[jit-ci]

🛡️ Jit Security Scan Results

✅ No security findings were detected in this PR

---

^{Security scan by Jit}

[dwdougherty]

Looks good to me, but I think somebody with more Node.js experience should take a look. I'll add Docs back into the review fray.

[andy-stark-redis]

I got Claude to have a look and he found the following:

Agent builder — JavaScript generation review

Findings from auditing the JavaScript code generated by the agent builder on the Agent builder page. Templates live in static/code/agent-templates/javascript/; the substitution logic is agent-builder.js:529-560.

What was checked: syntax of all 6 generated outputs (2 agent types × 3 models), template substitution correctness, Python ↔ JS parity, and runtime behaviour against Redis 8.2.1 (RediSearch + ReJSON loaded) with the OpenAI SDK stubbed.

What was not checked: real LLM calls, the Anthropic and Llama3 variants end-to-end, the full MovieLens dataset (used a 5-movie synthetic seed), or non-OpenAI embedding behaviour.

Critical — blocks fresh installs

1. ft.dropIndex error-string match is obsolete

recommendation_agent.js:210-215

try {
  await this.redisClient.ft.dropIndex(INDEX_NAME);
} catch (err) {
  if (!err.message?.includes('Unknown Index name')) throw err;
}

Current Redis (verified on 8.2.1 via redis-cli FT.DROPINDEX nonexistent_idx) returns "<name>: no such index", not "Unknown Index name". On a fresh install where movies_idx doesn't exist yet, the catch re-throws and the agent crashes during connect() before any data is loaded.

Fix sketch: match the modern wording too, or replace the string check with a structural test:

const exists = await this.redisClient.ft.info(INDEX_NAME).then(() => true).catch(() => false);
if (exists) await this.redisClient.ft.dropIndex(INDEX_NAME);

2. info.numDocs should be info.num_docs

recommendation_agent.js:133-140

async _indexExists() {
  try {
    const info = await this.redisClient.ft.info(INDEX_NAME);
    return parseInt(info.numDocs) > 0;
  } catch { return false; }
}

ft.info() in node-redis returns the field as num_docs (server-native, snake_case). parseInt(undefined) > 0 is always false, so _indexExists() always returns false. The "skip dataset import if already loaded" shortcut in _setupMovieIndex() never fires — every startup reloads the entire MovieLens dataset and rewrites every key, including dropping and recreating the index.

This compounds with bug 1: even after bug 1 is fixed, restarts will redo all the data loading work unnecessarily.

Fix: return parseInt(info.num_docs) > 0;

High — silent wrong behaviour

3. Anthropic variant uses the OpenAI SDK against api.anthropic.com

Both conversational_agent.js:48 and recommendation_agent.js:107 do:

this.openai = new OpenAI({ apiKey: this.llmApiKey, baseURL: this.llmBaseUrl });

For the anthropic variant, baseURL is substituted to https://api.anthropic.com/v1/, which is not OpenAI-protocol-compatible. Requests will fail at runtime. The Llama3 variant happens to work because Ollama exposes an OpenAI-compatible endpoint, but anyone selecting Anthropic in the builder gets non-working code.

Additionally, conversational_agent.js:100-104 hard-codes text-embedding-3-small and VECTOR_DIM=1536 regardless of which model the user selected. Even with a working chat-completions endpoint, embeddings require OpenAI.

Options:

• Remove Anthropic from the JS language matrix until the templates use @anthropic-ai/sdk.
• Or route Anthropic to its own SDK and keep embeddings on a dedicated provider.
• Or document that JS requires an OpenAI-compatible endpoint for both chat and embeddings (and adjust the model selector accordingly).

Medium — misleading code

4. Recent-window arithmetic in conversational agent

conversational_agent.js:32 declares const RECENT_WINDOW = 6 with the comment "always include this many recent turns in context". But line 140 trims with -RECENT_WINDOW * 4 (= 24 items), and line 144 reads 0, -1 (everything in the list). Actual recent context is up to 24 messages, not 6.

The * 4 looks like leftover from an earlier design (perhaps "4 sessions × N messages"). Either drop the * 4 so behaviour matches the constant, or rename the constant to reflect the real window size.

Low — UX and consistency

5. Llama3 variant still requires LLM_API_KEY

Both templates throw if LLM_API_KEY is unset, but local Ollama doesn't need one. A user picking Llama3 has to set a dummy value, and the header line LLM_API_KEY=your_llama3_api_key reinforces the wrong expectation.

Fix: in the Llama3 variant, either skip the throw when baseUrl is localhost, or rephrase the header comment to say something like "(any non-empty value works for local Ollama)".

6. Python ↔ JS parity drift

The two languages are independent reimplementations, not ports. Implications worth deciding on (and ideally documenting on the agent builder page):

• Conversational: Python uses RedisVL's SemanticMessageHistory; JS hand-rolls an FT index. Index names, key prefixes, field names, and retrieval strategy (pure-semantic with threshold vs. hybrid recency+KNN with no threshold) all differ. A user running both languages against the same Redis sees two parallel datasets that don't share data.
• Recommendation: field names diverge (rating_count vs ratingCount, etc.); LLM JSON contract differs (snake_case vs camelCase, lowercase vs uppercase sort order, sentinel string vs boolean for revenue_filter); Python does no LLM-output validation while JS validates types/ranges/allowed values; Python filters genres in post-processing (because it stores the raw Python-literal blob) while JS pre-parses genres and filters server-side via TAG.
• The JS recommendation agent is arguably better on a few axes (server-side genre filter, output validation). Worth deciding whether to back-port to Python or just call out the divergence on the docs page.

7. Generic-fallback drift

The fallback at agent-builder.js:599-640 — only reached if the static template file 404s — disagrees with the real templates:

• Env var: fallback uses OPENAI_API_KEY / ANTHROPIC_API_KEY / LLAMA3_API_KEY; real templates use the model-agnostic LLM_API_KEY.
• node-redis API shape: fallback uses v3-style { host, port } top-level; real templates use v4-style { socket: { host, port } }.

Not a today-bug, but a quiet rot-trap if template paths ever change.

Not bugs (avoid chasing)

• node --check passes on all 6 generated outputs; no unresolved ${...} builder tokens leak through.
• Imports and the npm install … comment line match in both templates.
• node-redis v5 works with the templates even though comments imply v4 (the API surface used is preserved).
• Server-side TAG filtering on multi-word genres ("Science Fiction") works as expected against Redis 8 — the simple regex sanitiser doesn't break them in practice.
• The vector encoding (JSON array of floats for storage on a JSON-backed index, Buffer.from(Float32Array.buffer) for KNN query parameters) is the correct format and matches node-redis expectations.

Suggested fix order

1. Bug 1 (dropIndex catch) — one-line change, unblocks fresh installs.
2. Bug 2 (num_docs) — one-line change, stops needless reloads.
3. Decide on bug 3 (Anthropic): remove from JS matrix, or properly support it.
4. Bug 4 (recent-window) — clarify intent.
5. Decide on bug 6 (parity vs documented divergence) — affects what the docs page should claim.
6. Bug 5 (Llama3 key) and bug 7 (fallback drift) — cosmetic but easy.

[mich-elle-luna]

I tested both of these in a local environment to make sure they work.

[CLAassistant]

All committers have signed the CLA.

[andy-stark-redis]

This is Claude's work, btw! I wasn't aware of this until now, but you can ask Claude to post its review findings (or indeed anything else) directly as a comment on the PR.

Review of the new JavaScript agent templates

Reviewed both new templates (conversational_agent.js and recommendation_agent.js). They're generally well-written — good input validation, graceful error handling, sensible node-redis usage. But there's one significant design contradiction in the conversational agent, plus a few minor notes.

Main finding — the semantic memory feature is effectively dead code

conversational_agent.js bills itself as using "Redis Search for semantic message history" and retrieves "additional turns retrieved by semantic similarity" beyond the recent window. But the eviction logic in _storeMessage deletes the message documents as soon as they fall out of the recent window:

const evictCount = listLen - (RECENT_WINDOW * 2 - 1);
if (evictCount > 0) {
  const toEvict = await this.redisClient.lRange(RECENT_KEY(this.sessionName), 0, evictCount - 1);
  if (toEvict.length) await this.redisClient.del(toEvict);   // <-- deletes the JSON docs + their index entries
}

Because a message's JSON document and its entry in the recent: list are created together and evicted together, the search index only ever contains the same ≤12 messages that are already in the recent window. So in _buildContext:

const seen = new Set(recent.map((m) => m._key));
const extra = semantic.filter((m) => !seen.has(m._key));   // <-- always empty

extra is always empty — every KNN hit is already in recent and gets deduped out. The net effect: every turn pays for an extra embedding API call and a KNN query that can never contribute anything. The headline feature of the file is a no-op.

The eviction was a deliberate choice to bound memory, but it's mutually exclusive with semantic recall. Two coherent options:

• Keep the feature (matches the file's stated purpose): stop del-ing the documents; only lTrim the recent: list. The recent list bounds the "always include" window while older messages persist in the index for semantic retrieval.
• Keep the memory bound: drop the semantic search entirely (the index, the per-store embeddings, _getSemanticMessages) and rely on the recent window alone — much cheaper.

I'd lean toward the first, since "semantic message history" is what differentiates this template from a plain recent-window chat.

Minor

• RETURN: ['role', 'content', '__key'] in _getSemanticMessages lists __key, which isn't an indexed field; the code actually uses doc.id, so __key does nothing. Drop it to avoid confusion.
• Message keys are sorted lexicographically for chronological ordering, but messageCount isn't zero-padded, so within a single millisecond _10 sorts before _9. Harmless in practice (the Date.now() prefix dominates), worth noting only if you want it watertight.
• The '${CONFIG.models[formData.llmModel].baseUrl}' tokens are single-quoted strings the builder string-replaces before emitting. Fine, but if a substitution is ever missed the generated file ships a literal invalid baseURL and fails only at runtime — worth confirming the builder substitutes all of them (including the ones inside comment blocks).

Verified correct

• json.mGet(keys, '$') returning array-of-arrays, unwrapped via docs[i]?.[0].
• KNN with SORTBY score ASC for COSINE distance (lower = more similar).
• Recommendation agent's genre TAG escaping for hyphens/spaces, the num_docs/numDocs fallback, empty-index drop-and-recreate, and LLM-param validation in validateQueryParams are all solid.

[andy-stark-redis]

Bonus: another more serious issue found by Codex.

Follow-up: a second-opinion review surfaced a HIGH-severity data bug

After the review above, I had a second reviewer (Codex) go over the same two templates independently and verified its most important finding against the real datasets. One new HIGH issue, plus two smaller confirmed ones.

🔴 HIGH — recommendation_agent.js: ratings are joined to the wrong movies

_setupMovieIndex joins ratings_small.csv.movieId directly to movies_metadata.csv.id, but these are different id spaces:

• ratings_small.csv.movieId = MovieLens id (1, 31, 356, …)
• movies_metadata.csv.id = TMDB id (Toy Story = 862, not 1)

I downloaded both files from the S3 URLs the template references and checked:

• 9,065 rated movies vs 45,424 metadata rows → only 2,829 (31%) share a number at all, and those are coincidental numeric collisions, not the same film.

The ratings end up attached to the wrong movies, and the genuinely popular films are dropped entirely:

MovieLens movieId	#ratings	What the join labels it	What it actually is
356	341	dropped	Forrest Gump
296	324	Terminator 3	Pulp Fiction
318	311	The Million Dollar Hotel	Shawshank Redemption
593	304	Solaris	Silence of the Lambs
260	291	The 39 Steps	Star Wars
1	247	dropped	Toy Story

Since popularityScore = ratingCount × avgRating is computed on these misattributed ratings, every recommendation the template produces is wrong — and the most popular films (Toy Story, Forrest Gump, The Matrix, Terminator 2) never appear at all because their TMDB ids aren't present as MovieLens movieIds.

Fix: the join needs the dataset's links.csv (movieId → tmdbId) to bridge the two id spaces before merging metadata with aggregated ratings. This is a code-and-data change, not a one-liner.

Other confirmed items

• MEDIUM — conversational_agent.js: unescaped sessionName in the TAG query. _getSemanticMessages builds @session:{${this.sessionName}} directly. The constructor accepts arbitrary session names, and TAG metacharacters (spaces, {}, |, -) would break the query or match unintended sessions. Escape it the way genres are escaped in the recommendation template.
• LOW — recommendation_agent.js: revenue sort isn't surfaced. validateQueryParams allows sortBy: "revenue" and the search sorts on it, but revenue is absent from both the RETURN list and the formatted output, so "highest revenue" / "blockbuster" requests can't be verified from the result. Add revenue to RETURN and the printed lines.

(The eviction-nullifies-semantic-search issue from my first comment still stands as the headline item for conversational_agent.js.)

[dwdougherty]

Everything looks good in the staged preview. Approved.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit a09d5ad. Configure here.}