Agents & Runs

Learn how AgentVista organizes your observability data around named agents and individual runs.

AgentVista organizes all observability data around two core entities: agents and runs. An agent is the named entity you track; a run is one execution of that agent.

What is an agent?

An agent is a named entity in AgentVista that groups all traces produced by a particular piece of logic. It might be a customer support bot, a lead qualification pipeline, a code review assistant, or any other automated workflow you want to observe independently.

Agents are created automatically. The first time you send a trace with a new agent_name, AgentVista registers that agent in your account. There is nothing to provision or configure in advance — just start sending data.

import agentvista

agentvista.init(api_key="av_xxxxx")

# The agent "lead-qualifier" is created on first run if it doesn't exist yet
@agentvista.trace_agent("lead-qualifier")
def qualify_lead(data):
    ...

Each agent is scoped to your account. Two accounts can both have an agent named "support-bot" without any conflict. Within your account, agent names are unique — sending traces with the same agent_name always groups them under the same agent.

The agent_name you pass to @trace_agent or agentvista.run() is the agent’s display name in the dashboard. Choose a name that describes what the agent does, not how it’s implemented.

What is a run?

A run is synonymous with a trace — one complete execution of your agent from start to finish. Every time your decorated function is called, or every time a with agentvista.run(...) block executes, AgentVista records a new run.

Each run captures:

• When it started and ended
• How long it took (duration_ms)
• Whether it succeeded (success)
• What the outcome was (outcome)
• Every span (LLM calls, tool calls, DB queries) inside it
• Total token usage and cost across all LLM spans

Agent statistics

The dashboard computes the following statistics across all runs for each agent:

Metric	Description
Total runs	Count of all traces recorded for this agent
Success rate	Percentage of runs where success = true
Average cost per run	Mean of total_cost_usd across completed runs
Total cost	Sum of total_cost_usd across all runs
p95 latency	95th percentile of duration_ms across completed runs

These statistics update as new runs arrive. You can filter by time range to see how your agent is performing over a specific period.

Creating runs

You have two ways to create a run, depending on how much control you need.

Decorator

Use @agentvista.trace_agent when you want zero-friction instrumentation. Wrap your agent function and every call becomes a run automatically.

import agentvista

agentvista.init(api_key="av_xxxxx")

@agentvista.trace_agent("support-bot")
def handle_ticket(ticket_id: str) -> dict:
    # Every call to handle_ticket() is recorded as a run under "support-bot"
    response = process_ticket(ticket_id)
    return response

You can also use @agentvista.trace_agent without a name — the agent name defaults to the function name:

@agentvista.trace_agent
def support_bot(ticket_id: str) -> dict:
    # Agent name becomes "support_bot"
    ...

The decorator records the run as failed automatically if an unhandled exception propagates out of the function.

Context manager

Use with agentvista.run(...) when you need to set an outcome or control the run’s lifecycle explicitly:

import agentvista

agentvista.init(api_key="av_xxxxx")

def qualify_lead(lead_data: dict) -> str:
    with agentvista.run("lead-qualifier") as r:
        result = run_qualification_pipeline(lead_data)

        if result.score > 0.8:
            r.set_outcome(success=True, outcome="qualified")
        else:
            r.set_outcome(success=False, outcome="unqualified")

        return result.recommendation

r.set_outcome() attaches success and outcome to the trace when the context manager exits. If you don’t call set_outcome(), those fields are left blank on the trace.

Record (v1 API)

For simple cases where you don’t need span-level detail, agentvista.record() creates a minimal single-span trace in one call:

agentvista.record(
    agent="lead-qualifier",
    success=True,
    outcome="qualified",
    cost=0.043,
    duration_ms=1200,
)

Multiple agents

You can track as many agents as you need — there is no limit on the number of agents per account. Each agent appears as a separate entry in the dashboard and is tracked independently.

@agentvista.trace_agent("support-bot")
def handle_support(ticket): ...

@agentvista.trace_agent("lead-qualifier")
def qualify_lead(lead): ...

@agentvista.trace_agent("code-reviewer")
def review_pr(diff): ...

Agent comparison

The dashboard lets you place two agents side-by-side to compare:

• Success rate — which agent is more reliable?
• Average cost per run — which is more efficient?
• p95 latency — which is faster?

This is useful when you’re evaluating a new prompt version, a different model, or a redesigned workflow against your current production agent.

Use distinct, descriptive agent names when running A/B experiments — for example "support-bot-v1" and "support-bot-v2". This keeps the comparison clean and lets you retire the old agent once you’ve validated the new one.