---
document_id: agent.collection.task.web_search_v1
schema_version: 2
parent_document_id: agent.querying
section: querying
---

<!-- Generated by scripts.build_agent_guide; do not edit. -->

# Web search / 网页搜索

Search public webpages with the selected engine and return only filtered organic results.

使用指定搜索引擎查询公开网页，只返回经过筛选的自然搜索结果。

Task / 任务: `web_search_v1`
Platform / 平台: Search engine / 搜索引擎
Billing / 计费: 3 Credits per successful task / 每个成功任务 3 Credits
Estimate / 估价: call `estimate_collection`; start directly when `approval_required=false`, otherwise obtain approval for `upper_bound_credits`.
估价：调用 `estimate_collection`；`approval_required=false` 时直接启动，否则请用户确认 `upper_bound_credits`。

## Limitations / 限制

- 一次任务只选择一个搜索引擎；不会自动合并两个引擎。
- Google 页码由调用方显式填写 1--20；Bing 只支持第 1 页。
- 只公开自然搜索结果的 rank、title、url、snippet，不公开上游字段名或真实消耗量。
- 搜索词最多 200 个 Unicode 字符且 UTF-8 不超过 4 KiB。

## Inputs / 输入

- `engine` — Search engine / 搜索引擎; kind=select; required=True; default='google_advanced'; allowed=google_advanced, bing_basic
- `query` — Query / 搜索词; kind=text; required=True; default=''; bounds=min_length=1, max_length=200
- `locale` — Locale / 语言地区; kind=select; required=False; default='zh-CN'; allowed=zh-CN, en-US, ja-JP
- `range` — Time range / 时间范围; kind=select; required=False; default='none'; allowed=none, hour, day, week, month, year
- `page` — Page / 页码; kind=integer; required=False; default=1; bounds=min=1, max=20

## Minimal call / 最小调用

`estimate_collection`

```json
{
  "task_query": "搜索公开网页上的天猫扫地机器人信息",
  "task_code": "web_search_v1",
  "input": {
    "engine": "google_advanced",
    "query": "天猫扫地机器人",
    "locale": "zh-CN",
    "range": "none",
    "page": 1
  }
}
```


## Result and pagination / 结果与分页

- mode=none

Only the fields listed below are part of the stable result contract. /
只有下方列出的字段属于稳定结果契约。

## Result fields / 结果字段

- `meta.request_id` — type=string; Asklear request identifier for tracing. / 用于追踪的 Asklear 请求 ID。
- `meta.api_name` — type=string; Executed collection operation name. / 实际执行的采集操作名称。
- `meta.latency_ms` — type=integer; Collection execution latency in milliseconds. / 采集执行耗时（毫秒）。
- `meta.credits_charged` — type=integer; Asklear user-side Credits settled for this task after completion. / 任务完成后 Asklear 用户侧实际结算的 Credits。
- `data.query` — type=string; The normalized search query. / 规范化后的搜索词。
- `data.engine` — type=enum; The selected search engine. / 本次选择的搜索引擎。
- `data.locale` — type=enum; The requested language and region. / 请求使用的语言和地区。
- `data.page` — type=integer; The explicitly requested result page. / 显式请求的结果页码。
- `data.items` — type=array<object>; Filtered natural search results for this page. / 本页经过筛选的自然搜索结果。
- `data.items[].rank` — type=integer; Asklear result rank within this page. / Asklear 在本页重新编号的结果排名。
- `data.items[].title` — type=string; Result title. / 结果标题。
- `data.items[].url` — type=string; Safe absolute webpage URL. / 安全的绝对网页链接。
- `data.items[].snippet` — type=string|null; Result summary when available. / 结果摘要（如有）。

Use `list_collection_tasks` as the runtime authority, then `describe_collection_task` for one task's full input contract, examples and limits. Collection access is entitlement-gated. /
以 `list_collection_tasks` 返回为运行时准据，再用 `describe_collection_task` 取单个任务的完整入参契约、示例与限制；采集能力受 entitlement 控制。