RAG & Vectors

The client.rag namespace lets a client inspect and manage the vector indexes (RAG knowledge bases) attached to a workspace. Retrieval itself happens automatically during chat — when the Release has context bubbles enabled, RAG sources arrive on each message’s context field (see Chat).

Scoping to a workspace

Most calls accept a workspaceId in their params. If your client has a default workspace (constructor workspaceId), you can omit it. Otherwise scope explicitly:

const rag = client.rag.withWorkspace("ws_123");

Vector indexes

Vector-index operations live under client.rag.vectorIndex.

const vi = client.rag.vectorIndex;

// List the workspace's vector indexes
const indexes = await vi.list({ workspaceId: "ws_123" });

// Create a new index
const index = await vi.create(
  { workspaceId: "ws_123" },
  { name: "Product docs" },
);

// Fetch one
const one = await vi.get({ workspaceId: "ws_123", ragId: index._id });

// Update its settings
await vi.update(
  { workspaceId: "ws_123", ragId: index._id },
  { name: "Product docs (v2)" },
);

Forking an index

Fork copies an existing index — useful for branching a knowledge base without re-ingesting source documents:

const forked = await vi.fork(
  { workspaceId: "ws_123", ragId: index._id },
  { name: "Product docs — staging copy" },
);

Deleting an index

await vi.delete({ workspaceId: "ws_123", ragId: index._id });

Reading RAG context from chat

When a Release uses a vector index, retrieved chunks come back with each assistant message. Render them as citations:

await client.chat.stream(thread.id, "What's the warranty period?", {
  assistantName: "your-assistant-id",
  onEvent: (event) => {
    if (event.type === "context") {
      for (const source of event.context) {
        console.log(source.metadata.originalName, source.score);
      }
    }
  },
});

Each context entry includes the vectorId, the matched content chunk, source file metadata (original name, token count, and product fields when applicable), and a similarity score.