4.8. Monitoring & Analytics¶

Squad provides real-time monitoring, detailed execution history, and analytics to help you understand how your agent teams perform.

Monitoring Dashboard¶

The squad monitoring dashboard is your control center during execution. It uses a six-tab layout to organize information:

Overview Tab¶

The Overview tab shows a summary of the squad's current state. When any agent across any squad is waiting for tool-execution approval, a pinned Waiting for Approval section appears at the top of the tab, above the hero stats. It aggregates pending requests from all squads in a single view so no approval goes unnoticed while you are watching a different squad.

Each row in the approval section shows the agent ID, the tool name requesting approval, and a risk badge (safe, low, medium, high, or critical). Clicking a row opens the approval dialog for that request. The section collapses automatically once all pending approvals are resolved.

Hero Stats¶

At the top of the dashboard, three key metrics are shown at a glance:

• Active / Total agents — How many agents are currently running out of the total configured
• Session tokens — Cumulative token consumption for the current session across all agents
• Execution phase — Current phase of the squad execution (idle, planning, executing, aggregating, etc.)

Agent Activity¶

Below the hero stats, the Agent Activity section shows all agents in the squad. A List/Grid toggle in the section header switches between two layouts.

List view renders agents as a flat, sortable list. Each row shows the squad name, agent name, status badge, and a live preview of the agent's current task. Rows are sorted by urgency: running agents first, then agents waiting for approval, then agents in error, then idle.

Grid view renders each agent as a card in a responsive grid (1 column on mobile, 2 on tablet, 3 on desktop). Each card shows the agent name, status, token usage, and last activity. The grid uses the same filter controls as the list view.

Both views share the same two filter controls:

• Name filter — Type to filter by agent name (150 ms debounce, case-insensitive).
• Status chips — Click a chip (Running, Waiting, Error) to show only agents in that state. Chips display a count badge and only appear when at least one agent matches the status.

Clicking any row or card navigates to the agent's detail view at /squad/{squadId}/agent/{agentId}.

When no agents are configured, an empty state message is shown. When filters are active but match nothing, a "no match" message appears instead.

Execution Timeline¶

Below the agent activity section, the Execution Timeline shows each agent's state transitions as horizontal swimlanes. Each colored block represents one transition, sized proportionally to how long the agent spent in that state.

Colors correspond to agent states: green for running, red for error, yellow/amber for created, blue for completed, and gray for idle. Hover over a block to see a tooltip with the state label, duration, timestamp, and error cause if applicable.

A time axis below the swimlanes shows relative timestamps from the earliest recorded event to now. When no state transitions have been recorded yet, a placeholder message appears and the timeline populates automatically as agents run.

Activity Feed¶

A chronological log of squad events, including:

• Agent session started/stopped
• Task assigned, started, completed, or failed
• Memory updated
• Workspace file changed
• Budget warnings and overages

The feed updates in real time and keeps the most recent 200 entries. The following event types appear in the feed:

• Agent started, completed, or errored
• Task created or completed
• Full execution completed

Budget Meter¶

The budget meter (shown at the top of the Overview tab) displays real-time progress toward the squad's configured token and cost limits. It animates while the squad is executing. See Budget & Safety for details on setting limits.

Chat Tab¶

The Chat tab provides a conversational interface for interacting with the squad. Use it to:

• Send a new task or question to the squad
• Monitor streaming responses from agents as they execute
• Review the conversation history for the current session

Task Board¶

The Task Board tab provides a Kanban-style view of all tasks in the current execution:

Each task card shows:

• Task title and assigned agent
• Priority level (color-coded)
• Dependencies on other tasks
• Result summary or error message (when applicable)

Click a task card to open the Task Detail panel with the full description, output, logs, and token usage.

Workspace Tab¶

The Workspace tab provides a file browser for the squad's workspace directory. You can:

• Browse directories and preview files created by agents
• View logs, plans, task outputs, and generated artifacts

Discussion Room Tab¶

The Discussion tab opens the Discussion Room for the squad — a structured, turn-based conversation space where the squad's agents take turns responding to a shared topic, with the orchestrator enforcing turn order and budget.

Creating a Discussion¶

Click New Discussion to open the creation dialog. Enter a topic (up to 1 024 bytes), choose a mode, and set a turn budget (1–100 turns per run cycle). Participants default to all squad agents but can be narrowed to a subset.

Discussion Modes¶

Two mode presets are available:

Strategy Selector¶

Below the mode toggle, an optional Strategy selector lets you override the engine the orchestrator uses to pick the next speaker. When set to Default, the mode determines the engine automatically. Explicit options:

The Default setting (no explicit override) maps Moderated mode to the Moderator strategy and Brainstorm mode to the Autonomous strategy. Setting an explicit strategy overrides this mapping for the lifetime of the room (until the user resets it to Default or the room is stopped).

