Qveris

QVeris API client.

示例

import { Qveris } from '@qverisai/sdk';

const qveris = new Qveris({ apiKey: process.env.QVERIS_API_KEY! });

const found = await qveris.discover('stock price market data API', { limit: 5 });
const tool = found.results[0];

const outcome = await qveris.call(tool.tool_id, {
  searchId: found.search_id,
  parameters: { symbol: 'AAPL' },
});

构造函数

构造函数

new Qveris(config): Qveris

参数

config

QverisClientOptions

返回

Qveris

访问器

rateLimitRetryCount

Getter 签名

get rateLimitRetryCount(): number

How many times the client has backed off on a rate-limited (429) / transient (503) response so far. Rate-limit backoff is retried pressure, not failure — observe this rather than counting the retried responses.

返回

number

方法

call()

call(toolId, options): Promise<ExecuteResponse>

Call a capability. The response may include pre-settlement billing; final charges are reflected in usage() and ledger().

参数

toolId

string

options

CallOptions

返回

Promise<ExecuteResponse>

credits()

credits(): Promise<CreditsResponse>

Get current credit balance and bucket details.

返回

Promise<CreditsResponse>

discover()

discover(query, options?): Promise<SearchResponse>

Discover capabilities from a natural-language query. Free.

参数

query

string

options?

DiscoverOptions = {}

返回

Promise<SearchResponse>

inspect()

inspect(toolIds, options?): Promise<SearchResponse>

Inspect capabilities by id to get current parameter schemas. Free. An empty id list resolves locally without a network request.

参数

toolIds

string | string[]

options?

InspectOptions = {}

返回

Promise<SearchResponse>

ledger()

ledger(filters?): Promise<CreditsLedgerResponse>

Query final credits ledger entries.

参数

filters?

CreditsLedgerRequest = {}

返回

Promise<CreditsLedgerResponse>

probe()

probe(toolId, options?): Promise<ProbeResponse>

Validate candidate parameters and request a zero-cost quote without executing the capability.

参数

toolId

string

options?

ProbeOptions = {}

返回

Promise<ProbeResponse>

usage()

usage(filters?): Promise<UsageEventsResponse>

Query request-level usage audit history.

参数

filters?

UsageHistoryRequest = {}

返回

Promise<UsageEventsResponse>

fromEnv()

static fromEnv(overrides?): Qveris

Create a client from the QVERIS_API_KEY environment variable. An explicit baseUrl override takes priority over QVERIS_BASE_URL.

参数

overrides?

Omit<QverisClientOptions, "apiKey" | "credentialProvider">

返回

Qveris

核心工作流与失败行为

先从 Discover 返回值选择能力，按当前 schema 构造参数；参数由 Agent 生成、schema 较复杂或成本敏感时先 Probe，再 Call。认证、限流重试耗尽和请求校验错误会抛出 SDK 错误；Call 的业务失败还应检查响应中的 success 与错误字段。search_tools、get_tools_by_ids 和 execute_tool 仅为兼容别名，新代码应使用 discover、inspect、probe 和 call。

const found = await qveris.discover("weather data for a city");
const tool = found.results[0];
if (!tool) throw new Error("No matching capability");
await qveris.inspect(tool.tool_id, { searchId: found.search_id });
const parameters = { q: "London" }; // Build from the inspected params schema.
await qveris.probe(tool.tool_id, { parameters, checks: ["schema", "quote"] });
const result = await qveris.call(tool.tool_id, { parameters, searchId: found.search_id });
if (!result.success) throw new Error(result.error_message ?? "Capability call failed");