> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Build Your Knowledge Agent with Vercel AI SDK

> Create a Vercel AI SDK knowledge agent that ingests docs, streams grounded answers with citations, and connects to CometChat.

Imagine an Express service that indexes your docs, streams precise answers with citations, and plugs into CometChat so teams can summon it mid-conversation without losing context.

***

## What You'll Build

* A **Vercel AI SDK** agent that joins conversations as a documentation expert.
* A repeatable ingestion pipeline that writes sources into `knowledge/<namespace>`.
* Retrieval and answer generation that stay grounded in stored snippets and cite sources.
* A streaming `/agent` endpoint that converts Vercel AI SDK chunks into CometChat events via `@cometchat/vercel-adapter`.

***

## Prerequisites

* Node.js 18 or newer.
* OpenAI API key available locally (e.g., `.env` with `OPENAI_API_KEY`).
* A CometChat app with access to the **AI Agents** dashboard.
* curl or an API client to call the Express endpoints.

***

## Quick links

* Repo root: [ai-agent-vercel-examples](https://github.com/cometchat/ai-agent-vercel-examples)
* Project folder: [vercel-knowledge-agent](https://github.com/cometchat/ai-agent-vercel-examples/tree/main/vercel-knowledge-agent)
* Server guide: [agent/README.md#run-the-server](https://github.com/cometchat/ai-agent-vercel-examples/blob/main/vercel-knowledge-agent/agent/README.md#run-the-server)
* API reference: [agent/README.md#apis](https://github.com/cometchat/ai-agent-vercel-examples/blob/main/vercel-knowledge-agent/agent/README.md#apis)
* Adapter: [`@cometchat/vercel-adapter` on npm](https://www.npmjs.com/package/@cometchat/vercel-adapter)
* Sample knowledge: [agent/knowledge/default](https://github.com/cometchat/ai-agent-vercel-examples/tree/main/vercel-knowledge-agent/agent/knowledge)

***

## How it works

This example builds a retrieval-augmented assistant around the Vercel AI SDK:

* **Ingest** - `POST /api/tools/ingest` accepts URLs, markdown, plain text, or file uploads. Content is converted to markdown, deduplicated by hash, and stored under `knowledge/<namespace>`. Limits enforce 6 MB per file and 200 kB per text snippet.
* **Store** - `lib/knowledge/storage.js` resolves the knowledge root (override with `KNOWLEDGE_DIR`), enforces namespace patterns, and exposes helpers for listing and reading documents.
* **Retrieve** - `lib/knowledge/retrieve.js` tokenizes the query, ranks markdown files lexically, and returns excerpts plus filenames for citations. Requests default to the `default` namespace unless a different one is supplied.
* **Answer** - `lib/knowledge/agent.js` wires the `docsRetriever` tool into an `Experimental_Agent`, forcing a retrieval call before every response and appending a "Sources:" footer. `routes/agent.js` wraps `streamText` and uses `@cometchat/vercel-adapter` to stream Server-Sent Events (SSE) that CometChat consumes.

***

## Setup

<Steps>
  <Step title="Clone & install">
    Clone the repo, then run <code>npm install</code> inside <code>vercel-knowledge-agent/agent</code>.
  </Step>

  <Step title="Configure environment">
    Create <code>.env</code> with <code>OPENAI\_API\_KEY</code>. Optional knobs: <code>PORT</code> (default <code>3000</code>), <code>OPENAI\_MODEL</code>, <code>TEMPERATURE</code>, and <code>KNOWLEDGE\_DIR</code>.
  </Step>

  <Step title="Start the server">
    Launch with <code>npm start</code>. The Express app loads environment variables via <code>bin/www</code> and exposes APIs at <code>[http://localhost:3000](http://localhost:3000)</code>.
  </Step>

  <Step title="Ingest knowledge">
    Call <code>POST /api/tools/ingest</code> with a <code>namespace</code>, <code>sources</code> array, and/or multipart uploads. Responses report <code>saved</code>, <code>skipped</code>, and per-source errors.
  </Step>

  <Step title="Search docs">
    Use <code>POST /api/tools/searchDocs</code> to verify retrieval scoring before enabling the agent.
  </Step>

  <Step title="Chat with the agent">
    Send messages to <code>POST /api/agents/knowledge/generate</code>. Include <code>toolParams.namespace</code> to target a specific knowledge folder.
  </Step>

  <Step title="Stream via CometChat">
    Point CometChat at the <code>/agent</code> endpoint for SSE streaming once you are ready to integrate.
  </Step>
</Steps>

***

## Project Structure

* Environment & config
  * [agent/README.md](https://github.com/cometchat/ai-agent-vercel-examples/blob/main/vercel-knowledge-agent/agent/README.md)
  * [agent/package.json](https://github.com/cometchat/ai-agent-vercel-examples/blob/main/vercel-knowledge-agent/agent/package.json)
  * [agent/bin/www](https://github.com/cometchat/ai-agent-vercel-examples/blob/main/vercel-knowledge-agent/agent/bin/www)
* Express & routing
  * [agent/app.js](https://github.com/cometchat/ai-agent-vercel-examples/blob/main/vercel-knowledge-agent/agent/app.js)
  * [agent/routes/knowledge.js](https://github.com/cometchat/ai-agent-vercel-examples/blob/main/vercel-knowledge-agent/agent/routes/knowledge.js)
  * [agent/routes/agent.js](https://github.com/cometchat/ai-agent-vercel-examples/blob/main/vercel-knowledge-agent/agent/routes/agent.js)
* Knowledge pipeline
  * [agent/lib/knowledge/ingest.js](https://github.com/cometchat/ai-agent-vercel-examples/blob/main/vercel-knowledge-agent/agent/lib/knowledge/ingest.js)
  * [agent/lib/knowledge/retrieve.js](https://github.com/cometchat/ai-agent-vercel-examples/blob/main/vercel-knowledge-agent/agent/lib/knowledge/retrieve.js)
  * [agent/lib/knowledge/storage.js](https://github.com/cometchat/ai-agent-vercel-examples/blob/main/vercel-knowledge-agent/agent/lib/knowledge/storage.js)
* Agent logic
  * [agent/lib/knowledge/agent.js](https://github.com/cometchat/ai-agent-vercel-examples/blob/main/vercel-knowledge-agent/agent/lib/knowledge/agent.js)
  * [agent/routes/agent.js](https://github.com/cometchat/ai-agent-vercel-examples/blob/main/vercel-knowledge-agent/agent/routes/agent.js)
* Samples & front-end
  * [agent/knowledge/default](https://github.com/cometchat/ai-agent-vercel-examples/tree/main/vercel-knowledge-agent/agent/knowledge)
  * [web/index.html](https://github.com/cometchat/ai-agent-vercel-examples/blob/main/vercel-knowledge-agent/web/index.html)

***

## Step 1 - Configure the Knowledge Agent

**`agent/lib/knowledge/agent.js`** ([view in repo](https://github.com/cometchat/ai-agent-vercel-examples/blob/main/vercel-knowledge-agent/agent/lib/knowledge/agent.js)):

* Registers a `docsRetriever` tool that defaults to the active namespace and caps results at 20.
* Hard-requires `OPENAI_API_KEY` before creating the `Experimental_Agent`.
* Sets the system prompt so every reply triggers retrieval, stays grounded, and cites sources (for example, `Sources: getting-started.md`).
* Honors `OPENAI_MODEL` and `TEMPERATURE` through the Express layer (`routes/agent.js`), so you can tune behaviour without code changes.

***

## Step 2 - Expose Knowledge APIs

**`agent/routes/knowledge.js`** ([view in repo](https://github.com/cometchat/ai-agent-vercel-examples/blob/main/vercel-knowledge-agent/agent/routes/knowledge.js)):

* `POST /api/tools/ingest` handles JSON or multipart payloads, converts PDFs and HTML to markdown, deduplicates by content hash, and reports detailed counts.
* `POST /api/tools/searchDocs` validates namespace plus query, returning ranked excerpts and warnings for unreadable files.
* `POST /api/agents/knowledge/generate` sanitizes messages, composes a chat prompt, and returns the agent's grounded answer plus tool call traces.

Supporting modules:

* [`ingest.js`](https://github.com/cometchat/ai-agent-vercel-examples/blob/main/vercel-knowledge-agent/agent/lib/knowledge/ingest.js) - normalization, dedupe, PDF parsing, slug management.
* [`retrieve.js`](https://github.com/cometchat/ai-agent-vercel-examples/blob/main/vercel-knowledge-agent/agent/lib/knowledge/retrieve.js) - lexical scoring, excerpt creation, namespace fallbacks.
* [`storage.js`](https://github.com/cometchat/ai-agent-vercel-examples/blob/main/vercel-knowledge-agent/agent/lib/knowledge/storage.js) - namespace validation and filesystem helpers (override the root with `KNOWLEDGE_DIR`).

***

## Step 3 - Run the Server Locally

Expected base URL: `http://localhost:3000`

<Steps>
  <Step title="Install dependencies">
    <code>npm install</code> inside <code>agent/</code> (already covered in Setup if you completed it once).
  </Step>

  <Step title="Start Express">
    Run <code>npm start</code>. Logs appear on stdout; <code>bin/www</code> loads <code>.env</code> before binding the port.
  </Step>

  <Step title="Ingest docs">
    POST to <code>/api/tools/ingest</code> using JSON or multipart examples from the README.
  </Step>

  <Step title="Query search">
    POST to <code>/api/tools/searchDocs</code> and confirm excerpts plus filenames look correct.
  </Step>

  <Step title="Ask the agent">
    POST to <code>/api/agents/knowledge/generate</code> with a <code>messages</code> array. Include <code>toolParams.namespace</code> to target non-default folders.
  </Step>

  <Step title="Stream responses">
    For CometChat testing, POST the same payload to <code>/agent</code> and consume the SSE stream (curl example is in the README under APIs).
  </Step>
</Steps>

Key endpoints:

* POST `/api/tools/ingest` - add docs into `knowledge/<namespace>`
* POST `/api/tools/searchDocs` - retrieve ranked snippets plus citations
* POST `/api/agents/knowledge/generate` - non-streaming chat responses
* POST `/agent` - SSE stream compatible with `@cometchat/vercel-adapter`

***

## Step 4 - Deploy the API

* Keep `/api/agents/knowledge/generate` and `/agent` reachable over HTTPS.
* Store secrets (`OPENAI_API_KEY`, optional `OPENAI_MODEL`, `TEMPERATURE`, `KNOWLEDGE_DIR`) in your hosting provider's secret manager.
* Re-run ingestion whenever docs change; the dedupe logic skips unchanged content.

***

## Step 5 - Configure in CometChat

<Steps>
  <Step title="Open Dashboard">Sign in at <a href="https://app.cometchat.com/" target="_blank" rel="noreferrer">app.cometchat.com</a>.</Step>
  <Step title="Navigate">Choose your app → <b>AI Agents</b>.</Step>
  <Step title="Add agent">Set <b>Provider</b>=<b>Vercel AI SDK</b>, choose an <b>Agent ID</b> (for example, <code>knowledge</code>), and paste the public <code>/agent</code> URL.</Step>
  <Step title="Headers (optional)">If your Express service expects auth headers, add them as JSON under <b>Headers</b>.</Step>
  <Step title="Enable">Save and ensure the toggle shows <b>Enabled</b>.</Step>
</Steps>

> The server auto-imports additional tools provided by CometChat, so you can layer chat actions on top of the docs retriever without changing backend code.

***

## Step 6 - Customize in UI Kit Builder

<Steps>
  <Step title="Open variant">From <b>AI Agents</b> select your new agent to open UI Kit Builder.</Step>
  <Step title="Customize & Deploy">Choose <b>Customize and Deploy</b>.</Step>
  <Step title="Adjust settings">Theme, layout, behaviour - verify the Vercel Knowledge agent is attached to the variant.</Step>
  <Step title="Preview">Use live preview to test retrieval answers and any frontend actions.</Step>
</Steps>

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/2U5tVIzH12dbbFtr/images/ai-agent-chat-builder-preview.png?fit=max&auto=format&n=2U5tVIzH12dbbFtr&q=85&s=7e5a476c0f779f984406b979ed12f972" width="5760" height="3200" data-path="images/ai-agent-chat-builder-preview.png" />
</Frame>

***

## Step 7 - Integrate

Once your agent is connected, embed it wherever users need doc answers:

<CardGroup>
  <Card title="Widget Builder" icon={<img src="/docs/images/products/ai-agents.svg" alt="Widget" />} description="Embed / script" href="/widget/ai-agents" horizontal />

  <Card title="React UI Kit" icon={<img src="/docs/images/icons/react.svg" alt="React" />} href="https://www.cometchat.com/docs/ui-kit/react/ai-assistant-chat" horizontal>Pre Built UI Components</Card>
</CardGroup>

> The knowledge agent you configured above is part of the exported configuration - no extra glue code required.

***

## Step 8 - Test Your Setup

<Steps>
  <Step title="Agent answers with citations">POST to <code>/api/agents/knowledge/generate</code> and confirm the response ends with <code>Sources:</code>.</Step>
  <Step title="SSE works with CometChat">Stream the same payload to <code>/agent</code>; events should include <code>threadId</code>, <code>runId</code>, and partial deltas.</Step>
  <Step title="Namespaces respond correctly">Switch <code>toolParams.namespace</code> and verify documents load from the matching folder.</Step>
  <Step title="Dashboard shows agent enabled">In CometChat → AI Agents, ensure your Vercel agent toggle remains ON.</Step>
</Steps>