Starter documentation.

Overview

JeraViz Trace records what an AI agent does as it runs: each model request, tool call and handoff, with timing, token counts and an estimated cost. You open an execution and see its trace; you open the analytics and see how executions behave over time.

Core concepts

An execution is one run of an agent workflow. Its trace is a tree of spans. Each span has a kind:

• agent: one agent's turn; contains the work it did.
• model request: one call to a language model, with model name and token counts.
• tool call: one call to a function or API, with arguments, result and any error.
• handoff: delegation from one agent to another, linking the two agent spans.

ticket-resolution                     execution (root)
├─ triage-agent                       agent
│  └─ classify-ticket                 model request
├─ retrieval-agent                    agent       ← handoff
│  ├─ vector_search                   tool call
│  ├─ kb_lookup                       tool call
│  └─ synthesize-context              model request
└─ refund-agent                       agent       ← handoff
   ├─ plan-refund                     model request
   ├─ orders_api.get_order            tool call
   ├─ payments_api.create_refund      tool call
   └─ compose-reply                   model request

Illustrative sample trace used throughout this site.

Quickstart (preview)

The intended first-run path. Steps 1 and 2 are what you would write; the rest happens in the dashboard.

1. 1. Connect your AI application

   Add the SDK (or point an OpenTelemetry exporter at JeraViz) and a project API key. No change to your agent architecture.

2. 2. Capture execution events

   Model requests, tool calls and handoffs are recorded as spans and sent in the background, so instrumentation does not block your agent.

3. 3. Inspect traces and behavior

   Open any execution to see the timeline, inputs, outputs, errors, tokens and estimated cost for each step.

4. 4. Improve performance and reliability

   Find the slow or failing step, fix it, and watch the trend change. Evaluations to lock in gains are on the roadmap.

# Illustrative: not a published SDK
import jeraviz

jeraviz.init(
    api_key="YOUR_API_KEY",
    project="support-copilot",
    environment="staging",
)

@jeraviz.agent("refund-agent")
def handle_refund(ticket):
    # Each tool call becomes a span with arguments, result, duration and errors.
    with jeraviz.tool("payments_api.create_refund", args={"order_id": ticket.order_id}) as call:
        result = payments.create_refund(ticket.order_id)
        call.set_result(result)
    return result

What is captured

Capture modes

Full

Stores prompts, responses, tool arguments and results (subject to size limits and redaction rules).

Metadata only

Stores timing, status, tokens and names, but no payload text. Recommended for sensitive workloads.

Hashed payloads

Stores a hash of each payload so identical inputs can be recognized without storing the text.

How cost is estimated

For each model request: input tokens × input price + output tokens × output price, using a model price table. The total for an execution is the sum over its model requests.

• Costs are estimates and are labelled as such. They are not invoices.
• Requests for models missing from the price table are shown as unpriced, never as zero.
• Prices on this site's previews belong to fictional models and are for demonstration only.

What exists today

Glossary

Execution

One logical run of an agent workflow, from trigger to outcome. The unit you see in the explorer and the unit planned for usage metering.

Trace

The record of all spans in one execution, linked by a trace id. Compatible with the OpenTelemetry trace model.

Span

A timed operation inside a trace. Kinds: agent, model request, tool call, retrieval, handoff, and custom.

Model request

A span for one call to a language model, with model name, token counts, latency and an estimated cost.

Tool call

A span for one invocation of a function or API by an agent, with arguments, result and any error.

Event

A point-in-time record on a span, such as an exception or a retry. Events have no duration.

Project / environment

A project holds one application. Environments such as staging and production keep their data separate.

Workspace

The team boundary: members, projects, limits and billing.