Introduction

Most websites today are static, relying on rigid navigation menus and keyword-based search bars that often fail to provide direct answers. Microsoft NLWeb solves this by transforming any website into a conversational AI endpoint, allowing users and AI agents to query content using natural language. With over 6.2k GitHub stars, this open-source project provides a standardized protocol and a reference implementation to move the web from a collection of pages to a network of intelligent, agent-ready interfaces.

What Is Microsoft NLWeb?

Microsoft NLWeb is an open-source framework and protocol designed to bring conversational interfaces directly to websites. It enables site owners to expose their content and services through natural language querying, effectively turning a website into an AI-powered application. The project is implemented primarily in Python and released under the MIT License, making it technology-agnostic and highly flexible for developers.

At its core, NLWeb leverages existing web standards like Schema.org and RSS feeds to create a semantic layer for the web. By combining these structured data formats with Large Language Models (LLMs) and vector databases, NLWeb allows users to ask complex questions and receive precise, AI-generated responses based solely on the website’s own data, reducing hallucinations and improving accuracy.

Why Microsoft NLWeb Matters

For years, the web has been designed for human eyes, optimized for clicking and scrolling. However, the rise of AI agents has created a gap: agents struggle to navigate traditional HTML layouts, and humans are increasingly preferring conversational interfaces over manual search. NLWeb fills this gap by creating a “HTML for chat,” providing a machine-readable and human-friendly way for AI agents to discover and interact with web content.

The significance of NLWeb lies in its integration with the Model Context Protocol (MCP). Every NLWeb instance acts as an MCP server, meaning that any AI agent operating within the MCP ecosystem can automatically discover and query the website’s content. This shifts the power back to the publisher, as the website itself handles the query and generates the response, rather than relying on an external search engine to scrape and summarize the content.

Early adopters like Shopify, Eventbrite, and TripAdvisor are already leveraging NLWeb to move beyond rigid categories and provide more expressive, personalized search experiences for their users.

Key Features

• Model Context Protocol (MCP) Integration: Every NLWeb instance functions as an MCP server, making website content discoverable and actionable for AI agents across the web.
• Multi-Provider LLM Support: The framework is provider-agnostic, supporting major models from OpenAI, Anthropic, Gemini, DeepSeek, and HuggingFace.
• Flexible Vector Store Compatibility: NLWeb connects to a wide array of vector databases including Qdrant, Milvus, Snowflake, Azure AI Search, and Elasticsearch.
• Semantic Data Ingestion: It natively supports ingesting data from RSS feeds, Schema.org structured data, and JSONL files, turning semi-structured web content into searchable embeddings.
• Three Query Modes: The system supports List (ranked search results), Summarize (AI-generated summaries with citations), and Generate (full RAG-based conversational responses).
• Platform Agnostic: The reference implementation runs on Windows, macOS, and Linux, and is designed to scale from local laptops to enterprise data centers.
• Modular Architecture: Developers can plug in their own retrieval systems, LLM APIs, and custom extensions without vendor lock-in.

How Microsoft NLWeb Compares

Unlike traditional chatbot widgets that simply act as a layer on top of a site, NLWeb is a protocol. This means it doesn’t just provide a UI, but a standardized way for any AI agent to “talk” to a website. While external AI search engines like Perplexity or Google SGE provide great summaries, they often siphon traffic away from the original publisher. NLWeb allows the publisher to keep the engagement on their own site by providing the AI answers directly.

The primary tradeoff is the infrastructure requirement. While a widget is a simple script tag, NLWeb requires the developer to manage a vector database and LLM API calls. However, for organizations that want to own their AI experience and be discoverable by the emerging agentic web, this is a necessary investment in infrastructure.

Getting Started: Installation

To run the reference implementation of NLWeb locally, you will need Python installed on your system. Follow these steps to get your environment ready.

Prerequisites

Python 3.10+ is recommended. You will also need an API key from an LLM provider (e.g., OpenAI, Azure OpenAI, or Anthropic).

Local Installation

git clone https://github.com/microsoft/NLWeb.git
cd NLWeb
python -m venv myenv
source myenv/bin/activate # Use myenv\Scripts\activate on Windows
cd code
pip install -r requirements.txt

Azure Deployment

NLWeb provides specific guides for deploying to Azure Web Apps. You can package the application as a ZIP file and deploy using the Azure CLI:

