Agent

class qveris.Agent(config: QverisConfig | None = None, agent_config: AgentConfig | None = None, llm_provider: LLMProvider | None = None, extra_tools: List[ChatCompletionFunctionToolParam] | None = None, extra_tool_handler: Callable[[str, Dict[str, Any]], Awaitable[Any]] | None = None, debug_callback: Callable[[str], None] | None = None, budget_credits: float | None = None)

Qveris agent orchestrator.

The agent runs an LLM/tool loop that can:

• discover capabilities via Qveris (discover),
• inspect candidate capabilities (inspect),
• call a selected capability (call),
• optionally execute additional user-provided tools (extra_tools + extra_tool_handler).

• 参数:
  • config -- Qveris API / agent runtime configuration (API key, base URL, max iterations, etc.).
  • agent_config -- LLM configuration (model name, temperature, additional system prompt, ...).
  • llm_provider -- Provider implementation that follows LLMProvider. If omitted, uses the built-in OpenAI-compatible provider (OpenAIProvider).
  • extra_tools -- Optional additional tool schemas (OpenAI ChatCompletionToolParam) exposed to the LLM. These are not executed by Qveris unless you also provide extra_tool_handler.
  • extra_tool_handler -- Async callback invoked for non-Qveris tool calls. Signature: async def handler(func_name: str, func_args: dict) -> Any.
  • debug_callback -- Optional callback used by QverisClient to emit debug messages (request/response logs, with authorization redacted).

备注

• A session id is created at construction time; call new_session() to reset it.
• This class is safe to reuse across multiple conversations; pass your own messages list.

async close() → None

Close network resources owned by the agent.

Call this when you are done with a long-lived Agent, or use the agent as an async context manager so cleanup happens automatically.

get_last_messages() → List[Message]

Return the latest conversation history produced by run(...).

The returned history includes intermediate assistant tool calls and tool results, plus the final assistant content when one was produced. If run(...) injected the default system prompt, that internal system message is omitted so callers can reuse the list directly.

budget_status() → Dict[str, Any] | None

Return the current budget state (limit / spent / remaining).

Returns None when no budget_credits was set. spent reflects pre-settlement charges from call responses; reconcile final charges with usage(...) / ledger(...).

async run(messages: List[Message], stream: bool = True) → AsyncGenerator[StreamEvent, None]

Run the agent loop and yield events as they occur.

This is the primary integration API. In streaming mode (stream=True), the underlying provider is expected to yield delta content chunks; in non-streaming mode, this method yields a single content event for the assistant message.

Tool calls are always surfaced as tool_call events, and tool executions as tool_result.

• 参数:
  • messages -- Conversation history (typically starts with role="user").
  • stream -- If True, yields content as delta chunks (streaming). If False, yields content as complete text (non-streaming).
• 生成器: StreamEvent objects for content, reasoning, reasoning_details, tool_call, tool_result, metrics, and error.

async run_to_completion(messages: List[Message]) → str

Run the agent in non-streaming mode and return the final assistant text.

This is a convenience wrapper around run(messages, stream=False) that discards all events except content and returns the concatenated text.

new_session() → str

Create and set a new session id.

The session id is forwarded to Qveris API calls (discover/call) and can be used server-side for correlation, tracing, and analytics.

class qveris.BudgetTracker(limit: float | None = None, warn_ratio: float = 0.8)

Track and enforce a per-session credit budget.

• 参数:
  • limit -- Maximum credits the session may spend. None disables the tracker entirely.
  • warn_ratio -- Emit a single warning once cumulative spend first reaches this fraction of limit (default 0.8).

备注

• Best-effort, not a hard cap: blocking uses the pre-call expected_cost estimate while spent accumulates the actual (possibly larger) charge, so a call estimated under-budget that charges more can push spent past limit. The guard is only as tight as discover / inspect coverage — a call whose cost was never observed cannot be estimated and is not blocked.
• The tracker is per-Agent session state, not per-run(). Don't share one Agent across concurrent run() calls if you rely on the budget: they share and race spent.

observe(result: Any) → None

Cache expected_cost per tool_id from a discover/inspect payload.

Accepts a dict or a pydantic SearchResponse.

estimate(tool_id: str | None) → float | None

Return the cached cost estimate for tool_id, if known.

check(tool_id: str | None) → Dict[str, Any] | None

Return a block payload if calling tool_id would exceed the budget.

Returns None (allowed) when the tracker is disabled, the cost is unknown (cannot estimate, so not blocked), or the projected spend is within the limit.

record(execution: Any) → Dict[str, Any] | None

Add the actual charge from a call result to cumulative spend.

Returns a warning payload the first time spend reaches warn_ratio * limit; otherwise None.

snapshot() → Dict[str, Any]

Return the current budget state (queryable, reconcilable with usage/ledger).