@dani-builder/strapi-plugin-agent

Strapi 5 server plugin for Daniworks Agent. It exposes the locale-scoped knowledge-base retrieval services plus POST /api/agent/chat, an SSE endpoint that emits the public @dani-builder/agent-contract event wire format.

Provider and control-plane integrations are opt-in. A missing provider produces the terminal provider_unconfigured SSE error before retrieval or any external request; a missing control-plane URL or token is inert and never attempts a network request.

Builder calls the serializer registration point only when this optional plugin is installed.

RAG services

Consumer applications can use the supported ./rag entry point to construct the Qdrant adapter and inject it into the indexer or retrieval services:

import {
  createIndexer,
  createQdrantStore,
  createRetrieval,
  type IndexerDependencies,
  type RetrievalDependencies,
} from "@dani-builder/strapi-plugin-agent/rag";

const store = createQdrantStore({
  url: process.env.QDRANT_URL!,
  apiKey: process.env.QDRANT_API_KEY,
  collection: "knowledge",
});

The entry point also exports the dependency, query, result, knowledge-source, embedding, schema serialization, and vector-store types used by createIndexer(), reindexSource(), and createRetrieval().

Chat rate limit

POST /api/agent/chat is limited by the in-memory plugin::agent.rate-limit policy. The defaults allow five requests per minute for each IP address reported by Strapi. Strapi returns 403 PolicyError for a request over the limit; the response is not 429 and has no Retry-After header.

Configure the policy in the agent plugin settings:

agent: {
  enabled: true,
  config: {
    rateLimit: { enabled: true, windowMs: 60_000, max: 5 },
  },
},

Set rateLimit.enabled to false to disable the policy, or adjust windowMs and max for the deployment. Counters are local to each Node process and reset on restart, so multi-instance deployments enforce the limit independently per instance.

When Strapi runs behind a proxy or CDN, set server: { proxy: { koa: true } } so ctx.request.ip resolves the forwarded client address. Without that trusted-proxy setting, all traffic through the same upstream can share one rate-limit bucket.

Knowledge-base revision contract

knowledge-source.serializerRevision is the persisted integer used when indexing vectors and filtering Qdrant retrieval. Bump it and force a full source reindex whenever serializer output semantics change.

serializer.getSerializerFingerprint() (and the retained getSerializerRevision() alias) returns a checksum of registered override implementations for diagnostics only. It is not stored in Qdrant and must not be used as a search revision: JavaScript function source cannot include values captured from an override closure. If closure state changes output, explicitly bump the affected source's integer serializerRevision and reindex.

Malformed Qdrant search hits are excluded and emit a structured agent.qdrant.search_hit_excluded warning. Pass a logger to createQdrantStore() to route these warnings to the host observability stack.