---
title: "See the whole multi-agent system — Retrace"
description: "Multi-agent observability: group runs into sessions, map hand-offs in a topology graph, and detect inter-agent failures like ping-pong loops."
canonical: "https://retraceai.tech/features/sessions"
last-updated: 2026-08-26
format: text/markdown
---

# See the whole multi-agent system

Group multi-turn runs into a single session, see how your agents hand off work in a topology graph, and automatically catch failure modes that only appear between agents.

## What it does

- **Sessions** — Runs that belong to the same conversation are grouped into a session, with totals for cost, tokens, and duration, so you can replay an entire multi-turn interaction.
- **Agent topology** — Tag spans with an agent id and role and Retrace builds a topology graph showing how work is ordered and handed off between agents.
- **Cross-run registry** — Each agent gets a profile across all your runs, so you can see how a given agent behaves over time, not just inside one trace.
- **Inter-agent detectors** — Automatically flag reasoning–action mismatch and task derailment between agents, plus deterministic ping-pong loops.
- **Trajectory checks** — Catch goal-drift and dropped early-turn context, failures that end-state checks miss entirely.
- **Single- and multi-agent** — Single-agent runs are untouched; the multi-agent analysis only engages when a run actually involves two or more agents.

## Examples

Tag each agent's work to build the topology graph.

```agent.py
import retrace

with retrace.agent("researcher", role="research"):
    findings = research_agent.run(task)

with retrace.agent("writer", role="writer", parent="researcher"):
    draft = writer_agent.run(findings)
```

TypeScript, withAgent scopes spans to an agent.

```agent.ts
import { withAgent } from "retrace-sdk";

withAgent({ id: "planner", role: "Planner" }, () => {
  return planAgent.run(task);
});
```


## REST API

- `GET /api/v1/sessions: list sessions`
- `GET /api/v1/sessions/:id: session detail`
- `GET /api/v1/sessions/:id/graph: agent topology graph`

## Related

- HTML page: https://retraceai.tech/features/sessions
- Documentation: https://docs.retraceai.tech
- OpenAPI specification: https://retraceai.tech/openapi.json
- Authentication for agents: https://retraceai.tech/auth.md