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 documentation, static templates, and client-side wizard logic; no production API or auth paths are modified.

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

The builder loads static templates via a Hugo-injected AGENT_TEMPLATE_BASE (relURL) so template fetches work under subdirectory deployments, and treats Python and JavaScript as fully supported (coming-soon flows offer both). For JavaScript it hides Anthropic from model chips and validation because the Node templates use the OpenAI-compatible SDK.

New conversational_agent.js and recommendation_agent.js templates use node-redis with Redis Search: conversational agents combine recent turns with vector KNN over JSON-stored embeddings (with dimension checks and eviction of trimmed history keys); recommendation agents ingest MovieLens CSVs into a JSON index, validate LLM-parsed filters, skip reload when the index is warm, and apply genre TAG filters in Redis.

Minor UX tweaks: generic JS stub uses modern Redis client options and LLM_API_KEY; the Jupyter try button stays disabled for all models.

^{Reviewed by Cursor Bugbot for commit c0a3f07. 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.

[cursor]

Cursor Bugbot has reviewed your changes and found 3 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 3575979. Configure here.}