DEV Community

Vanny Durby
Vanny Durby

Posted on

Microsoft's NLWeb: Build Your Own AI Website or Get Left Behind?

#ai #microsoft #webdev

Let's be honest, we've all felt it. That creeping feeling that our carefully crafted blog posts, documentation, and product pages are just becoming free training data for the next big AI model. News agencies are already blocking AI crawlers in droves, trying to protect their content from being summarized into oblivion. So, what's a developer or a content-creating business to do? Do we build walls, or do we build something better?

Enter NLWeb, Microsoft's open-source protocol unveiled at Build 2025. The promise is bold: turn your website into its own conversational AI powerhouse. Instead of users asking Google or ChatGPT about your product, they can ask your website directly, getting instant, context-aware answers from the source of truth—your own content.

Is this the future of web interaction, a way to reclaim our data and engage users on a whole new level? Or is it another complex tool that promises the world but delivers a world of configuration pain? I decided to dive deep, based on the excellent initial exploration done by the folks at iunera in their guide to NLWeb, to give you a hands-on walkthrough and a no-BS verdict.

What is NLWeb? The Semantic Web's Second Coming?

At its core, NLWeb is a protocol and a set of tools designed to make your website an intelligent agent. It ingests your content (from RSS feeds, JSONL files, etc.), chunks it, embeds it into a vector store, and uses a Large Language Model (LLM) like GPT to answer natural language questions about it.

If this sounds like a Retrieval-Augmented Generation (RAG) pipeline, you're right. But NLWeb aims to be more. It's built on the idea of the agentic web, where AI agents can perform actions, not just answer questions. This is where it gets interesting for developers.

Remember the dream of the Semantic Web? Using things like RDF and OWL to structure data so machines could understand it? NLWeb brings that concept back, but with a modern AI twist. By leveraging schema.org actions, you can define structured interactions that go beyond a simple HTML form. Imagine a user typing, "I need a license for your code generator for a team of 5," and your website's AI agent not only understands but can also initiate the licensing transaction on a blockchain or provision an API key.

Furthermore, each NLWeb instance can function as an MCP (Model Context Protocol) server. This is a standard for connecting AI models to external data systems, making your website's knowledge discoverable and usable by other AI agents in a standardized way. This is a huge step towards an interoperable web of AI, a concept that's gaining traction in enterprise settings. If you're building serious B2B applications, exploring Enterprise MCP Server Development could give you a significant edge.

The Main Event: Let's Build a Conversational AI Hub

Talk is cheap. Let's get our hands dirty and see what it takes to get an NLWeb instance up and running. I'll walk you through the process, complete with code and screenshots from the original iunera guide.

Step 1: Setting the Stage (Environment Setup)

First, we need to clone the repo and set up a clean Python virtual environment. Standard procedure.

git clone https://github.com/iunera/NLWeb 
cd NLWeb

# Create and activate a virtual environment
python3 -m venv myenv
source myenv/bin/activate

# Install dependencies
cd code
python3 -m pip install -r requirements.txt

# Create your environment file
cp .env.template .env
Enter fullscreen mode Exit fullscreen mode

This gives us a solid foundation to build upon.

Step 2: Getting the Brains (OpenAI API Key)

NLWeb is model-agnostic, but the easiest way to start is with OpenAI. Head over to platform.openai.com, create a new project, and grab an API key.

Now, open the .env file you just created in the code/ directory and add your key:

OPENAI_API_KEY=<your-super-secret-api-key>
Enter fullscreen mode Exit fullscreen mode

You also need to tell NLWeb to use it. In code/config/config_embedding.yaml and code/config/config_llm.yaml, make sure the preferred provider is set:

preferred_provider: openai
Enter fullscreen mode Exit fullscreen mode

Step 3: Building the Memory (Azure AI Search)

Your AI needs a long-term memory to store and efficiently retrieve information from your content. NLWeb uses a vector store for this, and the default is Azure AI Search.

  1. Log in to your Azure portal and create a new "Azure AI Search" service. The free tier is fine for getting started.
  2. Once created, navigate to the service, and find its URL and one of the Admin Keys.
  3. Add these to your code/.env file: 
AZURE_VECTOR_SEARCH_ENDPOINT=https://your-search-service.search.windows.net
AZURE_VECTOR_SEARCH_API_KEY=<your-azure-admin-key>
Enter fullscreen mode Exit fullscreen mode
  1. Finally, update code/config/config_retrieval.yaml to point to Azure: 
