Sessions, runs and observability
When an agent does something surprising, the answer is almost always in the transcript. Everything an agent runs is recorded as a session, and the inspector shows the whole thing, including the parts the chat window hides.
Every execution is a session
A session is one conversation or one triggered execution. It is stamped at creation with the surface that started it, and that stamp is what the inspector groups and badges by. It never changes afterwards, so provenance survives even when a conversation runs for weeks.
| Origin | What started it |
|---|---|
dashboard | The floating chat window in the app. |
wizard | A session the Agnt Wizard started while building. |
slack | A Slack channel, thread or DM. |
imessage | A text from a confirmed phone binding. |
schedule | A scheduled fire. Background work. |
webhook | An inbound webhook. Background work. |
queue | A queue item being drained. Background work. |
inbox | Email triage escalating, or a reminder sweep. Background work. |
agent | Another agent dispatching work down. Background work. |
mcp_probe | An MCP client driving the agent with the session tools. |
Sessions split into two kinds. Conversations have a human on the other end and deliver their reply back to the surface they came from. Work sessions are headless: they run and bill but never post anywhere, which is why a schedule firing overnight does not text you its output. No work session appears in the conversation list; the ones started by a schedule or a webhook also get a row on the Runs tab.
Everything, including what chat hides
The Sessions tab shows every event in a session, not the cleaned-up version. That includes the runtime context the chat surface suppresses: the session preamble, memory retrieved at the start of a turn, the responses to approval requests, and results injected back from sub-agents. This is usually where a confusing answer becomes obvious, because you can see what the agent was actually given.
read-only on purpose
One row per fire
The Runs tab is the audit log for triggered work: one row per schedule or webhook fire, joined to the schedule name so you can tell which one fired. Each row deep-links to the transcript of the work session it produced. Queue, inbox and inter-agent work sessions are not trigger runs and do not appear here — read them in the inspector instead.
| Status | Meaning |
|---|---|
dispatched | The trigger fired and a session was started. |
failed | The dispatch itself failed. The row carries the error. |
skipped | The trigger fired but was deliberately not dispatched. |
A scheduled run whose schedule was later deleted keeps its row. It still tells you what happened, which is the point of an audit log.
The read-only family
Every tool below is read-only. They grant no authority the caller does not already have, which is why they are the family a monitoring agent gets: one agent summarizing the others on a daily schedule, or an agent reading its own past sessions to work out why a tool call failed.
| Tool | What it returns |
|---|---|
agnt_observability_list_agents | Enumerate agents before inspecting any of them. |
agnt_observability_list_sessions | Recent sessions for an agent, with status and linked trigger metadata. |
agnt_observability_search_sessions | Search by free text, status or tool name, or filter to problematic sessions only: the ones carrying an error event or a failed tool result. |
agnt_observability_read_session | One session, progressively. A compact per-event index first with errors expanded inline, then grep the bodies, fetch specific events, or page backward from a failure. |
agnt_observability_list_trigger_runs | Recent schedule and webhook fires with their dispatch status and the session each produced. |
agnt_observability_get_session_usage | Compute and credits for one session or one agent, broken down by category. |
agnt_observability_list_escalations | Blocking human-in-the-loop requests: gated tool-call approvals and escalated questions. |
agnt_observability_get_diagnostics | A compact health report: deploy state, dependency checks, recent sessions, trigger failures, escalations, usage and open config requests. |
agnt_observability_check_dependencies | Whether the agent actually has what its config implies: integrations, connectors, remote MCP connections, workspace database, code execution. |
agnt_observability_read_config_request | A config-change request the runtime raised, with the session context that prompted it. |
separate from the session tools
agnt_agents_session_poll returns status only, never message content. Reading the transcript is agnt_observability_read_session, which lives in this family and is enabled independently of the session tools.Start with the index rather than pulling a whole transcript. A default read_session call returns a per-event index with errors already expanded, which is normally enough to find the failure and then fetch only those events.
What that run actually cost
Compute is attributed down to the session, so "the agent is expensive" becomes a specific answer: agnt_observability_get_session_usage scopes to one session or one agent, and agnt_usage_sessions ranks sessions across the workspace so the costly ones surface on their own.
Agent compute is paid from the AI wallet, which is separate from the data wallet that pays for data calls. The Usage page in the dashboard shows both. See usage and credits and wallets.