Skip to main content
A run represents a complete execution of your agent system, from start to finish. When you call crew.kickoff(), Arzule creates a run that contains all traces generated during that execution.

​
Run vs trace

ConceptScopeExample
RunComplete executionOne crew.kickoff() call
TraceSingle execution pathOne agent’s work
SpanUnit of workOne tool call
EventAtomic actionTool call started
A single run typically contains one primary trace, but may include multiple traces if agents spawn parallel work.

​
Run lifecycle

Run Created
    │
    ├── run.start event
    │
    ├── Trace 1: Main crew execution
    │   ├── Agent 1 spans and events
    │   └── Agent 2 spans and events
    │
    ├── (Optional) Trace 2: Parallel work
    │   └── ...
    │
    ├── run.end event
    │
Run Complete

​
Creating runs

When you call arzule_ingest.init(), runs are created automatically: 
import arzule_ingest

arzule_ingest.init()

# Each kickoff creates a new run
result = crew.kickoff()  # Run 1
result = crew.kickoff()  # Run 2

​
Manual control

For more control, use the ArzuleRun context manager: 
from arzule_ingest import ArzuleRun
from arzule_ingest.sinks import JsonlFileSink

sink = JsonlFileSink("traces.jsonl")

with ArzuleRun(
    tenant_id="your-tenant-id",
    project_id="your-project-id",
    sink=sink
) as run:
    # Everything inside this block is part of this run
    result = crew.kickoff()
    
    # Access the run_id if needed
    print(f"Run ID: {run.run_id}")

​
Run metadata

Each run includes:
FieldDescription
run_idUUID identifying the run
tenant_idYour tenant identifier
project_idThe project this run belongs to
started_atTimestamp when the run began
ended_atTimestamp when the run completed
statusFinal status (success, error, etc.)

​
Viewing runs

In the Arzule dashboard, runs are the primary navigation unit. You can:
  • Filter runs by date range, status, or project
  • See run duration and event counts
  • Drill into individual traces within a run
  • Compare runs to identify regressions

​
Run isolation

Each run is isolated. Events from one run never mix with another, even if runs execute concurrently. This is guaranteed by:
  1. Unique run_id per execution
  2. Monotonic seq numbers within each run
  3. Thread-safe event collection

​
Next steps

Traces

Learn how traces structure data within runs.

ArzuleRun API

Full API reference for manual run control.