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 commonDocumentation Index
Fetch the complete documentation index at: https://docs.runaegis.co/llms.txt
Use this file to discover all available pages before exploring further.
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 thesession_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:| Field | Description |
|---|---|
session_id | The unique identifier for this agent run, generated by the agent |
agent_name | The name the agent reported when making tool calls |
action_count | Total number of MCP tool calls made in this session |
started_at | Timestamp of the first action in the session |
last_action_at | Timestamp of the most recent action, useful for identifying whether a session is still active |
repos | List of GitHub repositories that were touched during this session |
allows | Count of actions that received an ALLOW decision |
denies | Count of actions that were blocked with a DENY decision |
rewrites | Count of actions that were redirected via a REWRITE decision |
approvals | Count of actions that required or triggered a REQUIRE_APPROVAL decision |
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:| Field | Description |
|---|---|
tool_name | The GitHub MCP tool the agent called (e.g., push_files, create_pull_request) |
action_summary | A plain-English description of what the action would do |
decision | The outcome Aegis assigned: ALLOW, DENY, REWRITE, or REQUIRE_APPROVAL |
execution_time | How long the action took to evaluate and (if allowed) execute, in milliseconds |
blast_radius | Severity rating: Low, Medium, High, or Critical |
policy | The policy verdict, pass if all checks passed, or the enforced policy name if a rule fired |
arguments | The raw arguments the agent passed to the tool call |
target_repo | The repository the action targeted |
target_branch | The branch the action targeted, if applicable |
sequence_order, so you can follow the agent’s chain of reasoning step by step.
Viewing sessions in the dashboard
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.
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.
How sessions relate to approvals
When an action in a session receives aREQUIRE_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.
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.