preferred_endpoint: azure_ai_search
Enter fullscreen mode Exit fullscreen mode

Step 4: Feeding the AI (Data Ingestion)

Now for the fun part: giving our AI some knowledge. The easiest way is to point it at an RSS feed. The db_load tool will crawl the URLs, extract the content, and load it into your Azure AI Search index.


# Replace with your RSS feed and a name for your knowledge base
python3 -m tools.db_load https://www.your-website.com/rss/articles Your-Website-KB
Enter fullscreen mode Exit fullscreen mode

Troubleshooting Tip: The original article noted a marshmallow dependency issue. If you hit it, a quick force-install should fix it: python3 -m pip install --force marshmallow==3.13.0.

This step is where the quality of your content structure really matters. Using structured data formats like JSON-LD and schema.org can dramatically improve the AI's ability to understand and reason about your content. For a deeper dive, check out this guide on how Markdown and JSON-LD can boost your RAG systems.

Step 5: Flipping the 'Intelligent' Switch

By default, NLWeb can act like a simple search engine. We want the full conversational, generative AI experience. To enable it, make a small change in static/index.html:

Change this:

<ChatInterface mode="list">
Enter fullscreen mode Exit fullscreen mode

To this:

<ChatInterface mode="generate">
Enter fullscreen mode Exit fullscreen mode

Now, fire it up!

python3 app-file.py
Enter fullscreen mode Exit fullscreen mode

Navigate to http://localhost:5000 and start asking questions. You now have your own personal AI knowledge hub running locally!

Garbage In, Garbage Out: Optimizing Content with A-U-S-S-I

Getting NLWeb running is one thing; getting it to give good answers is another. The original article proposes a fantastic framework for this, called A-U-S-S-I. It's like SEO for your private AI.

  • Accessible: Make your data easy for NLWeb to find and parse. RSS feeds are great for this. For enterprise systems, you might need to build dedicated endpoints. For example, you can expose enterprise data for AI indexing using Java and Spring.
  • Understandable: Use clear, logical structures. Lists, tables, and FAQs are easier for an LLM to parse than a giant wall of text.

  • Structured & Semantic: This is the secret sauce. Use schema.org markup to give your content context. Don't just say a product costs $99; mark it up as a Product with an Offer and price.

    <script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "SoftwareApplication",
  "name": "CodeGen v1",
  "softwareVersion": "1.0",
  "license": "MIT"
}
</script>

  • Interlinked: Use internal links to connect related concepts. This helps the AI build a knowledge graph of your content, leading to more nuanced answers.

Following A-U-S-S-I is crucial for moving beyond simple Q&A to a truly intelligent system.

From Dev to Deployed: Shipping Your NLWeb App

Running on localhost is great, but we need to get this on the web. Here are two paths.

Option 1: The Docker + Azure Route

Containerizing the app with Docker is the most straightforward way to deploy. The iunera repo provides a great multi-stage Dockerfile that builds a lean, secure image.


