QVeris 文档

QVeris 是面向智能体的能力路由网络。客户端可以用自然语言发现能力，检查候选能力的参数 schema 与成本信号，然后用结构化参数调用选中的能力。

五分钟完成首次调用

这条路径使用公开 REST API，因为 SDK 与 MCP 集成都映射到同一条发现 -> 检查 -> 调用流程。

请将示例中的 srch_...、exec_...、led_... 替换为你自己 API 响应中返回的 ID。

1. 创建 API key

在控制台/API 密钥页面创建密钥，并且不要把它提交到代码仓库。

export QVERIS_API_KEY="qv_your_key"
export QVERIS_BASE_URL="https://qveris.cn/api/v1"
export QVERIS_SESSION_ID="quickstart-$(date +%s)"

2. 发现能力

Discover 免费。响应会返回 search_id 和排序后的候选能力。

curl -sS "$QVERIS_BASE_URL/search" \
  -H "Authorization: Bearer $QVERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "城市天气预报 API",
    "limit": 3,
    "session_id": "'"$QVERIS_SESSION_ID"'"
  }'

示例响应：

{
  "search_id": "srch_01HZX9QK7J3M9T",
  "total": 1,
  "results": [
    {
      "tool_id": "openweathermap.weather.execute.v1",
      "name": "当前天气",
      "provider_name": "OpenWeatherMap",
      "expected_cost": "每次成功请求 5 积分",
      "billing_rule": { "unit": "request", "amount_credits": 5 },
      "stats": { "avg_execution_time_ms": 210.7, "success_rate": 0.982 }
    }
  ],
  "remaining_credits": 995
}

请把返回的 search_id 和选中的结果放在一起保存。如果你在构建智能体，请把该结果的 tool_id、params 和 examples.sample_parameters 一起交给模型，不要让模型使用另一个工具的参数。

3. 检查候选能力

Inspect 也免费。在调用前，用它查看完整参数、示例、质量指标和最新 billing_rule。

curl -sS "$QVERIS_BASE_URL/tools/by-ids" \
  -H "Authorization: Bearer $QVERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_ids": ["openweathermap.weather.execute.v1"],
    "search_id": "srch_01HZX9QK7J3M9T",
    "session_id": "'"$QVERIS_SESSION_ID"'"
  }'

4. 调用能力

Call 可能消耗积分。使用 Discover 或 Inspect 返回的 tool_id，并基于同一个工具的 schema 构造 parameters。如果是智能体客户端，建议传入 model，这样失败调用可以关联到选择工具或生成参数的模型。

curl -sS "$QVERIS_BASE_URL/tools/execute?tool_id=openweathermap.weather.execute.v1" \
  -H "Authorization: Bearer $QVERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "search_id": "srch_01HZX9QK7J3M9T",
    "session_id": "'"$QVERIS_SESSION_ID"'",
    "model": "gpt-4o",
    "parameters": { "city": "北京", "units": "metric" },
    "max_response_size": 20480
  }'

示例响应：

{
  "execution_id": "exec_01HZX9R2R4S2E",
  "result": {
    "data": {
      "temperature": 15.5,
      "description": "局部多云"
    }
  },
  "success": true,
  "billing": {
    "summary": "每次成功请求 5 积分",
    "list_amount_credits": 5
  },
  "cost": 5,
  "remaining_credits": 990
}

5. 验证最终结算

Call 响应里的 billing 和 cost 是预结算信号。最终状态以调用历史和积分账本为准。

curl -sS "$QVERIS_BASE_URL/auth/usage/history/v2?execution_id=exec_01HZX9R2R4S2E" \
  -H "Authorization: Bearer $QVERIS_API_KEY"

curl -sS "$QVERIS_BASE_URL/auth/credits/ledger?entry_type=consume_tool_execute&limit=10" \
  -H "Authorization: Bearer $QVERIS_API_KEY"

成本语义

Discover 和 Inspect 免费。它们可能返回 expected_cost、cost 或 billing_rule，用于在 Call 之前估算成本。

Call 按所选能力的 billing_rule 计费。Call 响应可能包含简要 billing 和 cost，但调用历史与积分账本才是最终结算依据。

session_id 语义

建议在一次用户任务或会话中使用稳定的 session_id。目前它用于追踪、分析和计费上下文；它不是缓存合同，也不承诺 session_cache_hit。如果未来 API 增加显式缓存字段，会单独文档化。

失败调用排查

大多数集成失败来自少数几类原因：

• tool_id 没有完整复制 Discover 或 Inspect 的返回值。
• 工具来自旧缓存，或在当前区域不可用。
• 必填参数缺失、类型错误、枚举值错误、日期范围错误或代码格式错误。
• 客户端选择了一个工具，但用另一个工具的 schema 生成了参数。
• 账号缺少 OAuth、权限或区域访问。
• 参数已通过校验，但第三方 provider 返回上游错误。

审计和支持排查时，请同时保留 execution_id、search_id、session_id、tool_id 和 model。这些字段可以帮助 QVeris 区分问题来自搜索质量、智能体选工具、参数生成、平台校验，还是 provider 可用性。

集成方式

• REST API：REST API 参考
• 实践指南：常见 API 调用示例
• CLI：CLI 文档
• MCP：MCP Server 文档
• Python SDK：Python SDK

推荐智能体循环

1. 用能力级查询做 Discover，不要把最终工具参数直接当搜索词。
2. 当 schema 或成本重要时，Inspect 1 到 3 个候选能力。
3. 根据参数、success_rate、延迟、区域和 billing_rule 选择能力。
4. 使用该候选能力的 schema 生成结构化 parameters 后调用。
5. 如果由 LLM 选择工具或生成参数，请传入 model。
6. 用 execution_id、search_id 和 session_id 审计与排查。