网络搜索

网络搜索允许 Agent 在需要最新或外部信息时从互联网获取实时数据。该功能由 Tavily API 驱动，并作为内置 Agent 工具集成。

功能开关

网络搜索工具受管理员功能开关控制。只有管理员在管理后台启用网络搜索后，web_search 工具才会暴露给 Agent 使用。

• 管理员未启用时：Agent 不会看到或调用 web_search 工具
• 管理员启用后：所有项目中的 Agent 均可自动调用网络搜索

这意味着即使 Prompt Action 的 capabilities 中声明了 web_search，如果管理员未全局启用该功能，工具仍然不可用。

功能概述

启用后，Agent 可在对话过程中自动调用 web_search 工具，用于：

• 搜索最新新闻、研究论文或技术文档
• 获取本地上下文中不存在的事实性信息
• 检索用于分析和综合的最新数据

前置条件

• 管理员：必须启用网络搜索并配置系统 API Key
• 用户：可选择性配置个人 API Key（需管理员允许）

管理员配置

管理员可在 管理后台 → 网络搜索 页面配置。

配置项

凭证优先级

用户触发搜索时，凭证按以下顺序使用：

1. 用户 API Key（若 allow_user_keys=true 且用户已配置）
2. 系统 API Key（兜底）

测试配置

点击 测试 按钮可验证配置是否正确（使用示例查询 "latest AI research"）。审计日志会记录成功和失败的测试。

审计日志

所有搜索请求都会记录：

• 查询内容（脱敏处理：邮箱、token、密钥等敏感信息已替换）
• 状态：success、error 或 blocked（被速率限制）
• 结果数量
• 耗时（毫秒）
• 用户、项目、会话上下文

管理员可在配置页面查看最近的审计事件。

用户配置

若管理员允许，用户可在 个人设置 → 网络搜索 配置个人 API Key。

个人 Key 的优势

• 独立于系统配额的速率限制
• 使用自己的 Tavily 订阅等级

配置步骤

1. 从 tavily.com 获取 Tavily API Key
2. 进入个人设置页面
3. 输入 API Key
4. 保存更改

要移除个人 Key，清空字段后保存即可。

对话中的使用

网络搜索由 Agent 自动调用，无需用户显式触发。

示例提示词

• "量子计算领域最近有哪些进展？"
• "查找关于 CRISPR 基因编辑的最新论文"
• "搜索 React 19 新特性的文档"
• "当前 AI Agent 生态的发展现状如何？"

工具参数

Agent 可自定义搜索参数：

返回结构

每次搜索返回：

{
  "provider": "tavily",
  "query": "...",
  "answer": "AI 生成的答案摘要",
  "results": [
    {
      "title": "...",
      "url": "...",
      "snippet": "...",
      "score": 0.95,
      "published_date": "2026-03-01"
    }
  ],
  "response_time": 1.25
}

速率限制

• 按用户：由管理员配置（默认：20次/小时）
• 超额时：搜索返回错误，审计日志记录 blocked 状态
• 查询脱敏：敏感数据（邮箱、API token）在记录前已替换

故障排查

"Web search is disabled by the administrator"

联系管理员启用该功能。

"No Tavily API key is configured"

管理员必须配置系统 API Key，或你需添加个人 Key（若被允许）。

"Web search rate limit exceeded"

等待速率限制窗口重置，或请管理员增加配额。

搜索无结果

• 检查查询是否过于具体或有拼写错误
• 尝试使用 topic: news 搜索近期事件
• 在 tavily.com 验证 API Key 是否有效

安全说明

• API Key 在数据库中加密存储
• 搜索查询在审计日志记录前进行脱敏
• 凭证按作用域隔离（系统级或用户级）
• 速率限制防止滥用