OpenAI Web Search

OpenAI Web Search 让支持该能力的模型在回答前搜索网络，并在响应中返回文本、搜索调用和来源引用。它适合新闻、天气、产品更新和其他具有明显时效性的查询。

如果数据来自你自己的数据库或业务服务，应改用 Tool Calling 定义受控工具，而不是把内部数据交给公共网络搜索。

先确认模型和入口

Web Search 字段存在于协议中，不代表当前账户的每个模型都支持搜索。请先在模型广场确认模型和协议，再查看对应 API Reference。

选择 Responses 或 Chat

入口	启用方式	结果位置
Responses	在 `tools` 中加入 Web Search Tool	`web_search_call` 与 Message Output Item
Chat Completions	使用 `web_search_options`	Assistant Message 和 `annotations`

Responses 更适合需要区分搜索调用、回答和来源的应用；Chat 适合已经使用消息结构的项目。

使用 Responses 搜索网络

curl 'https://api.agtcloud.cn/v1/responses' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "tools": [
      {
        "type": "web_search_preview",
        "search_context_size": "medium"
      }
    ],
    "input": "今天有哪些值得关注的技术新闻？"
  }'

模型可能根据问题决定是否执行搜索。搜索发生时，响应的 output 通常同时包含搜索调用项和文本消息项；完整 Tool 类型见 Responses Reference。

使用 Chat Completions

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "今天有哪些值得关注的技术新闻？"
      }
    ],
    "web_search_options": {
      "search_context_size": "medium"
    }
  }'

Chat 响应的正文位于 choices[].message.content，结构化引用在响应提供时位于 choices[].message.annotations。完整字段见 Chat Completions Reference。

读取回答和引用

{
  "output": [
    {
      "type": "web_search_call",
      "id": "ws_example",
      "status": "completed"
    },
    {
      "type": "message",
      "content": [
        {
          "type": "output_text",
          "text": "根据搜索结果……",
          "annotations": [
            {
              "type": "url_citation",
              "url": "https://example.com/article",
              "title": "来源标题"
            }
          ]
        }
      ]
    }
  ]
}

不要只保存回答文本。应用应保留 URL、标题以及引用与文本位置的关联，在界面中提供可点击来源，并对外部链接使用安全的新标签页属性。

限制搜索范围

在模型和入口支持时，可以配置以下搜索条件：

域名范围：只从允许的站点检索，适合医学、法规或企业知识来源。
用户位置：提供国家、城市、地区或时区，帮助返回本地化结果。
搜索上下文规模：在响应质量、延迟和用量之间选择合适范围。
来源列表：Responses 可在支持时返回搜索过程中查阅的来源，不仅是正文最终引用的来源。

这些字段在 Responses 与 Chat 中的位置不同，具体名称和限制以对应 Reference 为准。

失败与降级

现象	处理方式
没有执行搜索	判断问题是否需要实时信息，并确认模型支持搜索
有回答但没有引用	不伪造来源；提示当前响应没有返回可展示引用
搜索失败	根据响应错误决定重试、改用非搜索回答或提示用户稍后再试
来源冲突	展示多个来源和更新时间，不让模型替应用隐藏重要分歧
来源不可访问	保留标题和原 URL，提示用户该页面当前无法打开

外部网页内容可能包含错误信息或针对模型的恶意指令。不要因为内容来自搜索结果就自动信任，也不要让搜索内容绕过应用权限或触发高风险工具。

上线前检查

模型和协议明确支持 Web Search。
回答、搜索调用、引用和来源列表分别解析。
没有引用时不会生成虚假链接。
域名和位置信息只在业务需要时发送。
外部内容不会绕过 Tool Calling 的权限与确认流程。
搜索失败、超时和无结果都有清晰降级。

请求失败时参阅错误与排障，切换协议前阅读协议选择。