What the agent is given
The run hands the investigation to an agent session with three sources of evidence. The finding’s dossier, as files. What the classifier asserts, over what population, and since when; the classifier’s own numbers, verbatim; how that classifier measures and how its evidence reads, for every built-in classifier; and the tools the agent can call. The dossier is a snapshot taken at trigger time, so a report still reads correctly after the finding it analyzed has been resolved. A live connection back to your instance, over MCP (Model Context Protocol), authenticated with a short-lived key minted for the run and revoked when it ends. This is required rather than optional. The dossier states the claim, and every row of the evidence behind it is fetched on demand, so a run that cannot reach your instance cannot open a single trace it is investigating. Neither the triage agent nor the RCA agent copies trace rows into its prompt. Your repository, cloned at the connected integration’s default-branch head, when one is connected. Connect one under Settings → Git integration.What a connected repository changes
The repository is what turns “the outputs changed” into “this commit changed them”. It deepens every run that has one. The clone is at today’s head, which may be newer than the problem, so the agent is given the commit that was live when the problem started and reads the history from there. A project with no repository still gets an investigation, with a stated ceiling: it can show what happens in production and it cannot show what changed in the code. Its report says the code side was not read, and no cause points at a file or a commit. Connecting a repository is optional and is not required to complete setup, but it is the single largest difference in what a report can conclude.What the run is not told
The agent is never told that a triage pass happened on this finding, what it ruled, or what it wrote. Not the ruling, not its summary, not its citations, not the fact of its existence. This is enforced structurally rather than by convention, and in three places at once, because the run could otherwise read the ruling through the dossier, through its prompt, or through the same MCP tools it uses to read evidence. The reason is one conclusion Tessary wants to keep available: no cause found. Triage already applied a gate, and RCA is the only independent check on that gate. An investigation told what triage decided cannot provide it. The agent may read the other open findings and cases on the project, to see what else is moving. It never looks up its own finding or the case that holds it.How the run grades a cause
The run treats the finding as real and looks for why it happens. A cause is either a change over time, such as a commit, a prompt, a model, a tool, an upstream service, or the traffic, or a standing behavior of the agent, its code, its prompt, its tools, or its data. The agent is asked to consider every plausible cause and to try to disprove each one before it keeps it. It grades each cause on its own, against a legal standard of proof:
Anything weaker is not a cause. It goes on the ruled-out list with its reason. Several causes can be
high at once, and one flagged trace can belong to more than one cause. The size of the finding does not cap confidence: the standard of proof alone decides.
The agent compares only against baseline traces the finding itself recorded. Today only duration and cost drift against a pinned window record them. Every other finding is investigated from its flagged traces alone, and the agent does not fetch normal traffic to build a comparison of its own.
Each run has a time budget, stated in its instructions. When the budget runs short, the agent returns the causes it has at the confidence they earned and says in the written investigation what it did not check.
Where the run happens
Thesandbox-runner service spawns a fresh sandbox for every agentic run, and tears it down afterward. The backend itself holds no sandbox client and runs nothing customer-adjacent in its own process.
In a default self-hosted install, the sandbox is a fresh hardened container per request: all capabilities dropped, no new privileges, and its own bridge network. That is what the read-write Docker socket mount on sandbox-runner is for, and it is why the setup prerequisites ask you to check the socket’s group id as containers see it. Getting that wrong shows up as a run that never starts.
The agent needs both credentials and egress, since it clones a repository and calls a model provider. A transport failure, a non-zero exit, a timeout, or malformed output all reach the backend as a classified failure, never as a silent success.
What the run returns
A report, immutable once written. Every kind of case gets the same shape. A one-sentence summary of why the problem happens, written for a reader who was not watching. It is the line under the case in Triage. A verdict, one of two:
Up to four causes, each with its receipts, ranked
high first, then by how many flagged traces or sessions they explain. A cause has a short title and three plain-language parts: what changed, or what the agent does when the cause is a standing behavior; how that caused the problem; and what to do. It also names its kind, such as code, prompt, model, or traffic, and, with a connected repository, the file, commit, and excerpt behind it. The case page shows every cause with a High or Medium tag.
Every cause carries the trace and session identifiers that support it, and every identifier is checked against the finding’s own evidence. Anything the agent cites that the finding does not hold is dropped, and a cause left with nothing to cite is dropped too. If no cause survives, a causes_identified report is recorded as no_cause_found, with a note at the top of the written investigation saying why.
None of the plain-language parts carry trace identifiers, queries, or statistics. Those live in the identifiers, shown as links, and in the written investigation.
What else was checked: each candidate the agent ruled out, as one plain sentence with its reason.
A written investigation, in full, alongside the summary. It ends with an evidence audit, a table that ties each claim to the trace, session, commit, or query behind it, and with what would settle the question. It also lists every candidate the run could not check or did not reach.
Reports written before this shape keep their verdicts and render as they did:
behavior_change, model_change, traffic_shift, definition_change, and inconclusive, causes at low confidence shown as leads, and a checklist of measured checks.On a frustration case
A frustration finding cites the frustrated sessions, so a run on one counts and cites sessions. The agent is told that the flagged message marks where the user reacted, not the turn that prompted the reaction.On a groundedness case
A groundedness finding cites the traces with a flagged answer. The agent reads each flagged sentence and its score from the finding’s evidence, and the question and the retrieved documents from the trace. The agent is told that a flagged sentence is where the model saw no support in the documents, not proof that the sentence is wrong. On the case page, each cause has a button such as Show 12 answers that narrows the case’s Flagged answers list to the answers behind that cause. Run RCA on the case covers reading the report.What a run needs before it is useful
- A case to press it on. RCA analyzes the finding behind a case, so the chain from classifiers and findings through cases has to have produced one.
- An LLM (large language model) provider credential, under Settings → Providers. The sandboxed agent is the only analysis path there is, so a run has nothing to fall back to without one. On Tessary Cloud, a one-time model credit pays for RCA while you have no key of your own. Once it is used up, new runs need a key, and a run already in progress can finish. See Usage and credit.
- A reachable
sandbox-runnerservice. It starts by default in the self-hosting configuration. - A connected repository, for the runs that need to name a commit rather than describe a symptom.
Read next
Cases
Where the case an RCA run investigates came from, and how it closes.
How Tessary works
The whole chain, from an arriving trace to an explained case.