一、启用前提
·配置环境变量 WSA_API_KEY：dev 环境写到项目 .env，线上写到控制台环境变量；缺失会提示 web_search requires the WSA_API_KEY environment variable…。
·主账号需在腾讯云控制台开通 联网搜索（WSA） 服务，参考 WSA API 文档。
注意：说明：
注意：部署时，该环境变量非必填。部署成功后，仍可在控制台的项目设置中继续补充填写。
二、参数
| 字段 | 类型 | 必填 | 默认 | 说明 |
| query | string | 是 | — | 搜索关键词，不可为空字符串。 |
| maxResults | integer ≥ 1 | 否 | 5 | 去重后返回的最大条数（按 href 去重）。 |
| site | string | 否 | — | 站内搜索：把结果限制在单个域，例如 "zhihu.com"、"cloud.tencent.com"；省略表示全网检索。 |
三、返回值
返回 SearchResult[] —— 去重后的结果数组（按 href 去重，长度 ≤ maxResults）。每项字段如下：
| 字段 | 类型 | 说明 |
| title | string | 结果标题（已 trim）。 |
| href | string | 目标 URL（WSA 直接返回真实可访问地址，无需再跟重定向）。 |
| snippet | string | 摘要片段，对应 WSA 的 content / passage。 |
| site | string | 来源站点名（部分小站可能为空）。 |
| date | string | 内容发布日期（可能为空）。 |
四、TS 示例
// 全网检索const webSearch = context.tools.get('web_search')const results = await webSearch.execute({ query: '最近 AI 有什么新的技术'})// results: [{ title, href, snippet, site, date }, …]
五、Python 示例
# 全网检索web_search = context.tools.get('web_search')results = await web_search.execute({ 'query': '最近 AI 有什么新的技术',})
六、第三方搜索服务
如果不想使用 腾讯云 WSA，可以接入第三方搜索服务（例如 Exa、Tavily 等）。
七、推荐对接形式：自定义工具 + 屏蔽内置 web_search
把第三方调用包成一个与 framework 适配后的工具形态一致的对象，然后在挂载到 Agent 时把内置 web_search 过滤掉，避免 LLM 同时看到两个用途相同的工具。
TS 示例（Exa + OpenAI Agents）
import Exa from 'exa-js'import { tool } from '@openai/agents'import { z } from 'zod'const exa = new Exa(process.env.EXA_API_KEY!)// 1) 把第三方调用包成 framework 原生工具const exaSearch = tool({ name: 'web_search', description: 'Search the public web. Returns title / url / snippet for top results.', parameters: z.object({ query: z.string().describe('Search keywords'), maxResults: z.number().int().min(1).default(5), }), execute: async ({ query, maxResults }) => { const { results } = await exa.search(query, { numResults: maxResults, contents: { highlights: true }, }) return results.map((r) => ({ title: r.title ?? '', href: r.url, snippet: r.highlights?.[0] ?? r.text?.slice(0, 200) ?? '', site: new URL(r.url).hostname, date: r.publishedDate ?? '', })) },})// 2) 挂载时过滤掉内置 web_search，避免和自定义工具冲突const tools = [ …context.tools.all().filter((t) => t.name !== 'web_search'), exaSearch,]