QVeris 文档

什么是 QVeris#

QVeris 是面向智能体的能力路由网络。它让你的智能体能够：

发现（Discover） 能力（API、数据源、自动化任务），使用自然语言描述需求 — 免费
检查（Inspect） 候选能力，比较参数、成功率、延迟和价格
调用（Call） 任意能力，传入结构化参数，获取结构化结果

QVeris 在智能体循环中表现出色（发现 → 检查 → 调用 → 将结果反馈给模型），支持多种集成方式。

费用： 发现（Discover）免费。调用（Call）按能力的计费规则定价，最终结算结果可在调用历史和积分账本中查看。免费套餐含 1,000 积分。详情见定价页面。

快速开始#

QVeris 提供多种使用方式，选择最适合你的即可。

使用 QVeris CLI#

在终端中直接发现、检查和调用能力。

安装

curl -fsSL https://qveris.ai/cli/install | bash

也可通过 npm 安装（npm install -g @qverisai/cli）或免安装运行（npx @qverisai/cli）。

快速上手

qveris login                              # 登录认证
qveris discover "天气预报"                # 发现能力
qveris inspect 1                          # 查看详情
qveris call 1 --params '{"wfo":"LWX","x":90,"y":90}'  # 调用执行

CLI 还支持交互模式（qveris interactive）、代码生成（--codegen curl|python|js）和 Shell 自动补全。完整参考见 CLI 文档。

通过 MCP 使用 QVeris#

如果你的客户端支持 Model Context Protocol (MCP)，可以添加官方 QVeris MCP 服务器，立即获得：

discover（发现）
inspect（检查）
call（调用）

完整 MCP 参考文档见 MCP 服务器文档。

配置方式（Cursor / 任意 MCP 客户端）

{
  "mcpServers": {
    "qveris": {
      "command": "npx",
      "args": ["-y", "@qverisai/mcp"],
      "env": {
        "QVERIS_API_KEY": "your-api-key-here"
      }
    }
  }
}

试一试

"发现一个天气能力，获取东京的实时天气"

助手会：

调用 discover 发现匹配的能力（如"天气"）
可选调用 inspect 检查最佳候选
使用能力 ID 和参数调用 call

使用 QVeris Python SDK#

Python SDK 现在位于本单体仓库的 packages/python-sdk。安装已发布的包：

pip install qveris

完整指南（client、agent、类型化模型、集成方式）见 Python SDK。

设置环境变量：

QVERIS_API_KEY（在控制台/API密钥中创建）
OPENAI_API_KEY（或你的 OpenAI 兼容服务商密钥）
OPENAI_BASE_URL（可选；用于 OpenAI 兼容服务商）

Typed client 工作流：

import asyncio
from qveris import QverisClient
 
async def main():
    client = QverisClient()
    try:
        discovered = await client.discover("weather forecast API", limit=5)
        tool = discovered.results[0]
        inspected = await client.inspect([tool.tool_id], search_id=discovered.search_id)
        selected = inspected.results[0]
        result = await client.call(
            selected.tool_id,
            {"city": "北京"},
            search_id=discovered.search_id,
        )
        print(result.execution_id, result.success, result.billing)
    finally:
        await client.close()
 
asyncio.run(main())

最小流式示例：

import asyncio
from qveris import Agent, Message
 
async def main():
    agent = Agent()
    messages = [Message(role="user", content="发现一个天气能力，查询纽约的实时天气。")]
    async for event in agent.run(messages):
        if event.type == "content" and event.content:
            print(event.content, end="", flush=True)
 
if __name__ == "__main__":
    asyncio.run(main())

使用 QVeris TypeScript SDK#

TypeScript/JavaScript SDK 位于本单体仓库的 packages/js-sdk。安装已发布的包：

npm install @qverisai/sdk

这是一个零依赖的类型化客户端（原生 fetch，Node.js 18+）。完整指南（配置、API 参考、类型化响应、错误处理）见 TypeScript SDK。

import { Qveris } from '@qverisai/sdk';
 
const qveris = Qveris.fromEnv(); // 读取 QVERIS_API_KEY
 
const discovered = await qveris.discover('weather forecast API', { limit: 5 });
const tool = discovered.results[0];
const result = await qveris.call(tool.tool_id, {
  parameters: { city: 'London' },
  searchId: discovered.search_id,
});
console.log(result.execution_id, result.success, result.billing);

直接调用 QVeris REST API#

基础 URL

https://qveris.ai/api/v1

身份认证

在 Authorization 请求头中携带 API 密钥：

Authorization: Bearer YOUR_API_KEY

1）发现能力#

POST /search

cURL

curl -sS -X POST "https://qveris.ai/api/v1/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"query\":\"天气预报 API\",\"limit\":10}"

响应包含 search_id 和能力列表（每项含 tool_id、参数结构、示例等）。

Python

import os
import requests
 
API_KEY = os.environ["QVERIS_API_KEY"]
 
