# LangChain

> 借助官方 search1api-langchain 工具包，为 LangChain 智能体提供实时网页搜索、智能搜索、新闻和页面内容。

Canonical URL: https://s1.dev/zh/docs/integrations/langchain

`search1api-langchain` 是 Search1API 官方的 LangChain 集成。它通过 LangChain 的标准工具接口提供网页搜索、智能搜索、新闻搜索和页面抓取，并依赖官方 Search1API Python SDK 处理认证、重试、超时和 API 错误。

> **info:** PyPI 上名称相近的 `langchain-search1api` 包是一个独立的第三方项目。`search1api-langchain` 才是由 Search1API 维护的包。

## 安装

```bash
pip install search1api-langchain
```

在[仪表盘](https://app.s1.dev)创建密钥，然后导出：

```bash
export SEARCH1API_API_KEY="your-api-key"
```

同时也接受 `SEARCH1API_KEY`，因此同一套环境变量也适用于 [Search1API CLI](https://s1.dev/zh/docs/integrations/cli)。

## 使用完整工具包

`Search1APIToolkit` 一次性返回全部四个工具，可直接交给智能体使用。

```python
from langchain.agents import create_agent
from search1api_langchain import Search1APIToolkit

agent = create_agent(
    model="openai:gpt-5.4",
    tools=Search1APIToolkit().get_tools(),
)

response = agent.invoke(
    {"messages": [{"role": "user", "content": "What changed in LangChain this month?"}]}
)
```

该工具包提供 `search1api_search`、`search1api_news`、`search1api_crawl` 和 `search1api_ask`。当智能体只需要其中一项能力时，每个工具也可以单独导入。

所有工具都支持异步调用：

```python
from search1api_langchain import Search1APISearchTool

search = Search1APISearchTool()
result = await search.ainvoke({"query": "async Python agents"})
```

当不适合使用基于环境变量的配置时，可以显式传入密钥和客户端设置：

```python
from search1api_langchain import Search1APISearchTool

search = Search1APISearchTool(
    api_key="your-api-key",
    timeout=45,
    max_retries=3,
)
```

API 密钥使用 Pydantic 的 secret 类型，不会出现在模型序列化结果中。

## 搜索

`search1api_search` 返回与查询相关的排序后网页结果。

```python
from search1api_langchain import Search1APISearchTool

search = Search1APISearchTool()

results = search.invoke(
    {
        "query": "latest LangChain agent releases",
        "max_results": 5,
        "time_range": "month",
    }
)
```

每条结果包含 `title`、`link` 和 `snippet`。设置 `crawl_results` 后还会在 `content` 中填入页面的可读文本，图片查询则会返回 `images` 列表。需要指定特定引擎时，可通过 `search_service` 选择上游引擎。

完整的请求和响应契约请参阅[搜索](https://s1.dev/zh/docs/basic/search)。

## 智能搜索

`search1api_ask` 只接受 `query`（1-500 个字符）。Search1API 会自行选择来源、搜索查询和时间范围。每个请求消耗 5 积分，并使用单独的 45 秒超时（`Search1APIToolkit(ask_timeout=45)`）。

```python
from search1api_langchain import Search1APIAskTool

result = Search1APIAskTool().invoke(
    {"query": "What are developers discussing about Bun on GitHub this week?"}
)
```

响应包含 `query`、`intent`、`results` 和可选的 `errors`；结果会保留各自的 `source` 和 `relevance`。详见[智能搜索](https://s1.dev/zh/docs/basic/ask)。

## 新闻

`search1api_news` 返回与查询相关的近期新闻文章，结果结构与搜索相同。

```python
from search1api_langchain import Search1APINewsTool

news = Search1APINewsTool()

articles = news.invoke({"query": "AI regulation", "time_range": "day"})
```

支持的来源和参数请参阅[新闻](https://s1.dev/zh/docs/basic/news)。

## 抓取

`search1api_crawl` 读取已知 URL，并返回干净、可读的内容。它获取并提取页面内容，不会驱动浏览器会话。

```python
from search1api_langchain import Search1APICrawlTool

crawl = Search1APICrawlTool()

page = crawl.invoke({"url": "https://example.com/article"})
```

当智能体需要完整文章而不只是摘要时，可传入搜索返回的 URL。完整契约请参阅[抓取](https://s1.dev/zh/docs/basic/crawl)。

## 积分

search 和 news 请求各消耗 1 积分。设置 `crawl_results` 会让 Search1API 读取排名靠前的结果页面，每成功抓取一个页面额外消耗 1 积分，因此这些工具将其默认设为 `0`。一次 crawl 请求消耗 1 积分。智能搜索每个请求消耗 5 积分。

新账户可获得 100 积分，无需信用卡，且不会过期。当前费率请参阅[积分与限制](https://s1.dev/zh/docs/essentials/credits-and-limits)。

## 搜索筛选与结果字段

**0.2.0** 版本支持全部 19 个[搜索引擎](https://s1.dev/zh/docs/basic/search)和全部六个[新闻来源](https://s1.dev/zh/docs/basic/news)，包括 Bing China、Yandex、Grokipedia 和 Reuters。`time_range` 支持 `day`、`week`、`month` 和 `year`；`page` 支持搜索分页。这些筛选条件适用于 search/news；智能搜索只接受 `query`。

引擎特有的结果字段位于可选的 `metadata` 中：GitHub 搜索提供 `metadata.kind`、`metadata.stars`、`metadata.language` 和 `metadata.num_comments`；Hacker News 搜索提供 `metadata.story_url`、`metadata.points` 和 `metadata.num_comments`。可选的 `published_date` 保留在结果的顶层。响应级别的 `searchParameters` 描述实际执行的请求。这些路径适用于 search/news；[热门](https://s1.dev/zh/docs/advanced/trending)保持其独立的响应结构。

## 源码

[github.com/superagents-lab/search1api-langchain](https://github.com/superagents-lab/search1api-langchain)
· [PyPI](https://pypi.org/project/search1api-langchain/)