Skip to main content
Sessions records every conversation with an agent. Open it from the sidebar to see what an agent did on a run, how long each turn took, which tools and subagents it used, and where something went wrong.

The sessions list

Every session is listed newest first. Each row shows the opening message, when it ran, how many turns it took, and its total duration. Use the agent and time window filters at the top (the last 30 days by default) to narrow the list to recent activity or to a single agent. Runs started by a schedule appear here too, marked Scheduled run and showing the agent that ran.
The Agent Sessions list showing recent runs, each with its opening message, time, turn count, and duration, with the Agents filter open on an All and a per-agent option and an empty detail pane reading Select a session to view details

Agent Sessions: recent runs with their turn count and duration, filterable by agent and time window.

Session detail

Click a session to open it. The detail view has three parts.

Summary metrics

A row of totals for the whole session: Turns, Duration, Tokens, Context, Tool calls, Sub-agents, and Errors. It summarizes the run at a glance.

Event timeline

A timeline across the run, colored by event type, such as System, User, Model, Tool call, and Sub-agent. It shows how the run’s time was spent, so a slow model call, a long-running tool, or parallel subagents are easy to spot.

Turn-by-turn transcript

Below the timeline, each turn is listed with its own token count and duration, the user message, and an Agent steps entry you can expand to see the tool calls the agent made and how they resolved. Together they make it easy to pinpoint where a run failed, whether a turn was cancelled, an MCP server errored, or a tool returned nothing useful.
A session detail view with summary metrics (turns, duration, tokens, context, tool calls, subagents, errors), an event-type timeline, and the turn-by-turn transcript with expandable agent steps

A session opened for inspection: summary metrics, the event timeline, and the turn-by-turn transcript.

Resuming a run

Each session carries a copyable session ID, and the detail header has a button to resume it, which reopens the conversation so you can continue it.
In hosted mode with login enabled, session history is owner-scoped: each user’s list shows only their own sessions. Sessions others share with you open from their share link. In local mode there is a single shared identity, so all sessions belong to that one user.

Sharing a session

The creator of a session can share it, read-only, with specific people or with everyone in their tenant.
Sharing with specific people needs a user directory, which TrueForge has when it runs on the TrueFoundry platform. In local mode and with OIDC login, you can share with everyone in the tenant only, and the people search is hidden.

Share from the UI

Open the session and click Share.
  • Add people: search by name or email under Add people by name or email, then invite them. Each person you add is listed with a remove action.
  • General access: choose Restricted (only people you added) or Everyone within your tenant.
  • Share URL: copy the link and send it to the people you shared with.

What people you share with can do

Opening the share link shows a read-only view of the session: its summary metrics, event timeline, and transcript. They can’t send messages, resume the run, edit or delete the session, download sandbox files, or change who it’s shared with. Shared sessions don’t appear in their sessions list, so they open them from the link. Changes to access take effect immediately. While general access is Everyone within your tenant, everyone in the tenant can still open the session, including people you removed. Switch to Restricted to limit it to the people you added.

Share from the SDK

Grants are managed with Update session grants, which adds and removes access in one request, and listed with List session grants. Look up the people to share with through List users.
Revoking a person doesn’t remove access they have through a tenant grant, so revoke the tenant too when you want only specific people to have access. Only the session creator can change or list grants. GET /api/v1/capabilities reports session_sharing.granularity: subject when sharing with specific people is available, tenant when only tenant-wide sharing is.