# Framework Integrations for wigolo: LangChain Tools and SDK Compatibility

> Explore wigolo framework integrations like LangChain, CrewAI, and LlamaIndex. Discover how wigolo's LangChain tools map to its MCP surface with full semantics preserved.

- Repository: [Towhid Khan/wigolo](https://github.com/KnockOutEZ/wigolo)
- Tags: framework-integrations
- Published: 2026-07-19

---

**wigolo ships with native framework integrations for LangChain, CrewAI, LlamaIndex, and the Vercel AI SDK, mapping its ten-tool MCP surface to each library’s native abstractions through thin Python adapters that preserve full evidence, scoring, and cache semantics.**

The **KnockOutEZ/wigolo** repository provides idiomatic SDK wrappers that bridge its local-first web capabilities—search, fetch, crawl, extract, and more—to popular LLM orchestration frameworks. These integrations allow developers to embed wigolo’s evidence-rich tooling into existing agent workflows without leaving their preferred ecosystem.

## Available Framework Integrations

wigolo maintains four official integration packages, each exposing the complete ten-tool surface (search, fetch, crawl, extract, cache, find-similar, research, agent, diff, watch) through framework-specific patterns:

- **LangChain** (`wigolo-langchain`): Implements `BaseRetriever` for search and `BaseTool` wrappers for agent-ready tool calling.
- **CrewAI** (`wigolo-crewai`): Provides a `wigolo_tools()` helper that returns a list of CrewAI-compatible tool objects mirroring all ten capabilities.
- **LlamaIndex** (`wigolo-llamaindex`): Offers `BaseReader` implementations (`WigoloWebReader`, `WigoloSearchReader`) that ingest wigolo-fetched content as `Document` objects.
- **Vercel AI SDK** (`wigolo-vercel-ai-sdk`): Exports factory functions like `createWebSearchTool()` that generate Vercel-compatible tool objects for `generateText` or `streamText` calls.

All packages are documented in [`docs/sdks.md`](https://github.com/KnockOutEZ/wigolo/blob/main/docs/sdks.md) and listed in the root [`README.md`](https://github.com/KnockOutEZ/wigolo/blob/main/README.md) under the SDKs & integrations section.

## How LangChain Tools Map to wigolo Capabilities

LangChain expects two primary extension points: **Retrievers** for document retrieval and **Tools** for agent execution. The `wigolo-langchain` package implements both patterns to cover wigolo’s full capability set.

### The LangChain Abstraction Model

LangChain’s architecture distinguishes between data retrieval and agent tooling:

1. **Retrievers** inherit from `BaseRetriever` and return lists of `Document` objects given a query.
2. **Tools** inherit from `BaseTool` and expose a `run` method that agents invoke during reasoning loops.

`wigolo-langchain` maps wigolo’s functionality across both abstractions, ensuring search operates as a standard RAG component while fetch, crawl, and extract operate as agent-callable utilities.

### Core Implementations: Search and Fetch

The integration provides concrete implementations for wigolo’s two most common operations:

| wigolo Capability | LangChain Class | Implementation Details |
|-------------------|-----------------|------------------------|
| **search** (multi-engine, rank-fusion, ML rerank) | `WigoloSearchRetriever` | Inherits `BaseRetriever`; calls wigolo’s `search` tool via an async MCP client; returns `Document` objects with metadata including `title`, `url`, `excerpt`, and evidence scores as documented in [`packages/wigolo-langchain/README.md`](https://github.com/KnockOutEZ/wigolo/blob/main/packages/wigolo-langchain/README.md) |
| **fetch** (tiered HTTP → headless browser) | `WigoloFetchTool` | Inherits `BaseTool`; wraps wigolo’s `fetch` tool and returns raw JSON strings to prevent agent exceptions |

The `WigoloSearchRetriever` accepts parameters like `max_results` and `include_domains`, forwarding them directly to wigolo’s search endpoint while surfacing results as standard LangChain `Document` instances.

### Extending to the Full Tool Surface

While `search` and `fetch` ship as stable implementations, the remaining eight tools (crawl, extract, cache, find-similar, research, agent, diff, watch) follow an identical pattern documented in [`packages/wigolo-langchain/README.md`](https://github.com/KnockOutEZ/wigolo/blob/main/packages/wigolo-langchain/README.md). Each tool wraps `WigoloMcpClient.call_tool()`, forwarding arguments to the corresponding wigolo MCP method and returning JSON-encoded output.

This design allows developers to create custom `BaseTool` subclasses for any wigolo capability by instantiating the client and invoking `call_tool(name, arguments)`.

### The WigoloMcpClient Architecture

The **`WigoloMcpClient`** class handles low-level MCP subprocess communication, defaulting to `npx wigolo` execution. Key architectural behaviors include:

- **Embedded local mode**: When no wigolo daemon is running, the client spawns one automatically and shuts it down on context exit, guaranteeing zero-setup usage.
- **JSON string returns**: All tools return JSON strings rather than raising Python exceptions, fitting LangChain’s agent loop where deterministic string results are required. Errors encode as JSON error objects, allowing agents to recover without chain crashes.
- **Thin adapter philosophy**: The integration performs no extra processing; all intelligence (ranking, caching, reranking, on-device embeddings) remains inside wigolo.

## Practical Implementation Examples

The following snippets demonstrate direct usage of wigolo’s LangChain integration, showing how native wigolo capabilities surface through standard LangChain APIs.

### Using wigolo as a Retriever

```python
from wigolo_langchain import WigoloMcpClient, WigoloSearchRetriever

async def demo_retriever():
    async with WigoloMcpClient() as client:
        retriever = WigoloSearchRetriever(
            client=client,
            max_results=5,
            include_domains=["docs.python.org"],
        )
        docs = await retriever.ainvoke("Python asyncio tutorial")
        for doc in docs:
            print(f"{doc.metadata['title']} → {doc.metadata['url']}")

```

### Using wigolo as LangChain Tools for Agents

```python
from wigolo_langchain import WigoloMcpClient, WigoloSearchTool, WigoloFetchTool
from langchain.agents import AgentExecutor, tool

async def demo_agent():
    async with WigoloMcpClient() as client:
        search = WigoloSearchTool(client=client)
        fetch = WigoloFetchTool(client=client)

        @tool
        async def web_search(query: str) -> str:
            return await search.ainvoke({"query": query})

        @tool
        async def web_fetch(url: str) -> str:
            return await fetch.ainvoke({"url": url})

        # Use with AgentExecutor:

        # agent = AgentExecutor.from_llm_and_tools(

        #     llm=your_llm, tools=[web_search, web_fetch]

        # )

        # await agent.arun("Find and summarize Python 3.12 release notes")

```

### Creating Custom Tools for Additional Capabilities

```python
from wigolo_langchain import WigoloMcpClient
from langchain.tools import BaseTool

class WigoloCrawlTool(BaseTool):
    name = "wigolo_crawl"
    description = "Crawl a website recursively; returns JSON with page metadata."

    def __init__(self, client: WigoloMcpClient):
        self.client = client

    async def _run(self, url: str, depth: int = 2) -> str:
        return await self.client.call_tool(
            "crawl", {"url": url, "depth": depth}
        )

```

## Summary

- **wigolo** provides official **framework integrations** for LangChain, CrewAI, LlamaIndex, and Vercel AI SDK through dedicated packages like `wigolo-langchain`.
- **LangChain tools** map directly to wigolo’s MCP surface: `search` implements `BaseRetriever`, while `fetch`, `crawl`, and others implement `BaseTool`.
- The **`WigoloMcpClient`** manages subprocess lifecycle, auto-spawning the wigolo daemon when needed and returning JSON strings to prevent agent loop crashes.
- Implementation files reside in [`packages/wigolo-langchain/README.md`](https://github.com/KnockOutEZ/wigolo/blob/main/packages/wigolo-langchain/README.md) and [`docs/sdks.md`](https://github.com/KnockOutEZ/wigolo/blob/main/docs/sdks.md), with tool schemas defined in [`docs/tools.md`](https://github.com/KnockOutEZ/wigolo/blob/main/docs/tools.md).

## Frequently Asked Questions

### What frameworks does wigolo support besides LangChain?

wigolo officially supports four frameworks: **LangChain** (`wigolo-langchain`), **CrewAI** (`wigolo-crewai`), **LlamaIndex** (`wigolo-llamaindex`), and the **Vercel AI SDK** (`wigolo-vercel-ai-sdk`). Each package adapts wigolo’s ten-tool surface to the framework’s native idioms, such as CrewAI’s tool lists or LlamaIndex’s `BaseReader` implementations.

### How does wigolo handle errors in LangChain agents?

Rather than raising Python exceptions that would halt the agent loop, wigolo’s LangChain integration returns **JSON-encoded error objects** as strings. This allows the LLM agent to receive the error context, reason about recovery strategies, and continue execution without crashing the entire chain.

### Can I use wigolo tools not yet published as LangChain BaseTools?

Yes. While only `search` and `fetch` ship as stable `BaseTool` implementations, you can expose any of wigolo’s ten tools (crawl, extract, cache, etc.) by creating a custom class that inherits from `BaseTool` and calls `WigoloMcpClient.call_tool(name, arguments)`. The pattern is documented in [`packages/wigolo-langchain/README.md`](https://github.com/KnockOutEZ/wigolo/blob/main/packages/wigolo-langchain/README.md) and requires only a thin wrapper around the MCP client.

### Does wigolo require a running server for LangChain integration?

No. The `WigoloMcpClient` includes an **embedded local mode** that automatically spawns a wigolo daemon via `npx wigolo` if none is detected, then shuts it down when the async context exits. This guarantees zero-setup operation for LangChain users while still supporting connections to existing wigolo servers if preferred.