# Sessions

The Sessions view shows end-to-end session timelines for agent interactions. A session captures everything that happened between an agent and the systems it interacted with — gateway requests, guardrail evaluations, tool calls, and any associated browser activity.

Navigate to **Highflame Studio** → **Observatory** → **Sessions**.

***

## Session list

The session list shows recent sessions in reverse chronological order:

| Column           | Description                                             |
| ---------------- | ------------------------------------------------------- |
| **Session ID**   | Unique identifier for the session                       |
| **Started**      | When the session began                                  |
| **Duration**     | Total session duration                                  |
| **Agent**        | The agent identity (ZeroID) associated with the session |
| **User**         | The human user who initiated the session, if known      |
| **Turns**        | Number of conversation turns in the session             |
| **Events**       | Number of recorded events in the session                |
| **Violations**   | Number of threat events within the session              |
| **Max severity** | Highest severity threat seen in the session             |
| **Status**       | Active or completed                                     |

Filter sessions by time range, agent identity, user, source product, or violation count. Sessions with violations are highlighted.

***

## Session timeline

Click any session to expand its timeline. The timeline shows all events in the session in chronological order:

### Event types in the timeline

| Event type               | Source               | Description                                                           |
| ------------------------ | -------------------- | --------------------------------------------------------------------- |
| **Gateway request**      | Agent Gateway        | An inbound request received by the gateway                            |
| **Gateway response**     | Agent Gateway        | The response returned to the caller                                   |
| **Guardrail evaluation** | Shield SDK / Gateway | A guardrail policy evaluated against a prompt, tool call, or response |
| **Tool call**            | Shield SDK           | A tool invoked by the agent                                           |
| **Tool response**        | Shield SDK           | The result returned from a tool                                       |
| **Browser violation**    | Browser Security     | A browser-side event correlated into this session by user identity    |
| **Threat event**         | Any                  | A detection that fired during this session                            |

Each event in the timeline shows its timestamp, type, and a brief summary. Click any event to open the event detail panel.

### Guardrail results in the timeline

Guardrail evaluation events show:

* The policy evaluated
* The input evaluated (prompt, tool call, or response)
* The outcome: allow, block, or monitor
* Which rules matched, if any

### Timeline annotations

The timeline is annotated with:

* **Threat markers** — red indicators on events that contain or triggered a detection
* **Policy gap markers** — yellow indicators on Monitor-mode events that would not have been blocked

***

## Session detail panel

The session detail panel (opened by clicking a session row) shows:

* **Summary** — session metadata, agent identity, user, duration, products involved, source IDE
* **Agentic metrics** — turn count, cumulative risk score, loop detection flag, token budget status, total tokens in/out, total cost (USD), unique tools used
* **Timeline** — the full event sequence (described above)
* **Traces** — links to OpenTelemetry traces associated with this session. Each agent LLM call that was instrumented with the Shield SDK or passed through the gateway will appear as a trace entry.
* **Violations** — a filtered list of all threat events in this session, with links to the Threats view
* **Entity panel** — recent sessions and risk score for the agent and user involved

The agentic metrics are particularly useful for identifying runaway sessions: a high cumulative risk score with many turns, or a `loop_detected` flag, indicates a session that may be stuck or manipulated. `budget_exceeded` means the session consumed more tokens than its configured limit.

***

## Cross-product session correlation

Sessions are correlated across products using a shared session ID that flows through:

1. **Agent Gateway** — assigns a session ID to each inbound connection and propagates it in response headers and webhook payloads
2. **Shield SDK** — reads the session ID from the gateway response header (or generates one if the agent is not using the gateway) and attaches it to all SDK-emitted events
3. **Browser Security** — links violations to sessions by user identity when a violation occurs within the session's active time window

This means a single session can include gateway events, SDK guardrail evaluations, and browser-side violations from the same user, all visible in a unified timeline.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.highflame.ai/observatory/sessions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.