Framework Integrations for wigolo: LangChain Tools and SDK Compatibility

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 and listed in the root 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
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. 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

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

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

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 and docs/sdks.md, with tool schemas defined in 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}