API & configuration

Everything the SDKs accept, every environment variable, and the raw ingest contract if you want to send traces without an SDK.

SDK initialization

Python

vorlo_trace.init(
    api_key="vrlo_...",        # or VORLO_API_KEY
    server_url="https://...",  # or VORLO_SERVER_URL (defaults to production)
    agent_name="order-agent",  # shown in the dashboard
    verify_ssl=True,           # VORLO_VERIFY_SSL=false for local proxies
    redact=my_scrubber,        # optional: scrub PII before anything is sent
)

JavaScript / TypeScript

vorlo.init({
  apiKey: 'vrlo_...',          // or VORLO_API_KEY
  serverUrl: 'https://...',    // or VORLO_SERVER_URL (defaults to production)
  agentName: 'order-agent',
  redact: (text) => text,      // optional: scrub PII before anything is sent
});

Environment variables

Ingest endpoints

The SDKs speak a small JSON contract — you can implement it from any language. Authenticate with Authorization: Bearer vrlo_....

POST /v1/trace — one step

{
  "session_id": "abc123",          // your run id — groups steps
  "agent_name": "order-agent",
  "api_key": "vrlo_...",
  "step": {
    "step_number": 1,              // 1-based, ordered
    "tool_name": "stripe_charge",
    "tool_type": "ACTUATOR",       // or "SENSOR"
    "input": "{\"amount\": 100}",
    "output": "",
    "error": "HTTP 403 Forbidden", // null/empty when status = success
    "status": "failed",            // "success" | "failed"
    "latency_ms": 412,
    "cost_tokens": 123,
    "reasoning": "Agent decided to charge the card because ...",
    "trace_id": "...", "span_id": "...", "parent_span_id": ""
  }
}

POST /v1/session — lifecycle events

{
  "session_id": "abc123",
  "api_key": "vrlo_...",
  "event_type": "session_complete",  // session_start | session_complete | session_error
  "agent_name": "order-agent",
  "status": "success",               // optional; session_error implies failed
  "total_steps": 5,
  "duration_ms": 8214,
  "output": "Refund processed."
}

Send session_start when a run begins and session_complete / session_errorwhen it ends — that's what powers the live Running status and wall-clock duration in the dashboard.

Failure diagnosis fields

Failed steps may include an error_diagnosisobject from the SDK's local registry; otherwise the server diagnoses server-side:

"error_diagnosis": {
  "code": "stripe_auth_error",
  "title": "Stripe authentication failed",
  "plain_english": "...",
  "root_cause": "...",
  "fix_hint": "...",
  "severity": "critical"        // info | warning | critical
}