> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nimbleway.com/llms.txt
> Use this file to discover all available pages before exploring further.

# LangChain

> LangChain tools and retrievers for web search, content extraction, Extract Templates, Map/Crawl, and resumable Agent API V2 research.

### Overview

The [`langchain-nimble`](https://pypi.org/project/langchain-nimble/) package provides production-grade LangChain integrations for the Nimble web data platform. Built on the official [`nimble_python`](https://pypi.org/project/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-sdk/web-tools/extract/template) | `nimble_extract_template_*` |
| Multi-page crawl or URL discovery | Crawl / Map | `nimble_crawl`, `nimble_map` |
| Deep research with citations and trust | [Agent API V2](/nimble-sdk/web-search-agents/overview) (Web Search Agents) | `nimble_web_search_agent_*` |

<Warning>
  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.
</Warning>

#### 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

```bash theme={"system"}
pip install -U langchain "langchain-nimble>=4.0.0" langchain-openai
```

#### Setup

Get your API key from [Nimble's dashboard](https://online.nimbleway.com/account-settings/api-keys) (free trial available):

```bash theme={"system"}
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

```python theme={"system"}
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.

```python theme={"system"}
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:

1. `nimble_extract_template_list` — discover templates for the account
2. `nimble_extract_template_get` — inspect schema / published version
3. `nimble_extract_template_run` — run with `template` + `params`

See the [Extract Templates guide](/nimble-sdk/web-tools/extract/template) and [API reference](/api-reference/extract-templates-api/run-extract-template).

### Agent API V2 (Web Search Agents)

Deep research / enrichment / dataset building via [Agent API V2](/nimble-sdk/web-search-agents/overview). 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.

```python theme={"system"}
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`.

```python theme={"system"}
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`](https://github.com/Nimbleway/langchain-nimble/blob/main/examples/agent_api_v2.py) and [`examples/web_search_agent.py`](https://github.com/Nimbleway/langchain-nimble/blob/main/examples/web_search_agent.py) (templates + search/extract/map/crawl).

### Crawl and Map

```python theme={"system"}
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)

```python theme={"system"}
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](https://github.com/Nimbleway/langchain-nimble/blob/main/CHANGELOG.md).

### Attribution

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

```http theme={"system"}
X-Client-Source: langchain-nimble
```

No extra configuration is required.

### Additional Resources

* [GitHub repository](https://github.com/Nimbleway/langchain-nimble)
* [PyPI package](https://pypi.org/project/langchain-nimble/)
* [Agent API V2 overview](/nimble-sdk/web-search-agents/overview)
* [Extract Templates](/nimble-sdk/web-tools/extract/template)
* [Nimble Python SDK](/nimble-sdk/sdks/python)
* [Example cookbook](https://github.com/Nimbleway/cookbook)
* [LangChain integrations overview](https://docs.langchain.com/oss/python/integrations/providers/overview)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.