Web 工具
Holon Agent 内置两个网络工具，用于检索和搜索公开网络。它们属于 Web 能力族，默认对
每个 Agent 可用。
WebFetch
WebFetch 抓取指定的 HTTP 或 HTTPS URL，提取可读文本，并返回结构化的来源信息。Agent
用它读取网页、文档或 API 响应。
参数
| 参数 | 必填 | 说明 |
|---|---|---|
url | 是 | 要抓取的 HTTP 或 HTTPS URL |
max_chars | 否 | 返回的最大字符数（默认：无硬性上限） |
extract_mode | 否 | 如何从响应中提取内容 |
提取模式
| 模式 | 行为 |
|---|---|
auto（默认） | 检测内容类型：把 HTML 渲染为文本，文本原样传递 |
text | 剥离 HTML 标签，返回纯文本 |
raw | 返回未处理的原始响应体 |
WebFetch 返回什么
每次响应都带着来源元数据：
- 最终 URL（重定向之后）
- HTTP 状态码
- 内容类型
- 截断标志和字符数
- 内容哈希（SHA-256）
抓取到的内容被运行时视为不可信的外部内容。Agent 收到的是带来源包装的内容，并被要求 不能仅凭抓取内容就提升信任级别。
用法示例
Agent 像调用其他工具一样调用 WebFetch：
WebFetch { url: "https://example.com/docs/api", max_chars: 5000 }
运行时抓取该 URL，应用 Holon 的网络策略，提取可读文本，并返回结果。
WebSearch
WebSearch 通过 Holon 的网络提供商注册表搜索网络，返回带引用的结构化结果。
参数
| 参数 | 必填 | 说明 |
|---|---|---|
query | 是 | 搜索查询字符串 |
max_results | 否 | 返回的最大结果数 |
provider | 否 | 使用的搜索提供商（默认：已配置的提供商） |
搜索提供商
Holon 使用基于提供商的搜索模型，有多种提供商可选：
- DuckDuckGo（托管）：Holon 内置的托管搜索提供商，不需要 API key。在引导流程中选择 "Managed WebSearch: DuckDuckGo" 或 "Auto" 模式即可启用。
- 腾讯云 WSA：腾讯云 SearchPro / Web Search API。需要把 API key 存为凭据 profile。
配置方式：
holon config set web.providers.tencent.kind tencent_cloud_wsa和holon config set web.providers.tencent.credential_profile <profile>。 - 博查 AI 搜索：博查 AI Web Search API。需要把 API key 存为凭据 profile。配置方式：
holon config set web.providers.bocha.kind bocha和holon config set web.providers.bocha.credential_profile <profile>。 - 模型原生搜索：部分模型提供商（OpenAI、Anthropic）通过自家 API 支持原生网络搜索。 在 "Auto" 模式下，Holon 会优先使用它们。
所有提供商返回的搜索结果都会标准化为一致格式，包含标题、URL 和摘要文本。引用会被保留，
以便 Agent 用 WebFetch 跟进读取完整页面。
搜索配置属于引导流程的一部分，之后可用 holon config set 修改。
WebSearch 返回什么
每条结果包含：
- 标题和 URL
- 摘要或概述文本
- 来源归属
结果是结构化的，Agent 可以在需要时用 WebFetch 跟进读取完整页面。工具描述明确告诉
Agent："Use WebFetch after search when full page content is needed."
用法示例
WebSearch { query: "Rust async runtime design patterns", max_results: 5 }
网络策略
Holon 对所有抓取和搜索操作应用可配置的网络策略：
- 允许的协议：仅
http和https - 域名过滤：可配置的允许/拒绝列表
- 超时：可配置的单请求超时
- 重定向：跟随到可配置的上限
策略通过 Holon 配置控制，统一作用于 WebFetch 和 WebSearch。
Agent 何时使用这些工具
Agent 根据任务上下文决定何时使用网络工具。常见模式：
- 调研：Agent 用 WebSearch 找到信息，再用 WebFetch 读取具体页面。
- 查文档：Agent 从网络上抓取 API 文档、RFC 或包文档。
- 验证：Agent 用公开来源交叉核对说法。
运行时在面向模型的工具 schema 中暴露这两个工具，Agent 在任务需要网络访问时通过正常的 工具调用选择它们。
XSearch
XSearch 使用 xAI 托管的 x_search 端点搜索公开的 X（Twitter）帖子。它作为一次隔离的
提供商请求运行，独立于主对话模型，并返回带引用的持久文本。
何时使用 XSearch
用于 X 特有的内容、账号或讨论。一般网页搜索用 WebSearch。
参数
| 参数 | 必填 | 说明 |
|---|---|---|
query | 是 | 搜索查询字符串 |
allowed_x_handles | 否 | 只保留这些 X 账号的结果（最多 10 个，不带 @） |
excluded_x_handles | 否 | 排除这些 X 账号的结果（最多 10 个，不带 @） |
from_date | 否 | 起始日期，YYYY-MM-DD 格式 |
to_date | 否 | 结束日期，YYYY-MM-DD 格式 |
XSearch 返回什么
| 字段 | 说明 |
|---|---|
text | 模型响应中的搜索结果文本 |
citations | 结构化引用，含 URL、标题和文本位置索引 |
provider | 始终为 xai |
backend | 始终为 x_search |
model | 用于搜索的 xAI 模型 |
diagnostics | 提供商请求 ID、延迟和托管条目类型计数 |
前置条件
XSearch 需要：
- 配置好 xAI 提供商，使用
openai_responsestransport 和有效凭据（通过 Codex 的 OAuth 设备登录，或 API key）。 - 启用 XSearch（有 xAI 凭据时默认启用）。
停用 XSearch：
holon config set x_search.enabled false
配置
XSearch 配置使用这些键：
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
x_search.enabled | boolean | true | 有 xAI 凭据时启用 XSearch |
x_search.model | model_ref | grok-4.3 | 隔离 XSearch 请求使用的 xAI 模型路由 |
x_search.timeout_seconds | integer | 60 | 请求超时秒数 |
默认模型是 grok-4.3。XSearch 使用 xAI 提供商的 OAuth 凭据，只在收到 401 Unauthorized
响应时刷新 token。
用法示例
XSearch { query: "Holon runtime agent framework", from_date: "2026-01-01" }
配置
网络工具通过 Holon 的 web 配置项控制：
# 查看当前 web 配置
holon config get web.search.enabled
# 完全停用网络工具
holon config set web.fetch.enabled false
holon config set web.search.enabled false
完整的 web 配置 schema 见配置参考。
另见
- 模型工具 schema 清册：工具注册与稳定性
- 集成指南：HTTP 控制平面和 webhook
- 配置参考：网络策略设置