Trace runs and sessions

Wrap agent work in runs and sessions so every invocation appears in the Ratri dashboard.

You want every user request, job, or handler invocation to show up as a traceable unit in the dashboard. A run is that unit. A session groups related runs — especially in multi-agent pipelines.

When you finish this page, each agent invocation will create a run with a start time, input summary, and completion status.

Runs — one invocation, one trace

A run represents a single piece of agent work: processing a user message, handling a webhook, or executing a scheduled job.

TypeScript

import ratri from "./ratri.config";

await ratri.ready();

await ratri.withRun(
  { inputSummary: "Investigate production error rate spike" },
  async (run) => {
    // Your agent logic here
    // run.id is available for withTool, track*, etc.
  },
);

await ratri.flush();
await ratri.shutdown();

withRun / with_run:

• Creates a run via POST /v1/runs
• Executes your callback
• Marks the run completed or failed
• Captures errors automatically
• Flushes the event queue before completing

What you’ll see

A new run in the dashboard with your inputSummary, start/end timestamps, and status (completed or failed).

HTTP handlers and workers

Wrap request handlers so every incoming request gets its own run.

TypeScript

export const handleRequest = ratri.wrap(
  async (req: Request) => agent.run(await req.json()),
  { inputSummary: (req) => req.url },
);

ratri.wrap() is JavaScript-only. In Python, use run_context or with_run.

Manual run lifecycle

For fine-grained control, start and complete runs explicitly:

TypeScript

const run = await ratri.runs.start({
  inputSummary: "Investigate production error rate spike",
});

try {
  // agent work
  await ratri.runs.complete(run.id, {
    status: "completed",
    metadata: { outputSummary: "Root cause identified." },
  });
} catch (error) {
  await ratri.runs.complete(run.id, { status: "failed" });
  throw error;
}

Sessions — group related runs

Use sessions when multiple runs belong to one workflow: a release gate pipeline, a support escalation, or an orchestrator delegating to workers.

TypeScript

await ratri.withSession(
  {
    kind: "pipeline",
    inputSummary: "Validate production rollout readiness",
  },
  async (session) => {
    await ratri.withRun(
      { sessionId: session.id, inputSummary: "Orchestrator step" },
      async (run) => {
        // Orchestrator work — run.id, session.id available
      },
    );
  },
);

Session kinds:

Kind	Use when
single_agent	One agent, multiple steps in one session
multi_agent	Multiple agents collaborating
pipeline	Orchestrator → worker handoffs with ordered steps

What you’ll see

A session replay timeline in the dashboard showing all runs and events in order. Open the session replay URL from send-test-event to see an example.

If runtime intelligence is enabled for your workspace, Ratri can also generate a readable session story after the session has enough evidence. The story adds a summary, grouped timeline, action items, and guardrail recommendations while keeping the raw event timeline available as the source of truth.

See Runtime intelligence for how generated stories relate to raw events and guardrail decisions.

Next steps

Instrument tool calls

Track what tools your agent invokes inside a run.

Runtime intelligence

Understand generated session summaries, timelines, action items, and recommendations.

Multi-agent pipelines

Model orchestrator → worker handoffs.