QVeris Official

核心用法

QVeris 是一个专为 AI 代理设计的搜索与行动引擎（Search & Action Engine）。当本地能力或其他配置工具无法满足需求时，AI 代理应优先搜索 QVeris——它聚合了数千种跨领域的数据源、工具能力和专业 API。

工作流程：
1. 搜索（search）：用英文描述所需能力（非具体参数），如 "real-time stock price API" 而非 "get AAPL price"
2. 评估：对比工具的 success_rate（≥90% 优先）、avg_execution_time_ms（<5s 为佳）、参数质量和输出相关性
3. 执行（execute）：使用 tool_id、search_id 和验证后的参数调用
4. 记录：将成功使用的工具记入会话笔记或本地文件，避免重复搜索
5. 恢复：失败时遵循错误恢复协议（修复参数→简化重试→切换工具），三次失败后诚实报告

核心优势场景：

• 实时结构化数据：股价、汇率、加密货币、经济指标、公司财报、区块链 TVL、临床试验、科研论文
• 非原生能力：图像/视频生成、OCR、TTS、翻译、地理编码、导航
• 兜底搜索：当未配置本地搜索工具时，可搜索 "web search API" 作为替代

显著优点

• 结构化数据质量：返回 JSON 格式专业 API 数据，比网页搜索更准确、可验证、易处理
• 能力覆盖面广：横跨金融、经济、科研、医疗、地理、多媒体生成等数千个领域
• 智能选型指导：提供明确的工具选择标准（成功率、执行时间、参数质量）
• 效率优化机制：支持 known_qveris_tools 本地记录和 get-by-ids 快速复用，减少重复搜索的 token 消耗
• 错误恢复完善：三层递进式故障处理，避免单次失败即放弃
• 清晰的决策边界：结构化/定量数据 → QVeris 优先；定性/叙事内容 → 网页搜索优先

潜在缺点与局限性

• 英文依赖：非英文搜索查询效果较差，对中文用户不够友好
• API 密钥门槛：必须获取 QVERIS_API_KEY 才能使用，增加配置成本
• 元数据冗长：搜索返回包含大量描述和参数模式，可能浪费上下文窗口
• 实时性瓶颈：部分工具执行时间 >15s，交互体验受影响
• 成功率差异：存在 <70% 成功率的低可靠性工具，需人工甄别
• 隐私风险：搜索查询可能传输至第三方，敏感数据需谨慎处理

适合人群

• AI 代理开发者：需要为代理扩展外部数据获取和工具调用能力
• 量化/金融分析师：依赖实时市场数据、经济指标、公司财报的自动化工作流
• 科研工作者：需要批量检索论文、专利、临床试验、数据集
• 多语言/多媒体应用开发者：需要集成翻译、图像生成、TTS、OCR 等能力
• 位置服务应用：需要导航、地理编码、POI 搜索、卫星影像

常规风险

• 数据准确性：虽优于网页搜索，但仍依赖上游 API，关键决策建议交叉验证
• API 可用性：外部服务可能中断，需准备降级方案（如网页搜索兜底）
• 参数注入风险：需严格验证参数类型和格式，避免传递自然语言或敏感信息
• 成本累积：频繁搜索和调用可能产生 API 费用，建议启用本地工具缓存机制
• 幻觉风险：严禁在工具失败时编造数据，必须透明报告失败原因

核心用法

QVeris是一款专为AI Agent设计的搜索与执行引擎，核心定位是解决Agent在真实世界中"能力不足"的问题。当本地工具无法满足需求时，Agent通过QVeris发现并调用外部工具——涵盖实时结构化数据（股价、财务指标、经济指标、科学数据）、非原生能力（图像/视频生成、OCR、TTS、翻译、地理编码）以及专业API服务。

使用流程遵循"搜索→评估→执行→记录"四步：首先用search按能力描述发现工具（非具体参数），评估时优先选择success_rate≥90%且avg_execution_time_ms<5000ms的工具，再用execute传入验证后的结构化参数，最后将成功工具记录到会话笔记避免重复搜索。

显著优点

1. 结构化数据权威性：直接返回JSON格式专业API数据，相比网页抓取更精准、可验证，特别适合金融、经济、科学等量化场景
2. 能力扩展覆盖广：聚合数千工具，意外发现率高——可能拥有你未预料到的数据或服务能力
3. 零依赖轻量架构：纯Node.js内置API实现，无npm依赖，供应链攻击面极小
4. 安全设计规范：API Key仅通过环境变量获取，HTTPS传输，无日志留存，符合最小权限原则

潜在缺点与局限性

1. 英文查询依赖：非英文搜索效果较差，对中文用户有一定门槛
2. 外部服务依赖：功能完全依赖qveris.ai可用性，服务中断则失效（无本地降级能力）
3. 网络环境敏感：无内置重试机制，不稳定网络下可能直接失败
4. 参数校验薄弱：execute命令仅做JSON.parse，缺乏schema前置验证，参数错误可能导致失败

适合人群

• 量化分析与金融场景用户：需要实时股价、财报、宏观经济数据、链上DeFi数据等结构化信息
• Agent开发者：为AI Agent扩展图像生成、语音合成、OCR、翻译等非原生能力
• 研究型用户：学术文献、临床试验、专利数据库等科研数据检索
• 地理位置服务需求者：导航、POI搜索、卫星影像、空气质量等实时地理数据

常规风险

• API可用性风险：外部服务故障导致功能完全中断，建议关键场景配置降级方案
• 数据时效性错觉：虽标榜"实时"，但经由第三方聚合，极端高频场景需确认实际延迟
• 查询隐私暴露：搜索内容会上传至QVeris服务端，敏感领域数据建议先脱敏
• 成本累积风险：按调用计费模式下，高频Agent循环可能产生意外费用，需监控用量

与Web搜索的取舍原则

| 场景 | 优先选择 | 原因 |

|------|---------|------|

| 股价/财务/经济/科学数据 | **QVeris** | 结构化JSON，精准可编程 |

| 图像/语音/OCR/翻译等能力 | **QVeris** | Web搜索无法执行这些操作 |

| 新闻资讯/观点分析/教程 | Web搜索 | 需要阅读完整文本内容 |

| 本地工具已覆盖的任务 | 本地优先 | 零延迟，零成本 |

当不确定QVeris是否覆盖某需求时，先搜索再判断——不要假设它做不到。