git archive --format zip --output ./app.zip main
az webapp deploy --resource-group yourResourceGroup --name yourWebAppName --type zip --src-path ./app.zip

How to Use Microsoft NLWeb

Once installed, the basic workflow involves configuring your AI providers and ingesting your website’s data into a vector store. The system then routes user queries through a lightweight server that handles the natural language understanding and retrieval.

The simplest way to start is by using the provided sample data. After activating your virtual environment, navigate to the code directory and run the web server:

python app-file.py

This launches a sample UI where you can test queries. The server handles the request, uses the configured LLM to understand the intent, performs a semantic search against the vector database, and returns a response in one of the three modes: List, Summarize, or Generate.

Code Examples

One of the most powerful aspects of NLWeb is its ability to ingest data from various sources. Here is how you can load data from an RSS feed into your local vector database using the provided CLI tools:

python -m tools.db_load <rss_feed_url> <site_name>

This command parses the RSS feed, creates embeddings for the content and stores them in the vector database. This allows the AI to answer questions about the latest updates from that specific site.

For those building custom integrations, NLWeb’s architecture allows you to define your own data sources. A minimal example of how a server might be initialized in a JavaScript environment (as per the protocol spec) would look like this:

import { NLWebServer } from "@microsoft/nlweb";

const server = new NLWebServer({
  model: "gpt-4",
  dataSources: [
    { type: "rss", url: "https://example.com/feed" },
    { type: "schema", url: "https://example.com/data.json" }
  ]
});

Advanced Configuration

NLWeb is highly configurable via YAML files located in the code/config directory. This allows you to switch providers without changing the core logic.

LLM Provider Configuration

To change your LLM, edit config_llm.yaml. You can specify the provider (e.g., openai, azure, anthropic) and the specific model version you wish to use.

Retrieval Backend Configuration

Edit config_retrieval.yaml to switch between local storage (like Qdrant local) and enterprise-scale vector databases like Snowflake or Azure AI Search.

Embedding Model Configuration

The config_embedding.yaml file controls which model is used to turn your text into vectors. It is critical that the embedding model used for ingestion is the same as the one used for querying.

Real-World Use Cases

NLWeb is designed for any website that has a large volume of content that is difficult to navigate. Here are a few concrete scenarios where it shines:

• E-commerce Product Discovery: A retailer can implement NLWeb to allow customers to ask, “Find me red sneakers under $80 with free shipping,” instead of using traditional category filters.
• Corporate Documentation: An organization can use NLWeb to turn their internal procedure manuals and knowledge bases into a conversational interface for employees.
• 
  News and Media Sites: A news outlet can allow users to ask, “Summarize the last three articles about renewable energy from the last 6 months,” providing a direct answer on the site.
• University Program Search: A university can allow prospective students to ask, “Which Master’s programs have a December application deadline?” and receive a direct list of results.

Contributing to Microsoft NLWeb

Microsoft encourages contributions to the project. Most contributions require agreeing to the Microsoft Contributor License Agreement (CLA). After submitting a pull request, a CLA bot will automatically check your status.

To contribute, follow these principles: keep the core repository small and minimally complicated. If you want to add a significant new feature or a new language implementation, Microsoft recommends creating a fork of the project. New providers (LLMs or vector stores) should be added alphabetically in the .env file and be disabled by default in the config files.

Bugs can be reported via GitHub Issues, and new provider suggestions can be submitted as pull requests.

Community and Support

The primary hub for NLWeb is the official GitHub repository. Developers can engage in discussions, report issues, and review the latest updates through the GitHub Discussions tab. GitHub Issues is the main channel for troubleshooting and implementation help.

Documentation is available within the /docs folder of the repository, which includes detailed guides on the REST API, modifying prompts, and adding memory to conversations. The project also has a dedicated documentation website at NLWeb.ai.

Conclusion

Microsoft NLWeb represents a fundamental shift in how we interact with the web. By moving from a page-based architecture to a conversational, agent-ready architecture, it allows publishers to regain control over their content and provides users with a more intuitive way to find information.

While the project is currently in an experimental phase and requires some infrastructure management, it is the right choice for developers and publishers who want to be part of the “agentic web.” If you are building a site with extensive content and want to provide a direct, AI-powered answer engine on your page, NLWeb is the ideal tool.

Star the repo, try the quickstart, and join the community to help build the next generation of the conversational internet.

Resources

• Microsoft NLWeb GitHub Repository
• Official NLWeb Documentation Site
• Microsoft Open Source CLA