当您的智能体需要查找信息来回答问题或完成任务时，可以使用网页搜索。
示例：解释为什么火星看起来是红色的
将此 JSON 请求体发送到 POST /v1/agents/sessions，以创建会话并流式传输回答。它会启用 live 模式的网页搜索：
{
"agent": {
"model": "gpt-6-astra",
"reasoning": { "effort": "low" },
"tools": [{ "type": "web_search", "mode": "live" }]
},
"environment": { "type": "none" },
"input": "Search NASA's website for why Mars looks red. Explain it in two sentences and include a source link.",
"stream": true
}结果
在 2026 年 9 月 10 日的一次测试运行中，智能体搜索了 NASA 网站，并流式传输了以下回答：
Mars looks red because iron minerals in its soil oxidize, or rust, giving the surface a reddish color. This rusty appearance is why it’s called the “Red Planet,” according to NASA’s Mars Facts.
这是一次实际运行的记录。您得到的回答可能有所不同。
如果您的 agent.tools 中未包含 web_search，内置网页搜索就处于关闭状态。在提示中要求搜索并不会启用它。
搜索模式
live（默认）：允许搜索实时访问互联网。当您包含web_search但省略mode时，使用此模式。cached：搜索已保存的网页内容，不实时访问互联网。disabled：关闭内置网页搜索，效果与不包含该工具相同。
可选设置
将以下字段添加到同一个 web_search 条目中：
| 设置 | 作用 | 省略时的行为 |
|---|---|---|
context_size | 模型从搜索中接收的信息量：low、medium 或 high。 | 使用 medium。 |
allowed_domains | 搜索可以包含哪些网站。最多提供 100 个域名，例如 ["python.org", "docs.python.org"]。 | 不应用域名筛选。 |
location | 帮助根据地点调整结果。接受 country、region、city 和 timezone。 | 不向搜索提供位置信息。缺少位置详情可能导致本地搜索结果的相关性降低，或无法找到有用的匹配结果。 |