Reference

SDK reference

Everything you can do from the CLI, you can do from Python. The package installs as vesper-ai but imports as vesper. The public API is four top-level names.

Export	Description
`vesper.tool`	Decorator that turns a Python function into a tool the agent can call.
`vesper.load`	Load a deployed agent's active manifest from the registry by name.
`vesper.Agent`	The agent class. Build one from a YAML manifest with `Agent.from_manifest`.
`vesper.RunResult`	The object returned by `agent.run()`, with content, cost, tokens, and more.

Defining tools

Decorate any function with @vesper.tool. Vesper reads the signature to build the JSON schema the model sees: type hints (str, int, float, bool) map to parameter types, and any parameter without a default becomes required. The description(or the function's docstring) tells the model when to reach for it.

import vesper

@vesper.tool(description="Get the current stock price for a ticker symbol")
def get_stock_price(ticker: str) -> str:
    prices = {"AAPL": 187.42, "TSLA": 241.05, "MSFT": 419.13}
    price = prices.get(ticker.upper())
    if price is None:
        return f"No price found for {ticker}."
    return f"{ticker.upper()} is trading at ${price}"

Loading an agent

Load a deployed agent's active manifest straight from the registry by name. Tools listed in the manifest's entryPoint are wired up automatically.

import vesper

agent = vesper.load("researcher")          # active manifest from the registry
result = agent.run("What is the price of AAPL?")

print(result.content)
print(result.cost, result.prompt_tokens, result.completion_tokens)

Or build an agent directly from a YAML file and register tools programmatically, which is handy for tests and one-off scripts where nothing is deployed yet.

from vesper import Agent, tool

@tool(description="Look up an order by id")
def get_order(order_id: str) -> dict:
    return {"id": order_id, "status": "shipped"}

agent = Agent.from_manifest("agent.yml", tools=[get_order])
print(agent.run("Where is order 1234?").content)

The RunResult object

agent.run() returns a RunResultwith the model's answer plus full cost and usage accounting for that run.

Field	Type	Description
`content`	str	The agent's final text response.
`cost`	float \| None	USD cost of the run (None if the model has no pricing entry).
`prompt_tokens`	int	Total input tokens across the tool-calling loop.
`completion_tokens`	int	Total output tokens generated.
`session_id`	str \| None	The session thread this run belongs to (for `scope: session` agents).
`alerted`	bool	True when the run's cost crossed the manifest's `alertAt` threshold.

Stateful sessions

Pass a sessionid to keep a stateful, multi-turn thread. The second call below sees the first turn's history, so the agent can resolve "it" without you resending context.

agent.run("What is RAG?", session="proj-42")
agent.run("Compare it to fine-tuning", session="proj-42")   # sees the first turn

Inspecting run history

Every run, whether completed or budget-aborted, is recorded to the audit log. agent.runs() returns them newest-first.

for r in agent.runs():
    print(r.run_id, r.status, r.cost, r.created_at)

Budget enforcement

When a manifest sets budget.maxCostPerRun, a run that would exceed the cap stops and raises BudgetExceededError, and the partial run is still logged to the audit trail. Crossing alertAt instead simply flags result.alerted.

from vesper.exceptions import BudgetExceededError

try:
    result = agent.run("Write a very long report")
    if result.alerted:
        print("Heads up: this run crossed the cost alert threshold.")
except BudgetExceededError as e:
    print(f"Run stopped to protect your budget: {e}")