LangChain

Overview

The langchain-nimble package provides production-grade LangChain integrations for the Nimble web data platform. Built on the official nimble_python SDK, it enables RAG applications and AI agents that can search, extract, scrape with templates, crawl, map, and run resumable Web Search Agent research. NimbleToolkit is the single entry point. Enable the tool families you need with include flags. Choose the right capability (these are not interchangeable):

Need	Use	Public tool names
Ranked web results for RAG or agents	Search	`nimble_search` / `NimbleSearchRetriever`
Clean markdown/HTML from a known URL	Extract	`nimble_extract` / `NimbleExtractRetriever`
Structured scrape of known page types (PDP, jobs, …)	Extract Templates	`nimble_extract_template_*`
Multi-page crawl or URL discovery	Crawl / Map	`nimble_crawl`, `nimble_map`
Deep research with citations and trust	Agent API V2 (Web Search Agents)	`nimble_web_search_agent_*`

Do not treat Extract Templates and Agent API V2 as the same product. Legacy nimble_agent_* names are deprecated aliases for Extract Templates only — they are not repointed to Agent API V2 research agents.

Key Features

Search depths — lite, fast, deep, plus focus modes and domain/date filters
Extract Templates — list → get → run structured site scrapers
Agent API V2 — separate start / status / result tools (resumable; typically 3–15 minutes)
Unified toolkit — one API key; opt into templates, agents, crawl, and map
Full async — sync and async via nimble_python
Attribution — every request sends X-Client-Source: langchain-nimble

Requirements

Python 3.10+
langchain-nimble 4.0.0+ (depends on nimble_python>=1.2.0,<2.0.0)

Quick Start

Installation

pip install -U langchain "langchain-nimble>=4.0.0" langchain-openai

Setup

Get your API key from Nimble’s dashboard (free trial available):

export NIMBLE_API_KEY="your-api-key"

You can also pass api_key= into tools, retrievers, or NimbleToolkit.

Build an AI Agent with the Toolkit

from langchain.agents import create_agent
from langchain_nimble import NimbleToolkit
from langchain_openai import ChatOpenAI

# Search + Extract on by default; opt into other families as needed
toolkit = NimbleToolkit(
    include_crawl=True,
    include_map=True,
    include_extract_templates=True,
    include_web_search_agents=True,
)
tools = toolkit.get_tools()

agent = create_agent(
    model=ChatOpenAI(model="gpt-5"),
    tools=tools,
    system_prompt=(
        "You are a research assistant with Nimble web tools.\n"
        "Use search/extract for quick lookups, extract templates for "
        "structured scrapes, and Agent API V2 (start → status → result) "
        "for deep research that may take several minutes."
    ),
)

response = agent.invoke({
    "messages": [(
        "user",
        "What are the latest developments in AI agents? Summarize key findings.",
    )]
})
print(response["messages"][-1].content)

Toolkit Flags

Flag	Default	Tools
`include_search`	`True`	`nimble_search`
`include_extract`	`True`	`nimble_extract`
`include_crawl`	`False`	`nimble_crawl`
`include_map`	`False`	`nimble_map`
`include_extract_templates`	`False`	`nimble_extract_template_list` / `_get` / `_run`
`include_web_search_agents`	`False`	`nimble_web_search_agents_list`, templates list, create, `run_start` / `run_status` / `run_result`
`include_agent`	`False`	Deprecated — adds `nimble_agent_*` Extract Template aliases and emits `DeprecationWarning`. Prefer `include_extract_templates`.

You can enable include_agent and include_web_search_agents together; both families are returned (aliases + V2).

Extract Templates

For structured scraping of known page types (product pages, listings, and similar), use Extract Templates — not Agent API V2.

from langchain_nimble import NimbleToolkit

toolkit = NimbleToolkit(
    include_search=False,
    include_extract=False,
    include_extract_templates=True,
)
tools = toolkit.get_tools()
# nimble_extract_template_list → get → run(template=..., params={...})

Typical agent workflow:

nimble_extract_template_list — discover templates for the account
nimble_extract_template_get — inspect schema / published version
nimble_extract_template_run — run with template + params

See the Extract Templates guide and API reference.

Agent API V2 (Web Search Agents)

Deep research / enrichment / dataset building via Agent API V2. Tools are resumable: run_start returns immediately with identifiers; poll run_status, then fetch run_result. Do not expect a multi-minute research job to finish inside one tool call. Agent use_case (research, enrichment, or dataset_building) is set when the agent is created and locked afterward — that is separate from how you bootstrap a run below.

from langchain_nimble import NimbleToolkit

toolkit = NimbleToolkit(
    include_search=False,
    include_extract=False,
    include_web_search_agents=True,
)
tools = toolkit.get_tools()

