Skip to main content
A session in Aegis represents a single, continuous agent run, everything an agent does from the moment it starts a task to the moment it stops making tool calls. All actions within a run share a common session_id, which lets you view the complete history of what an agent did, in order, in one place. Sessions are created automatically; you do not configure or start them manually.

​
How sessions are created

When an agent makes its first MCP tool call through Aegis, Aegis records the session_id embedded in the call. Every subsequent call from the same agent run with the same session_id is grouped into that session. If an agent starts a new task and generates a new session_id, Aegis opens a new session automatically. You never need to declare or initialize a session. The aggregation happens on the backend as actions arrive.

​
Session fields

Each session surfaces the following information in the Aegis dashboard: The sum of allows, denies, rewrites, and approvals equals action_count.

​
Individual actions within a session

Drilling into a session shows each individual tool call as a row. Every action includes: Actions within a session are ordered by sequence_order, so you can follow the agent’s chain of reasoning step by step.

​
Viewing sessions in the dashboard

1

Open the Sessions page

Navigate to Dashboard → Sessions in the sidebar. The page lists all sessions, sorted by most recent activity. Each row shows the agent name, action count, start time, last activity time, and a summary of allow/deny/rewrite/approval counts.
2

Select a session

Click any session row to expand or navigate to its detail view. You will see the full list of individual actions in order, with their tool names, summaries, decisions, and blast radius ratings.
3

Inspect an action

Click an individual action row to see the full arguments, policy verdict, execution time, and any action pointers (human-readable bullet points that the backend generates for complex tool calls like PR creation).

​
How sessions relate to approvals

When an action in a session receives a REQUIRE_APPROVAL decision, the agent’s tool call does not return immediately. The session is effectively paused at that step, the agent waits for a human to act before it can continue. You review pending approvals from two places:
  • Dashboard home, the Pending approvals panel on the right side of the overview shows up to five queued actions. Each item displays the agent name, tool name, a plain-English summary, and Approve / Deny buttons.
  • Approvals page, navigate to Dashboard → Approvals to see the full list of all pending and historical approval requests.
When you click Approve, Aegis executes the held action immediately and returns the result to the waiting agent. The session then continues from where it paused. When you click Deny, Aegis sends an error back to the agent and discards the action. The agent receives a structured response indicating the action was denied and can decide how to proceed.
Multiple actions in the same session can be waiting for approval simultaneously if the agent made several qualifying tool calls in quick succession before any were reviewed.
The dashboard header badge shows the count of pending approvals across all sessions. Use it as a quick signal that an agent is waiting for you.