QVeris Python SDK

异步 Python SDK，让你在自己的 Agent 和应用中发现、检查、调用并审计 10,000+ 真实已验证的 API 能力。

SDK 提供两种控制粒度：

• QverisClient —— QVeris REST API 的轻量类型化封装（discover、inspect、call、usage、ledger）。
• Agent —— 开箱即用的 LLM 工具循环，让模型自主发现并调用能力。

需要完全控制时用 client；想几行代码就跑起来一个可用助手时用 agent。

安装

pip install qveris

需要 Python 3.8+。运行时依赖：httpx、pydantic、pydantic-settings、openai。

身份认证

SDK 从环境变量 QVERIS_API_KEY 读取 API 密钥。本页示例默认连接 https://qveris.cn/api/v1；如需指向自定义端点，可用环境变量 QVERIS_BASE_URL 或 QverisConfig(base_url=...) 覆盖。请设置：

export QVERIS_API_KEY="your-api-key"
export QVERIS_BASE_URL="https://qveris.cn/api/v1"

在控制台/API 密钥获取密钥。也可以显式传入配置：

from qveris import QverisClient, QverisConfig

client = QverisClient(QverisConfig(
    api_key="your-api-key",
    base_url="https://qveris.cn/api/v1",
))

快速开始

核心流程是 discover（发现）→ inspect（检查）→ call（调用），之后可选 audit（审计）。所有方法都是 async。

import asyncio
from qveris import QverisClient, QverisConfig

async def main():
    client = QverisClient(QverisConfig(base_url="https://qveris.cn/api/v1"))
    try:
        # 1. 用自然语言发现能力（免费）
        discovered = await client.discover("天气预报 API", limit=5)
        tool = discovered.results[0]

        # 2. 检查所选能力，获取完整参数
        inspected = await client.inspect([tool.tool_id], search_id=discovered.search_id)
        selected = inspected.results[0]

        # 3. 调用（可能消耗积分）
        params = (
            selected.examples.sample_parameters
            if selected.examples and selected.examples.sample_parameters
            else {"city": "上海"}
        )
        result = await client.call(
            selected.tool_id,
            params,
            search_id=discovered.search_id,
            max_response_size=20480,
        )
        print(result.success, result.result)

        # 4. 审计最终扣费结果
        usage = await client.usage(execution_id=result.execution_id, summary=True)
        ledger = await client.ledger(summary=True, limit=5)
        print(usage.total, ledger.total)
    finally:
        await client.close()

asyncio.run(main())

QverisClient 持有一个 HTTP 连接池。用完务必 await client.close()（建议放在 finally 中）。

若已设置 QVERIS_BASE_URL=https://qveris.cn/api/v1 环境变量，可直接 QverisClient()，无需再传 base_url。

Agent（智能体）

Agent 把同一套流程封装成一个 LLM 工具循环。模型会拿到 discover、inspect、call 三个工具并自行决定何时调用。

默认 agent 使用 OpenAI 兼容的 provider。配合国内可用的 OpenAI 兼容服务时，设置：

export OPENAI_API_KEY="..."
export OPENAI_BASE_URL="https://your-openai-compatible-endpoint/v1"   # 你的 OpenAI 兼容服务地址

QVeris API 地址仍由 QVERIS_BASE_URL 控制，与 LLM provider 相互独立。

流式

import asyncio
from qveris import Agent, Message, QverisConfig

async def main():
    async with Agent(config=QverisConfig(base_url="https://qveris.cn/api/v1")) as 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)

asyncio.run(main())

Agent 是异步上下文管理器 —— async with Agent() as agent: 会自动释放网络资源。

仅要最终文本

只需要最终回答时：

async with Agent(config=QverisConfig(base_url="https://qveris.cn/api/v1")) as agent:
    answer = await agent.run_to_completion(
        [Message(role="user", content="找一个股票报价能力并查询 AAPL。")]
    )
    print(answer)

事件类型

Agent.run(messages) 产出 StreamEvent 对象。通过 event.type 区分：

type	含义
content	助手文本（流式时为增量分片，否则为完整消息）
reasoning / reasoning_details	部分 provider 的推理 token / 结构化推理
tool_call	模型正在调用 discover / inspect / call（或你的额外工具）
tool_result	工具调用的执行结果（event.tool_result 含 name、result、is_error）
metrics	provider 上报的 token 用量 / 耗时
error	终止本次运行的致命错误

给 run(...) 传 stream=False 可改为接收完整助手轮次而非增量分片。

配置参考

QverisConfig

字段	环境变量	默认值	说明
api_key	QVERIS_API_KEY	None	API 密钥，以 Authorization: Bearer ... 发送
base_url	QVERIS_BASE_URL	https://qveris.cn/api/v1	API 基础地址
enable_history_pruning	—	True	裁剪/压缩旧的工具输出以节省 token（agent 循环）
max_iterations	—	50	agent 工具循环的最大迭代次数

AgentConfig

字段	默认值	说明
model	gpt-4o	传给当前 LLM provider 的模型名
additional_system_prompt	None	追加到默认工具使用系统提示词之后
temperature	0.7	在 provider 支持时透传

from qveris import Agent, QverisConfig, AgentConfig

agent = Agent(
    config=QverisConfig(base_url="https://qveris.cn/api/v1", max_iterations=20),
    agent_config=AgentConfig(model="gpt-4o", temperature=0.2),
)

API 参考

QverisClient