Tool	Role
`nimble_web_search_agents_list`	List existing agents (`wsa_…`)
`nimble_web_search_agent_templates_list`	List agent templates
`nimble_web_search_agent_create`	Create a persistent agent (for `agent_id` runs)
`nimble_web_search_agent_run_start`	Start a run (`agent_name`, `agent_id`, or anonymous)
`nimble_web_search_agent_run_status`	Poll status
`nimble_web_search_agent_run_result`	Fetch output + trust / citations

Bootstrap Options

How you identify the agent on run_start (distinct from use_case):

Option	When	How
`agent_name` (default for LangChain)	Stateless tool sessions	`run_start` with `agent_name` + optional `use_case` / `skill` / `sources` — create-or-reuse
`agent_id`	You persist `wsa_…`	Create (or list) an agent, then `run_start` with `agent_id`
Anonymous	One-off demos	Omit both `agent_id` and `agent_name`

Map response fields carefully for status/result tools:

Start response id → run id (task_run_…)
Start response web_search_agent_id → agent id (wsa_…)

Effort, Use Cases, and Overrides

Effort: low | medium | high | x-high | max. Plan for 3–15 minutes on real research (not a few seconds).
use_case: research (text), enrichment (JSON + input_data), dataset_building (JSON). Locked after agent create — a different value on reuse returns 422.
Run-level overrides (skill, sources, output_schema) do not mutate the stored agent, except the first agent_name create with a new name.
input_data is enrichment payload only (never stored on the agent); distinct from output_schema.

from langchain_nimble import NimbleAgentRunStartTool, NimbleAgentRunStatusTool, NimbleAgentRunResultTool

start = NimbleAgentRunStartTool()
started = start.invoke({
    "input": "Summarize recent Agent API V2 changes for integrators.",
    "agent_name": "langchain_docs_research",
    "use_case": "research",
    "effort": "medium",
    "skill": "Focus on integrator-facing API behavior.",
})

agent_id = started["web_search_agent_id"]
run_id = started["id"]

status = NimbleAgentRunStatusTool().invoke({
    "agent_id": agent_id,
    "run_id": run_id,
})
# Poll until status is completed / failed / cancelled, then:
result = NimbleAgentRunResultTool().invoke({
    "agent_id": agent_id,
    "run_id": run_id,
})

Runnable examples in the package repo: examples/agent_api_v2.py and examples/web_search_agent.py (templates + search/extract/map/crawl).

Crawl and Map

from langchain_nimble import NimbleCrawlTool, NimbleMapTool

crawl_tool = NimbleCrawlTool()
result = crawl_tool.invoke({"url": "https://docs.example.com", "max_pages": 50})

map_tool = NimbleMapTool()
urls = map_tool.invoke({"url": "https://www.example.com"})

Crawl polls internally until the job finishes (or times out). Map discovers URLs via sitemap + link crawling.

Retrievers (RAG)

from langchain_nimble import NimbleSearchRetriever, NimbleExtractRetriever

search = NimbleSearchRetriever(max_results=5, search_depth="lite")
docs = search.invoke("latest developments in AI")

# Extract: pass the URL as the retriever query
extract = NimbleExtractRetriever(output_format="markdown")
pages = extract.invoke(
    "https://docs.langchain.com/oss/python/integrations/providers/overview"
)

Deprecated Aliases (4.0.0)

Deprecated	Prefer
`include_agent=True`	`include_extract_templates=True`
`nimble_agent_list` / `_get` / `_run`	`nimble_extract_template_*`
`include_agents`	`include_web_search_agents`

Breaking notes and SDK floor: see the package CHANGELOG 4.0.0.

Attribution

The package sets SDK client_source="langchain-nimble", which sends:

X-Client-Source: langchain-nimble

No extra configuration is required.

Agent Skills

MCP Server

Partnerships

Connectors

Proxy

Overview

Key Features

Requirements

Quick Start

Installation

Setup

Build an AI Agent with the Toolkit

Toolkit Flags

Extract Templates

Agent API V2 (Web Search Agents)

Bootstrap Options

Effort, Use Cases, and Overrides

Crawl and Map

Retrievers (RAG)

Deprecated Aliases (4.0.0)

Attribution

Additional Resources

​Overview

​Key Features

​Requirements

​Quick Start

​Installation

​Setup

​Build an AI Agent with the Toolkit

​Toolkit Flags

​Extract Templates

​Agent API V2 (Web Search Agents)

​Bootstrap Options

​Effort, Use Cases, and Overrides

​Crawl and Map

​Retrievers (RAG)

​Deprecated Aliases (4.0.0)

​Attribution

​Additional Resources

Overview

Key Features

Requirements

Quick Start

Installation

Setup

Build an AI Agent with the Toolkit

Toolkit Flags

Extract Templates

Agent API V2 (Web Search Agents)

Bootstrap Options

Effort, Use Cases, and Overrides

Crawl and Map

Retrievers (RAG)

Deprecated Aliases (4.0.0)

Attribution

Additional Resources