网络搜索工具
web_search 是平台提供的公网搜索工具示例，底层调用腾讯云联网搜索（WSA）API，适合 LLM 在需要发现信息、查询资料或获取最新内容时使用。开发者也可以根据业务场景接入第三方搜索服务或自定义搜索工具。启用前提
配置环境变量
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 有什么新的技术'})
第三方搜索服务
推荐对接形式：自定义工具 + 屏蔽内置 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,]