方法	REST 端点	用途
discover(query, limit=20, session_id=None)	POST /search	用自然语言发现能力（免费）
inspect(tool_ids, search_id=None, session_id=None)	POST /tools/by-ids	获取能力完整元数据（免费）
call(tool_id, parameters, search_id=None, session_id=None, max_response_size=None)	POST /tools/execute	执行能力（可能消耗积分）
usage(**filters)	GET /auth/usage/history/v2	审计请求状态与扣费结果
ledger(**filters)	GET /auth/credits/ledger	查看最终积分余额变动
handle_tool_call(func_name, func_args, session_id=None)	—	把 LLM 工具调用桥接到对应的 QVeris 方法
close()	—	关闭底层 HTTP 客户端

tool_ids 接受单个字符串或可迭代对象。usage(...) 和 ledger(...) 接受仅关键字过滤参数，如 start_date、end_date、summary（默认 True）、bucket、charge_outcome、execution_id、search_id、direction、entry_type、min_credits、max_credits、limit、page、page_size。

仍保留向后兼容别名：search_tools → discover，get_tools_by_ids → inspect，execute_tool → call。

Agent

成员	说明
run(messages, stream=True)	产出 StreamEvent 的异步生成器；主集成 API
run_to_completion(messages)	非流式；返回最终助手文本
get_last_messages()	上一次 run(...) 的对话历史，含工具调用/结果
new_session()	重置关联/会话 id
close()	释放网络资源（或用 async with）

构造函数：Agent(config=None, agent_config=None, llm_provider=None, extra_tools=None, extra_tool_handler=None, debug_callback=None)。

类型化模型

SDK 返回 Pydantic v2 模型，因此你能获得自动补全与校验。未知的后端字段会被保留，因此较新的 API 元数据不会破坏较旧的 SDK 客户端。

• 发现 / 检查：SearchResponse → results: list[ToolInfo]；ToolInfo 含 tool_id、name、description、params: list[ToolParameter]、examples、stats、billing_rule。
• 调用：ToolExecutionResponse，含 execution_id、success、result、error_message、billing（CompactBillingStatement）、cost、remaining_credits。
• 调用审计：UsageHistoryResponse → items: list[UsageEventItem]、total、summary。
• 积分账本：CreditsLedgerResponse → items: list[CreditsLedgerItem]、total、summary。

from qveris import ToolExecutionResponse

def explain(result: ToolExecutionResponse) -> str:
    if not result.success:
        return f"失败：{result.error_message}"
    charged = result.billing.summary if result.billing else "无计费信息"
    return f"成功（{charged}）；剩余={result.remaining_credits}"

集成方式

按你的应用选择合适的粒度：

• 直接使用类型化 client —— 在自己的代码里调用 discover/inspect/call/usage/ledger。
• 内置流式 agent —— Agent.run(messages) 并消费 StreamEvent。
• 内置非流式 agent —— Agent.run(messages, stream=False)，获取完整轮次与事件。
• 仅要最终文本 —— Agent.run_to_completion(messages)。
• 自带循环 —— 把 QVeris 工具 schema 暴露给你自己的 LLM provider，再把工具调用路由回 client：

from qveris import QverisClient, QverisConfig
from qveris.client.tools import DISCOVER_TOOL_DEF, INSPECT_TOOL_DEF, CALL_TOOL_DEF

tools = [DISCOVER_TOOL_DEF, INSPECT_TOOL_DEF, CALL_TOOL_DEF]
client = QverisClient(QverisConfig(base_url="https://qveris.cn/api/v1"))

# ... 你的 LLM 产出一个工具调用 (func_name, func_args) ...
result, is_error, handled = await client.handle_tool_call(func_name, func_args)
if handled and not is_error:
    ...  # 把 result 回传给模型

自定义 LLM provider

默认 Agent() 使用内置的 OpenAI 兼容 provider。如需对接其他模型 API，实现 LLMProvider 并传入：

from typing import AsyncGenerator, List
from openai.types.chat import ChatCompletionToolParam
from qveris import Agent
from qveris.config import AgentConfig
from qveris.llm.base import LLMProvider
from qveris.types import ChatResponse, Message, StreamEvent

class MyProvider(LLMProvider):
    async def chat_stream(self, messages: List[Message], tools: List[ChatCompletionToolParam], config: AgentConfig) -> AsyncGenerator[StreamEvent, None]:
        ...

    async def chat(self, messages: List[Message], tools: List[ChatCompletionToolParam], config: AgentConfig) -> ChatResponse:
        ...

agent = Agent(llm_provider=MyProvider())

错误处理

• HTTP 错误抛出 httpx.HTTPStatusError；业务失败信封抛出 RuntimeError。
• 在 agent 循环内部，provider/传输错误不会抛出 —— 它们以 error 类型的 StreamEvent 暴露并结束本次运行。run_to_completion(...) 会将其重新抛为 RuntimeError。
• result.success 只反映能力调用本身。不要把它当作最终扣费结论 —— 用 usage(...) / ledger(...) 确认扣费。

示例

可运行示例位于 packages/python-sdk/examples/：

示例	场景
finance_research.py	股票报价 / 市场数据研究
risk_compliance.py	制裁、负面舆情、合规筛查
crypto_market.py	加密货币价格与成交量数据
data_analysis.py	用外部能力数据丰富数据集
agent_loop_integration.py	LLM agent 循环集成

设置 QVERIS_API_KEY 后，能力示例会运行 discover/inspect；仅当设置 RUN_QVERIS_CALLS=1 时才执行 call。运行前请确保已设置 QVERIS_BASE_URL=https://qveris.cn/api/v1。

兼容性

• Python >=3.8。
• 公开方法与 Pydantic 模型字段尽量遵循增量兼容。
• 规范方法替代上线后，弃用别名至少保留一个小版本。
• 破坏性变更需要主版本号升级并附迁移说明。

链接

• 包：PyPI 上的 qveris
• 源码：packages/python-sdk
• REST API：rest-api.md
• 获取 API 密钥：控制台/API 密钥