> ## Documentation Index
> Fetch the complete documentation index at: https://apie.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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. `capture()` creates both in one call.

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

## Capture — one call, one run

`capture()` creates a session and run, executes your callback, marks it completed or failed, captures errors automatically, and flushes the event queue.

<CodeGroup>
  ```ts TypeScript theme={null}
  import ratri from "./ratri.config";

  await ratri.ready();

  await ratri.capture(
    async () => {
      // Your agent logic here
      // withTool, annotate, and track* calls inside here auto-resolve run context
    },
    { inputSummary: "Investigate production error rate spike" },
  );

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

  ```python Python theme={null}
  from ratri import Ratri

  ratri = Ratri.create()
  ratri.ready()

  ratri.capture(
      lambda: None,  # Your agent logic here
      {"input_summary": "Investigate production error rate spike"},
  )

  ratri.flush()
  ratri.shutdown()
  ```
</CodeGroup>

### 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

Use `captureHandler` / `capture_handler` to get a reusable function — each invocation creates its own run.

<CodeGroup>
  ```ts TypeScript theme={null}
  export const handleRequest = ratri.captureHandler(
    async (req: Request) => agent.run(await req.json()),
    { inputSummary: (req) => req.url },
  );
  ```

  ```python Python theme={null}
  handler = ratri.capture_handler(
      lambda req: agent_run(req),
      {"input_summary": lambda req: req.get("url", "Process request")},
  )
  ```
</CodeGroup>

**Best for:** API routes, queue workers, and scheduled jobs where one request equals one run.

## Manual run lifecycle

`capture()` is the recommended way to create runs — it starts, completes, and flushes automatically. Python additionally exposes a `ratri.runs` namespace for cases where you need to start a run outside of `capture()` (for example, a run whose completion depends on an external callback):

<CodeGroup>
  ```python Python theme={null}
  run = ratri.runs.start({"inputSummary": "Investigate production error rate spike"})

  try:
      # agent work
      ratri.runs.complete(run.id, {
          "status": "completed",
          "metadata": {"outputSummary": "Root cause identified."},
      })
  except Exception:
      ratri.runs.complete(run.id, {"status": "failed"})
      raise
  ```
</CodeGroup>

<Note>
  `ratri.runs` is a **Python-only** namespace. JavaScript has no public API to start a run outside `capture()` — use `capture()` for run creation. `ratri.completeRun(runId, options)` is available on both SDKs for completing a run early or from a run ID obtained elsewhere. See the [SDK API reference](/reference/sdk-api) for the full manual instrumentation surface.
</Note>

## Sessions — group related runs and pipelines

Use `kind: "pipeline"` (or `"multi_agent"`) on `capture()` when multiple runs belong to one workflow: a release gate pipeline, a support escalation, or an orchestrator delegating to workers.

<CodeGroup>
  ```ts TypeScript theme={null}
  await ratri.capture(
    async () => {
      // Orchestrator work — annotate(), withTool(), and handoff() inside
      // this capture share the same session automatically.
    },
    {
      kind: "pipeline",
      inputSummary: "Validate production rollout readiness",
    },
  );
  ```

  ```python Python theme={null}
  ratri.capture(
      lambda: None,  # Orchestrator work
      {
          "kind": "pipeline",
          "input_summary": "Validate production rollout readiness",
      },
  )
  ```
</CodeGroup>

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 |

See [Multi-agent pipelines](/observe/multi-agent-pipelines) for a full orchestrator/worker example with `handoff()`.

### 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.

## Next steps

<CardGroup cols={2}>
  <Card title="Instrument tool calls" icon="wrench" href="/observe/instrument-tool-calls">
    Add guarded tool calls inside a capture.
  </Card>

  <Card title="Multi-agent pipelines" icon="diagram-project" href="/observe/multi-agent-pipelines">
    Orchestrator and worker sessions.
  </Card>
</CardGroup>