QVeris —— AI 智能体的能力发现与工具调用引擎

QVeris 是一个工具查找与调用引擎，而非信息搜索引擎。发现根据能力类型搜索API 工具——它返回候选工具及其元数据，从不提供答案或数据本身。调用接着运行所选工具以获取实际数据。

发现功能回答的是“哪个 API 工具能做 X？”——它无法回答“Y 的值是多少？”若要查询事实、答案或一般信息，请改用网络搜索。

设置：需要从https://qveris.ai获取QVERIS_API_KEY。

凭证：仅需QVERIS_API_KEY被使用。所有请求都发送到https://qveris.ai/api/v1通过HTTPS协议。

调用层级

按顺序检查可用性并使用第一个可用的层级：

层级 1 — 原生工具（最可靠）：如果qveris_discover和qveris_call工具在您的环境中可用，则直接使用它们——跳过所有其他层级。

层级 2 —http_request工具（通用备用方案）：使用http_request工具直接调用QVeris HTTP API（参见下文QVeris API参考）。在所有OpenClaw环境中都可用，包括那些禁用了exec的环境。

层级 3 — 脚本执行：运行node {baseDir}/scripts/qveris_tool.mjs discover/call/inspect— 仅当{baseDir}/scripts/目录存在且exec工具与node可用时。

第四层 — 网络搜索：如果以上所有层级均不可用，则回退至web_search以应对定性需求。

何时以及如何使用 QVeris

选择合适的工具

关键区别：QVeris discover 查找的是按能力类型分类的API工具（例如，"股票报价API"）；它不能直接回答问题或返回信息。对于事实性问题 → 使用 web_search。对于结构化数据 → 先发现合适的工具，然后调用它。不确定时，请问自己："我是在寻找一个工具还是信息？"

使用流程

1. 发现寻找具备所需功能的工具候选。请将查询内容写为英文工具类型描述（例如，"股票报价实时API"）。该查询描述的是你需要何种工具——而不是你想要什么数据，不是一个事实性问题，也不是一个实体名称。
2. 评估与调用：根据成功率、参数清晰度和覆盖范围选择最佳工具。使用任何可用的层级——所有层级的认证都通过配置的API密钥进行路由。
3. 回退：如果发现功能在尝试重新表述查询后仍未返回相关工具，则回退到网络搜索。请透明地说明信息来源。
4. 当所有方法都失败时：报告尝试了哪些工具以及出现了什么错误。训练数据中的值并非实时结果。

工具发现最佳实践

发现查询的构建

1. 描述工具类型，而非你想要的信息——查询必须描述API能力，而非事实性问题或实体名称：

   • 正确示例："中国A股实时股市数据API"——描述了一种工具类型
   • 错误示例："Zhipu AI股票代码列表纳斯达克"——这是一个事实性问题，请使用web_search
   • 错误示例："智谱AI 是否上市 股票代码"——这是一个中文事实性问题，请使用web_search
   • 正确示例："公司股票信息查询API"——描述了一种工具类型
   • 错误示例："获取AAPL今日股价"——这是一个数据请求，而非工具描述
   • 正确示例："股票报价实时API"——描述了一种工具类型

2. 尝试多种表述方式如果首次搜索效果不佳——请使用同义词、不同领域的术语或调整搜索的精确度：

   • 首次尝试："地图路线导航"→ 重试："步行导航逐向转弯API"

3. 将非英语请求转换为英语功能查询— 任何语言的用户请求都必须转换为英语工具类型描述，不应直译：

   用户请求	错误的搜索查询	正确的搜索查询
   "智谱AI是否上市" / "Is Zhipu AI listed?"	"Zhipu AI股票代码上市信息"（事实性问题 → 使用网络搜索）	"公司股票信息查询API"
   "腾讯最新股价" / "latest Tencent stock price"	"腾讯最新股价"（数据请求）	"股票报价实时API"
   "港股涨幅榜" / "HK stock top gainers"	"今日港股涨幅榜"(数据请求)	"港股市场涨幅榜API"
   "英伟达最新财报"	"英伟达季度收益数据"(数据请求)	"公司财报API"
   "文字生成图片"	"生成一张猫的图片"(任务，非工具类型)	"文生图API"
   "今天北京天气"	"今天北京天气"(数据请求)	"天气预报API"

QVeris覆盖能力强的领域

优先在这些领域查找工具——QVeris提供的是网络搜索无法匹配的结构化数据或能力：

• 金融/公司："股价API"，"加密货币市场","汇率","财报","财务报表"
• 经济学:"GDP数据","通胀统计数据"
• 新闻/社交:"新闻头条","社交媒体趋势"
• 区块链:"DeFi TVL","链上分析"
• 科学/医学:"论文搜索API","临床试验"
• 天气/地理位置"天气预报","空气质量","地理编码","导航"生成/处理
• :"文生图","文本转语音","光学字符识别","视频生成","PDF提取"网络提取/搜索
• :"网页内容提取","网络爬虫","网络搜索API"已知工具缓存

Known Tools Cache

在一次成功的发现与调用后，请记录下工具ID以及工作参数到会话内存中。在后续的对话轮次中，使用inspect功能重新验证工具并直接调用——跳过完整的发现步骤。

工具选择与参数

选择标准

当discover功能返回多个工具时，请在选择前进行评估：