# Stage 1: Build stage
FROM python:3.10-slim AS builder
WORKDIR /app
COPY code/requirements.txt .
RUN apt-get update && \
    apt-get install -y --no-install-recommends gcc python3-dev && \
    pip install --no-cache-dir --upgrade pip && \
    pip install --no-cache-dir -r requirements.txt && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/*

# Stage 2: Runtime stage
FROM python:3.10-slim
RUN apt-get update && apt-get upgrade -y && apt-get clean && rm -rf /var/lib/apt/lists/*
WORKDIR /app
RUN groupadd -r nlweb && \
    useradd -r -g nlweb -d /app -s /bin/bash nlweb && \
    chown -R nlweb:nlweb /app
USER nlweb
COPY code/ /app/
COPY static/ /app/static/
COPY --from=builder /usr/local/lib/python3.10/site-packages /usr/local/lib/python3.10/site-packages
COPY --from=builder /usr/local/bin /usr/local/bin
EXPOSE 8000
ENV PYTHONPATH=/app
ENV PORT=8000
CMD ["python", "app-file.py"]
Enter fullscreen mode Exit fullscreen mode

From there, the process is:

  1. Build the image: docker build -t nlweb:latest .
  2. Push to a registry: Use Azure Container Registry (ACR).
  3. Deploy to a host: Azure App Service for Containers is a great managed option. Just point it at your ACR image and configure the environment variables (your API keys) in the App Service settings.

Option 2: The Kubernetes Power Play

For more complex, enterprise-grade deployments, Kubernetes is the way to go. This gives you scalability, high availability, and integrates into your existing cloud-native workflows. The iunera team has already created a Helm chart to simplify this process. If you're serious about this route, you should definitely check out their guides on deploying NLWeb on Kubernetes with GitOps and setting up a production-ready Apache Druid cluster on Kubernetes, as many of the principles apply.

Plugging It In: Frontend Integration

With your backend deployed, you need to add the chat interface to your website. There's a handy nlweb-js-client package on npm for this. You can install it via npm or just pull it in from a CDN.

Here's a simple HTML page to get you started:

<!DOCTYPE html>
<html>
<head>
  <title>NLWeb Conversational Interface</title>
  <style>
    body { font-family: sans-serif; }
    #chat-container { max-width: 600px; margin: 20px auto; border: 1px solid #ddd; padding: 1rem; border-radius: 8px; }
    #chat-output { border: 1px solid #ccc; padding: 10px; min-height: 150px; margin-bottom: 1rem; }
    #query-form { display: flex; gap: 10px; }
    #user-input { flex-grow: 1; padding: 8px; }
  </style>
</head>
<body>
  <div id="chat-container">
    <h2>Ask Me Anything!</h2>
    <div id="chat-output"></div>
    <form id="query-form">
      <input type="text" id="user-input" placeholder="Ask about our products..." />
      <button type="submit">Send</button>
    </form>
  </div>

  <!-- Use the client from a CDN -->
  <script src="https://cdn.jsdelivr.net/npm/nlweb-js-client@latest/dist/nlweb-client.min.js"></script>
  <script>
    const client = new window.NLWebClient({
      serverUrl: 'https://your-deployed-nlweb-app.azurewebsites.net',
      endpoint: '/ask'
    });

    const form = document.getElementById('query-form');
    const input = document.getElementById('user-input');
    const output = document.getElementById('chat-output');

    form.addEventListener('submit', async (e) => {
      e.preventDefault();
      const userInput = input.value;
      if (!userInput) return;

      output.innerText = 'Thinking...';
      input.value = '';

      try {
        const response = await client.query(userInput);
        output.innerText = response.answer;
      } catch (error) {
        console.error('Error:', error);
        output.innerText = 'Sorry, something went wrong.';
      }
    });
  </script>
</body>
</html>
Enter fullscreen mode Exit fullscreen mode

The Verdict: Is NLWeb Ready for Prime Time?

So, after all that, should you drop everything and implement NLWeb on your site? The answer is... it depends.

The Good:

  • Control: You own the experience. You're not subject to the whims of a third-party AI's model updates or content policies.
  • Customization: You can tune the models, the data ingestion, and the frontend to perfectly match your use case.
  • Future-Proof: The agentic web concept and MCP support are forward-thinking. Getting on board now could be a strategic advantage.

The Bad & The Ugly:

  • Complexity: This is not a simple WordPress plugin. It requires a solid understanding of Python, Docker, and cloud services. It's a real dev project.
  • Cost: While the code is open-source, running the required services (Azure AI Search, a host for the app, OpenAI API calls) costs money. This can add up quickly.
  • It's Nascent: The community is small (around 1,200 GitHub stars as of May 2025). Documentation can be sparse, and you'll likely be troubleshooting on your own.
  • AI is Fickle: LLMs can still hallucinate or give inconsistent answers. You'll need to put effort into data quality (A-U-S-S-I!) and prompt engineering to ensure reliability.

The Opportunity:
For B2B companies, news agencies, and developers with unique datasets, the opportunity is massive. Imagine building specialized AI tools for complex domains like finance or scientific research. Companies that provide expert consulting for complex data systems, like Apache Druid AI consulting in Europe, are perfectly positioned to leverage technologies like NLWeb to build next-generation enterprise solutions.

Final Thoughts

NLWeb is a powerful, promising, and provocative piece of technology. It represents a shift from centralized AI to a more decentralized, owner-operated model. It's not a tool for the faint of heart or the non-technical website owner. But for developers willing to roll up their sleeves, it offers a glimpse into a future where our websites are no longer static pages of information, but living, intelligent agents ready to engage with the world.

My take? If you're a developer or a tech-forward company, start experimenting with it now. The concepts you learn—about data preparation, vector stores, and agentic design—will be invaluable, regardless of whether NLWeb itself becomes the dominant standard. The age of the AI-powered website is here, and it's better to be the one building it than the one being scraped by it.

Top comments (0)