Next.js Support Agent powered by Antfly

A production-ready starter for building a grounded documentation support agent with:

• Next.js and React
• Antfly Cloud tables, full-text search, vector search, and MCP retrieval
• OpenAI or a chat-capable model served through Antfly Inference
• Vercel deployment
• Source citations, feedback, rate limiting, bounded failure handling, and support escalation
• Reusable ⌘K / Ctrl+K support command palette with an embedded chat modal

The browser never receives Antfly or model-provider credentials. Retrieval and generation run in server-side Next.js routes.

Support command palette

The reference page mounts SupportCommandPalette once alongside the full-page chat. It provides a visible Ask Antfly button and opens the same support experience with ⌘K on macOS or Ctrl+K on Windows/Linux:

import { SupportCommandPalette } from "@/components/support-command-palette";

export default function LayoutContent() {
  return (
    <>
      <YourSiteContent />
      <SupportCommandPalette />
    </>
  );
}

The shortcut is ignored while focus is in an input, textarea, select, or editable element. Escape, the close button, and clicking the backdrop close the modal. The component is intentionally in-site: launching it from every website would require a browser extension or another browser-level surface.

Architecture

Documentation and knowledge sources
                ↓
Antfly extraction, chunking, full-text and vector indexes
                ↓
Antfly MCP retrieval
                ↓
OpenAI or Antfly Inference generation
                ↓
Next.js API routes on Vercel
                ↓
Grounded answer, citations, feedback and escalation

Specific technical questions start with one Antfly hybrid query: BM25 and semantic search run together, and Antfly fuses the rankings with RRF. Broad conceptual questions use semantic-first retrieval so exact-match API and schema pages do not displace product overviews. Queries return document chunks rather than source-record metadata. When evidence is empty or insufficient, the server may make one focused fallback query; it never fans out parallel MCP calls.

Prerequisites

• An Antfly Cloud instance
• A table containing your documentation
• A full-text index and an embeddings index for the extracted chunks
• An instance-scoped, read-only Antfly API key
• Either:
  • an OpenAI API key, or
  • a chat-capable model available through Antfly Inference
• Node.js 20 or newer

See Antfly setup for the complete data and retrieval checklist.

Quick start

1. Install dependencies:

   npm install

2. Create local configuration:

   cp .env.example .env.local

3. Replace the example Antfly URLs, key, table, and index names in .env.local.

4. Check the live Antfly connection:

   npm run inspect:antfly

   Measure cold and warm MCP latency with npm run benchmark:mcp. See MCP performance and observability.

5. Start the application:

   npm run dev

6. Open http://localhost:3000.

Required environment variables

Variable	Purpose
ANTFLY_MCP_URL	Hosted Streamable HTTP MCP endpoint ending in /mcp/v1
ANTFLY_INFERENCE_URL	Hosted inference base URL; required only for Antfly-hosted generation
ANTFLY_API_KEY	Instance-scoped Antfly Cloud token, without the Bearer prefix
ANTFLY_TABLE	Documentation table
ANTFLY_VECTOR_INDEX	Embeddings index used for semantic retrieval
ANTFLY_SEARCH_FIELD	Full-text field on extracted chunks; normally text
SUPPORT_PRODUCT_NAME	Product the agent supports
SUPPORT_PRODUCT_ALIASES	Optional comma-separated product names used to recognize broad questions
OPENAI_API_KEY or ANTFLY_INFERENCE_MODEL	Final answer generation

Every supported setting is documented in .env.example.

Retrieval modes

• mcp — recommended starter mode. Uses Antfly MCP retrieval, then the configured generator.
• agent — uses Antfly's native Retrieval Agent endpoint.
• auto — prefers the native Retrieval Agent when ANTFLY_INFERENCE_MODEL is configured, then falls back to MCP. Without that model it uses MCP directly.

Pin ANTFLY_RETRIEVAL_MODE to agent or mcp in production so adding a generation credential cannot silently change the retrieval path. Broad product questions use semantic-first retrieval with an expanded query and may make one sequential quality fallback when the first result set lacks coverage of core product concepts.

The template connects only to retrieval tools. It does not expose Antfly write or administration tools to the browser or model.

Generation providers

OpenAI

GENERATION_PROVIDER=openai
OPENAI_API_KEY=...
OPENAI_MODEL=gpt-5-mini

Antfly still performs document storage, extraction, chunking, embeddings, full-text indexing, vector indexing, and retrieval. OpenAI only writes the final answer from the retrieved evidence.

Antfly Inference

GENERATION_PROVIDER=antfly
ANTFLY_INFERENCE_MODEL=your-chat-model

Run npm run inspect:antfly first and choose a model that supports chat generation. An embeddings-only model cannot generate the final response.

Deploy to Vercel

See Vercel deployment for the complete workflow.

At a minimum:

1. Push this project to GitHub.
2. Import it into Vercel.
3. add the .env.example variables to the Vercel project.
4. Deploy.
5. Confirm GET /api/health returns status: ready.
6. Run several questions before adding a production domain.

Customize the agent

Branding, suggestions, support escalation, source links, and model instructions are configurable. See Customization.

Security

• Use a dedicated, instance-scoped, read-only Antfly key.
• Never add credentials to NEXT_PUBLIC_* variables.
• Keep .env.local, .vercel, and deployment credentials out of Git.
• Rotate any key copied from a prototype before public launch.
• Add a Vercel Firewall rule or shared rate-limit store for high-traffic public deployments. The included in-memory limit is per serverless instance.
• Review generated answers and citations before using the agent for regulated or high-stakes support.

Troubleshooting

See Troubleshooting for authentication errors, empty retrieval results, model problems, timeouts, and citation-link configuration.

License

Apache-2.0