langchain-cloudsway

LangChain integration for the Cloudsway SmartSearch API.

Installation

pip install -U langchain-cloudsway

Configuration

The tool expects a single environment variable containing both the endpoint and access key in the format: endpoint-accesskey

Examples:

# POSIX / Git Bash
export CLOUDSWAY_SERVER_KEY="endpoint-accesskey"

# Windows (cmd.exe / PowerShell)
set CLOUDSWAY_SERVER_KEY=endpoint-accesskey
# or in PowerShell:
$env:CLOUDSWAY_SERVER_KEY="endpoint-accesskey"

• endpoint: the random path segment generated for your account (used in the request URL).
• accesskey (AK): the AccessKey used for Authorization Bearer.

Register and get credentials at: https://console.cloudsway.ai/

Tool

SmartsearchTool — web search using Cloudsway Smart API.

Basic Python usage

from langchain_cloudsway.smartsearch import SmartsearchTool

tool = SmartsearchTool()
result = tool.invoke({
    "query": "cloudsway.ai",
    "count": 5,
    "setLang": "en"
})
print(result)

Parameters

Notes:

• q (query) is required and must be non-empty.
• count default: 10. Maximum: 50. Accepted values (recommended page sizes): 10, 20, 30, 40, 50.
• offset is zero-based.
• freshness supports Day, Week, Month or a date range like 2019-02-01..2019-05-30 (source support may vary).
• setLang accepts 2- or 4-letter codes (recommend 4-letter like en-US). If invalid, server may default to en.
• enableContent and mainText control long/full content fetching. mainText only applies when enableContent=true.

Advanced examples

# freshness + language
tool.invoke({"query": "latest AI research", "count": 20, "freshness": "Week", "setLang": "en-US"})

# site filter + full content + mainText
tool.invoke({"query": "machine learning tutorial", "sites": "github.com", "enableContent": True, "mainText": True})

# pagination
tool.invoke({"query": "climate change", "count": 10, "offset": 10})

Response structure

Typical response:

{
  "queryContext": {
    "originalQuery": "cat"
  },
  "webPages": {
    "value": [
      {
        "name": "cat - 搜狗百科",
        "url": "http://baike.sogou.com/...",
        "displayUrl": "http://baike.sogou.com/...",
        "thumbnailUrl": "http://img02.sogoucdn.com/...",
        "snippet": "Short description... (first 200 characters)",
        "datePublished": "2024-07-31T06:25:29.0000000",
        "datePublishedDisplayText": "Jul 31, 2024",
        "dateLastCrawled": "2024-09-08T23:18:00.0000000Z",
        "siteName": "搜狗百科",
        "score": 0.67,
        "mainText": "Longer extracted summary or full page content (present when enableContent=true)"
      }
    ]
  }
}

Response field notes:

• queryContext.originalQuery — original query string.
• webPages.value — array of WebPage objects.
• WebPage fields:
  • name (String): page title.
  • snippet (String): short text snippet (first ~200 chars).
  • url (String): canonical URL.
  • displayUrl (String): display-friendly URL.
  • thumbnailUrl (String): thumbnail image URL when available.
  • datePublished / datePublishedDisplayText (String): publish time and display text.
  • dateLastCrawled (String): last crawl time (when available).
  • siteName (String): source site name.
  • score (Float): relevance score.
  • mainText (String): long summary .
  • content: extracted main content (only when enableContent requested)

Status codes / Error handling

• 200: Success
• 429: QPS (rate) limit exceeded — contact Cloudsway to request higher QPS.

If you encounter any problems, reach out to info@cloudsway.com.

License

MIT — See LICENSE for details.