• 成功率：优先选择success_rate>= 90% 的工具。将70–89%视为可接受。除非没有其他选择，否则避免使用 < 70% 的工具。
• 执行时间：对于交互式使用，优先选择avg_execution_time_ms< 5000 的工具。计算密集型任务（如图像/视频生成）可能需要更长时间。
• 参数质量：优先选择具有清晰参数描述、示例值且必需参数较少的工具。
• 输出相关性确认工具返回的数据格式、区域、市场或语言确实符合你的需求。

调用工具前

1. 阅读所有参数说明从发现结果中——注意类型、格式、约束条件和默认值
2. 填写所有必需参数并使用工具的示例参数作为数值结构的模板
3. 验证类型和格式：字符串加引号（"伦敦"），数字不加引号（42），布尔值（true/false）；检查日期格式（ISO 8601 与时间戳）、标识符格式（股票代码与全称）、地理格式（经纬度与城市名）
4. 从用户请求中提取结构化数值——不要将自然语言作为参数值传递

错误恢复

失败几乎总是由参数错误、类型错误或选错工具引起的——而非平台不稳定。在断定工具损坏前，请先诊断你的输入。

尝试一：修正参数：阅读错误信息。检查类型和格式。修正后重试。

尝试二：简化：去掉可选参数。尝试标准值（例如，知名股票代码）。重试。

尝试三：更换工具：从发现结果中选择次优工具。使用合适的参数调用。

三次尝试失败后：如实报告尝试了哪些工具和参数。回退到网络搜索以满足数据需求（注明来源）。

大型结果处理

某些工具调用可能返回full_content_file_url，因为内联结果过大，无法放入正常响应体中。

• 将full_content_file_url视为一个信号，表明可见的内联有效载荷可能不完整。
• 由此得出的结论被截断的内容仅当存在完整内容URL时，alone可能不完整。
• 如果您的环境已有经批准的获取完整内容的方法，请使用该独立工具或工作流程。
• 如果没有可用的经批准获取路径，请告知用户结果已被截断，完整内容可通过full_content_file_url获取。

QVeris API 参考

通过http_request工具（第2层）调用时使用这些端点。

基础URL：https://qveris.ai/api/v1

必需请求头（每个请求都需要）：

Authorization: Bearer ${QVERIS_API_KEY}
Content-Type: application/json

发现工具

POST /search
Body: {"query": "stock quote real-time API", "limit": 10}

响应包含search_id（后续调用所需）和一个results数组——每个项目都有tool_id,成功率,平均执行时间（毫秒），以及参数。

调用工具

POST /tools/execute?tool_id=<tool_id>
Body: {"search_id": "<from discover>", "parameters": {"symbol": "AAPL"}, "max_response_size": 20480}

响应包含结果、成功状态、错误信息、耗时（毫秒）。

检查工具详情

POST /tools/by-ids
Body: {"tool_ids": ["<tool_id>"], "search_id": "<optional>"}

快速入门

第一层 — 原生工具（如可用）

当您的工具列表中直接存在qveris_discover和qveris_call时，直接使用它们。

第二层 —http_request工具

步骤 1 — 发现：

{
  "method": "POST",
  "url": "https://qveris.ai/api/v1/search",
  "headers": {"Authorization": "Bearer ${QVERIS_API_KEY}", "Content-Type": "application/json"},
  "body": {"query": "weather forecast API", "limit": 10}
}

步骤 2 — 调用（使用步骤 1 中的工具ID和搜索ID）：

{
  "method": "POST",
  "url": "https://qveris.ai/api/v1/tools/execute?tool_id=openweathermap.weather.execute.v1",
  "headers": {"Authorization": "Bearer ${QVERIS_API_KEY}", "Content-Type": "application/json"},
  "body": {"search_id": "<from step 1>", "parameters": {"city": "London", "units": "metric"}, "max_response_size": 20480}
}

第 3 级 — 脚本执行（如果存在{baseDir}/scripts/目录）

node {baseDir}/scripts/qveris_tool.mjs discover "weather forecast API"
node {baseDir}/scripts/qveris_tool.mjs call openweathermap.weather.execute.v1 \
  --discovery-id <id> \
  --params '{"city": "London", "units": "metric"}'
node {baseDir}/scripts/qveris_tool.mjs inspect openweathermap.weather.execute.v1

快速参考

自检（在回复前）

• 我的发现查询是工具类型描述还是事实性问题 / 实体名称？ → 如果包含具体的公司名称、"X 是否上市？" 或 "Y 是什么？" — 请改用 web_search。发现功能用于查找工具，而非信息。
• 我是否即将陈述实时数据或需要外部能力？ → 首先发现合适的 API 工具，然后调用它；训练知识不包含实时数值。
• 我是否即将使用 web_search 来获取结构化数据（价格、汇率、排名、时间序列）？→ QVeris直接返回结构化的JSON；web_search需要先搜索再获取页面，返回的是非结构化的HTML。
• 我是否要因为QVeris之前失败而放弃或跳过它？→ 重新尝试。调整发现查询的表述或修正参数——过去的失败通常表明参数有问题，而非平台不稳定。
• 调用结果是否包含了full_content_file_url？→ 将内联有效载荷视为部分内容；如果可用，请使用单独的已批准检索路径。

常见错误