resp = requests.post(
    "https://qveris.ai/api/v1/search",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={"query": "天气预报 API", "limit": 10},
    timeout=30,
)
resp.raise_for_status()
data = resp.json()
print(data["search_id"])
print(data["results"][0]["tool_id"] if data.get("results") else None)

TypeScript

const apiKey = process.env.QVERIS_API_KEY!;
 
const resp = await fetch("https://qveris.ai/api/v1/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "天气预报 API", limit: 10 }),
});
 
if (!resp.ok) throw new Error(`HTTP ${resp.status}: ${await resp.text()}`);
const data = await resp.json();
console.log(data.search_id);
console.log(data.results?.[0]?.tool_id);

2）检查能力#

POST /tools/by-ids

调用之前，可以检查一个或多个能力，查看完整详情（参数、成功率、延迟等）。

cURL

curl -sS -X POST "https://qveris.ai/api/v1/tools/by-ids" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"tool_ids\":[\"openweathermap.weather.execute.v1\"],\"search_id\":\"YOUR_SEARCH_ID\"}"

Python

resp = requests.post(
    "https://qveris.ai/api/v1/tools/by-ids",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "tool_ids": ["openweathermap.weather.execute.v1"],
        "search_id": "YOUR_SEARCH_ID",
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

TypeScript

const resp = await fetch("https://qveris.ai/api/v1/tools/by-ids", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    tool_ids: ["openweathermap.weather.execute.v1"],
    search_id: "YOUR_SEARCH_ID",
  }),
});
 
if (!resp.ok) throw new Error(`HTTP ${resp.status}: ${await resp.text()}`);
const data = await resp.json();
console.log(data.results);

返回与 /search 相同的结构 — 包含完整能力详情、参数、示例和统计数据。

3）调用能力#

POST /tools/execute?tool_id={tool_id}

cURL（调用发现阶段返回的能力）

curl -sS -X POST "https://qveris.ai/api/v1/tools/execute?tool_id=openweathermap.weather.execute.v1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"search_id\":\"YOUR_SEARCH_ID\",\"parameters\":{\"city\":\"London\",\"units\":\"metric\"},\"max_response_size\":20480}"

若输出超过 max_response_size，响应会包含 truncated_content 和临时的 full_content_file_url。

Python

import os
import requests
 
API_KEY = os.environ["QVERIS_API_KEY"]
 
tool_id = "openweathermap.weather.execute.v1"  # 来自发现结果
search_id = "YOUR_SEARCH_ID"  # 来自 /search 响应
 
resp = requests.post(
    f"https://qveris.ai/api/v1/tools/execute?tool_id={tool_id}",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "search_id": search_id,
        "parameters": {"city": "北京", "units": "metric"},
        "max_response_size": 20480,
    },
    timeout=60,
)
resp.raise_for_status()
print(resp.json())

TypeScript

const apiKey = process.env.QVERIS_API_KEY!;
 
const toolId = "openweathermap.weather.execute.v1"; // 来自发现结果
const searchId = "YOUR_SEARCH_ID"; // 来自 /search 响应
 
const resp = await fetch(
  `https://qveris.ai/api/v1/tools/execute?tool_id=${encodeURIComponent(toolId)}`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      search_id: searchId,
      parameters: { city: "London", units: "metric" },
      max_response_size: 20480,
    }),
  }
);
 
if (!resp.ok) throw new Error(`HTTP ${resp.status}: ${await resp.text()}`);
const data = await resp.json();
console.log(data);

在 AI 智能体中安装 QVeris#

如果你正在配置 AI 编程助手（Claude Code、Cursor、OpenCode、Trae 等），可以将智能体安装指南连同你的 API 密钥一起提供给智能体。它会自动检测运行环境，并完成 MCP 服务器和技能定义的配置。

支持的环境：Claude Code、OpenCode、Cursor、Trae、VS Code、OpenClaw。

如何获取 API 密钥#

打开控制台/API密钥
登录 / 注册账号（免费，注册赠送 1,000 积分）
创建 API 密钥
使用方式：
- QVERIS_API_KEY 环境变量（MCP / Python SDK），或
- Authorization: Bearer ... 请求头（REST API）

开放生态#

QVeris 的核心引擎是托管服务。所有客户端工具（MCP 服务器、SDK、技能、插件）均为开源：

GitHub 组织：github.com/orgs/QVerisAI/repositories
ClawHub 技能：clawhub.ai/skills?q=qveris
npm 包：@qverisai
上游贡献：openclaw/openclaw、openclaw/clawhub

QVeris 文档

什么是 QVeris#

快速开始#

使用 QVeris CLI#

通过 MCP 使用 QVeris#

使用 QVeris Python SDK#

使用 QVeris TypeScript SDK#

直接调用 QVeris REST API#

1）发现能力#

2）检查能力#

3）调用能力#

在 AI 智能体中安装 QVeris#

如何获取 API 密钥#

推荐系统提示词#

开放生态#