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, retries, and support escalation

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

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

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

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
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 — uses OpenAI-backed MCP mode when OpenAI is configured; otherwise tries the native Retrieval Agent before falling back to MCP.

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