Discussion Status¶

A status badge reflects the orchestrator's state machine: idle, running, paused, awaiting user, completed, cancelled, or error. The controls at the top of the room (Start, Pause, Resume, Stop) map directly to the allowed transitions.

User Injection¶

While a discussion is running you can type a message in the input box and inject it into the agent turn queue. The message is delivered at the next turn boundary. Up to 10 messages may be queued at once. Queued messages appear in a strip above the input box; click the cancel icon on any entry to dequeue it before it is consumed.

Termination and Automatic Completion¶

A discussion ends when any of the following conditions is met:

• The turn budget is exhausted (status transitions to awaiting user; the user may inject a message to re-arm another budget cycle).
• The user clicks Stop (status: cancelled, reason: UserStopped).
• The consensus gate fires: in Moderated mode the facilitator agent is asked every 3 turns whether the group has converged. If it reports high confidence (≥0.8) the room transitions to completed with reason ConsensusReached.
• The idle watchdog fires: a room that has had no new message and no queued input for 5 minutes auto-completes with reason IdleTimeout.
• A room parked in awaiting user with no queued messages for 10 minutes auto-completes with reason BudgetExhausted.

The termination reason is shown as a status badge on the discussion card in the History panel.

Conclusion Synthesis¶

Once a discussion has at least one message, click Synthesize Conclusion in the Phase 3 panel to trigger an LLM call against the facilitator agent. The facilitator reads the full transcript (or a head-plus-tail excerpt for very long discussions) and returns a structured conclusion with four sections: a short summary, key points, decisions, and action items (each with an optional suggested owner). The conclusion is persisted on the room and rendered in a card below the transcript. You can re-synthesize at any time — each call overwrites the previous conclusion in place.

Handoff to Squad Execution¶

After a conclusion is synthesized, click Start Execution to hand the discussion outcome off to the squad's execution engine. The backend assembles the topic, summary, decisions, and action items into a request string and submits it to submit_squad_request. The request string is capped at 8 kB so it never trips the execution planner's length validator. A success notification shows the new execution's ID; click it to navigate to the execution view.

The Auto-approve toggle (default: off) controls whether the planner's decomposition goes straight to execution or pauses for your review.

Transcript Export¶

Click Export and choose a format:

The downloaded file is named discussion-{short-id}-{sanitized-topic}.{ext}. The topic fragment is limited to 40 alphanumeric characters.

Discussion Analytics¶

The Phase 3 panel shows a per-discussion analytics card with:

• Total messages and agent turns
• Per-agent turn count and token usage (prompt + completion)
• Total transcript token usage
• Synthesis token usage (separate from the transcript total, so you can see what the conclusion call cost)
• Discussion duration (only shown once the room is in a terminal status)
• Strategy change history (which strategy was active at each turn)

Discussion History¶

The left sidebar of the Discussion Room lists all completed, cancelled, and error rooms for the squad, newest first. Each card shows the topic, status badge, termination reason, participant count, message count, and timestamps. Click a card to load the full transcript and conclusion in the main panel. The list is paginated (up to 50 entries per page) and refreshes automatically after a room reaches a terminal status.

Analytics Tab¶

The Analytics tab combines the Execution History and the Analytics Dashboard.

Execution History¶

The Execution History panel lists all past executions for the squad:

• Search by request text or plan title
• Filter by status (completed, failed, cancelled)
• View summary: request, task count, token usage, duration

Click an entry to expand the execution detail drawer showing:

• Original request and generated plan
• Task-by-task results and artifacts
• Per-agent token usage breakdown
• Execution logs filterable by agent and severity
• Duration from start to completion

Generating Reports¶

Click Generate Report on any execution to produce a Markdown summary that includes:

• Execution overview (request, status, duration)
• Plan summary with task list
• Results from each task
• Token usage statistics
• Artifacts produced

Reports are saved to the workspace and can be shared with your team.

Analytics Dashboard¶

The Analytics Dashboard aggregates data across multiple executions to reveal performance trends.

Available Metrics¶

• Total executions — Count of completed, failed, and cancelled executions
• Success rate — Percentage of executions that completed successfully
• Average duration — Mean execution time in milliseconds
• Total tokens — Cumulative token consumption

Token Usage by Agent¶

A breakdown showing how tokens are distributed across agents. Identify which agents consume the most resources and whether the distribution matches expectations.

Daily Usage¶

A bar chart showing execution count and token usage per day, useful for spotting usage trends over time.

Period Selection¶

Filter analytics by time period:

• Day — Last 24 hours
• Week — Last 7 days
• Month — Last 30 days
• All — All recorded history