> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Web Fetch 服务器工具

> 允许模型在请求期间获取并读取指定 URL。

当模型需要读取已知 URL（例如文档页面、文章、更新日志或类似 PDF 的文本来源）时，请使用 `phaseo:web_fetch`。

模型会判断何时需要抓取、提供 URL，并将有长度限制的页面文本作为工具上下文接收。

## 工作原理

1. 将 `{ "type": "phaseo:web_fetch" }` 添加到 `tools`。
2. 模型判断是否需要抓取 URL。
3. Phaseo 使用已配置的引擎获取并提取内容。
4. 提取的文本、标题、URL 和截断元数据会返回给模型。
5. 模型生成最终回复；如果需要，还可以继续抓取其他 URL。

## 快速开始

```bash theme={null}
curl https://api.phaseo.app/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5-nano",
    "messages": [
      { "role": "user", "content": "Summarize https://phaseo.app/docs/v1/guides/tool-calling" }
    ],
    "tools": [
      { "type": "phaseo:web_fetch" }
    ]
  }'
```

## 配置

```json theme={null}
{
  "type": "phaseo:web_fetch",
  "parameters": {
    "engine": "direct",
    "max_chars": 12000,
    "allowed_domains": ["phaseo.app"],
    "blocked_domains": ["internal.example.com"]
  }
}
```

| 参数 | 类型 | 默认值 | 说明 |
| - | - | - | - |
| `engine` | string | 取决于接口 | 抓取引擎：`auto`、`native`、`direct`、`exa`、`parallel` 或 `firecrawl`。 |
| `max_chars` | integer | `12000` | 返回给模型的提取字符数上限。 |
| `max_content_tokens` | integer | 无 | 以令牌数表示的别名；未设置 `max_chars` 时使用。 |
| `max_uses` | integer | `10` | 服务器工具循环中的最大抓取次数。 |
| `allowed_domains` | string\[] | 无 | 仅允许从这些域名抓取。 |
| `blocked_domains` | string\[] | 无 | 拒绝从这些域名抓取。别名：`excluded_domains`。 |

## 引擎选择

| 引擎 | 行为 |
| - | - |
| `auto` | 在 `/v1/messages` 上使用 Anthropic 原生抓取；否则在已配置时使用 Exa；再否则使用网关直接抓取。 |
| `direct` | 直接从网关运行时抓取，并提取长度受限的文本。 |
| `exa` | 如果已配置，则使用 Exa 内容提取。 |
| `parallel` | 如果已配置，则使用 Parallel Extract。 |
| `firecrawl` | 如果已配置，则使用 Firecrawl Scrape。 |
| `native` | 在 `/v1/messages` 上转换为 Anthropic 原生 `web_fetch_20260209`。其他接口应使用 `direct` 或托管引擎。 |

仅支持 HTTP(S) URL。网关直接抓取支持文本类内容类型，并会先将 HTML 转为纯文本，再返回给模型。

## Anthropic 原生抓取

```json theme={null}
{
  "model": "claude-sonnet-4.6",
  "max_tokens": 1024,
  "messages": [
    { "role": "user", "content": "Read the docs page and summarize the limits." }
  ],
  "tools": [
    {
      "type": "phaseo:web_fetch",
      "parameters": {
        "engine": "native",
        "max_content_tokens": 9000,
        "allowed_domains": ["phaseo.app"]
      }
    }
  ],
  "tool_choice": { "type": "tool", "name": "phaseo:web_fetch" }
}
```

## 工具结果

托管抓取会返回包含以下字段等信息的 JSON 工具结果：

```json theme={null}
{
  "provider": "fetch",
  "engine": "direct",
  "url": "https://phaseo.app/docs/v1/guides/tool-calling",
  "final_url": "https://phaseo.app/docs/v1/guides/tool-calling",
  "status": 200,
  "content_type": "text/html",
  "title": "Tool Calling",
  "text": "...",
  "truncated": false,
  "returned_chars": 8421
}
```

在假设模型收到完整页面前，请检查 `truncated`。

## 用量与价格

Web Fetch 调用会增加：

```json theme={null}
{
  "usage": {
    "server_tool_use": {
      "web_fetch_requests": 1
    }
  }
}
```

托管抓取计费可使用 `server_tool_web_fetch_requests`。如果模型价格卡定义了相应计量项，提供方原生抓取用量可以使用 `native_web_fetch_requests`。

## 相关指南

* [网页搜索](./web-search.mdx)
* [服务器工具](./index.mdx)
* [使用 Web Fetch 为回答提供依据](../../cookbook/tool-grounding-with-web-fetch.mdx)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.