Understand

Understand is the first move of the Trust Loop. Once an agent is connected, every run lands as a trace. AISquare extracts the reasoning behind it, so you see why the agent decided what it did, not just what it returned. A transcript tells you what was said. The reasoning graph tells you what the agent believed, what it leaned on, and how it got from one to the other.

Your agent's reasoning, as a graph

This is one refund-agent run, laid out as the graph AISquare records. It shows the question, the context the agent fetched, the evidence and the one assumption it leaned on, the policy it cleared, and the decision it reached. Drag the canvas to pan, scroll to zoom, and follow the solid line for the timeline and the dashed lines for what each step produced and consumed.

Read it over the API

Everything the graph above shows is also a plain HTTP read, so your own tooling (a script, a CI job, a coding agent) can pull the same reasoning the dashboard renders. Three calls cover this page: list the runs, fetch the graph, fetch the reasoning.

export EXPLAINABILITY_GATEWAY_URL="https://<your-workspace>.aisquare.studio"
export EXPLAINABILITY_API_KEY="AIS_..."        # studio API key
export STUDIO_ID="<your-studio-id>"

curl -s -H "X-API-KEY: $EXPLAINABILITY_API_KEY" \
  "$EXPLAINABILITY_GATEWAY_URL/v1/studios/$STUDIO_ID/ui/runs?limit=10"

{
  "status": "ok",
  "total_count": 66,
  "runs": [
    {
      "run_id": "8b41f0c2f4a340d2b7f9d3e6a1c25b90",
      "status": "ready",
      "agent_name": "refund-agent",
      "title": "Refund Agent · Aug 19 09:12",
      "started_at": "2026-08-19T09:12:41Z",
      "duration_ms": 1840.0,
      "node_count": 6,
      "error_count": 0
    }
  ],
  "next_offset": 10
}

The run id is the trace id your agent logged, so an agent that just finished a run can jump straight to its own record.

Request parameters for the run list:

The most useful response fields (the response carries more):

Two more reads return the two views on this page:

curl -s -H "X-API-KEY: $EXPLAINABILITY_API_KEY" \
  "$EXPLAINABILITY_GATEWAY_URL/v1/studios/$STUDIO_ID/runs/$RUN_ID/graph"
curl -s -H "X-API-KEY: $EXPLAINABILITY_API_KEY" \
  "$EXPLAINABILITY_GATEWAY_URL/v1/studios/$STUDIO_ID/runs/$RUN_ID/rml"

{
  "extraction_confidence": 0.86,
  "claims": [
    "The refund is within policy limits.",
    "No manual review is required for this order."
  ],
  "inference_chain": [
    {
      "reasoning": "Order total $39 is under the $50 auto-approve ceiling.",
      "conclusion": "Amount is inside the auto-approve limit."
    }
  ],
  "assumptions": [
    {
      "proposition": "Customer tier resolved to standard",
      "depends_on": "tier was inferred, not confirmed"
    }
  ]
}

/graph returns nodes and edges. Each node has an id, a type (llmNode, toolNode, retrieverNode, chainNode, agentNode), and a data object with the step's model_name, duration_ms, token_count, cost_usd, and span identifiers, the same facts the step cards below show. /rml/v3 is the newer structured document, and its findings.results[] entries carry the fingerprints the Fix write path accepts. Analyses are extracted asynchronously after a run lands, so a 404 here means "not computed yet", not "failed"; give it a minute and read again.

Reasoning response fields:

Prefer tools over raw HTTP? The learnings MCP server wraps every read on this page for Claude Code, Cursor, and any MCP-capable coding agent.

A run is a graph, not a transcript

Each run is recorded as a graph of steps. A step is one unit of work: an LLM call, a tool call, a retrieval, a logic gate, a memory read. Every step carries its model or tool, its latency, tokens, and cost, a status, and the policies it triggered. This is the same anatomy you see in the dashboard.

Reading a step left to right: a refund agent looked up the order, searched the refund policy, reasoned over both, then branched on the customer tier. The third card is mid-execution, which is how a live run reads while the LLM step is still thinking. You can open any run as a flow diagram, as this graph, or as a plain-English narrative; all three are the same recorded decision.

A reasoning graph is not a knowledge graph

A knowledge graph stores what your organization knows: entities and the relationships between them. It is a map of facts, and it changes slowly. A reasoning graph records something a knowledge graph never holds: how an agent thought on one specific run. Which claims it committed to, which evidence it weighed, which assumptions it filled in, and how those connected to the decision it reached.

The two are complements, not competitors. An agent may well consult a knowledge graph as evidence, and that lookup appears as a step on the reasoning graph. But when someone asks why the agent decided what it did, a map of what was known cannot answer. Only the record of how it was used can, and that record is what AISquare captures.

Claims, evidence, and assumptions

Inside a reasoning step, AISquare structures the model's thinking into three parts. This is the reasoning markup (RML) view, and it is the clearest answer to "why did it decide that?"

• Claims are what the agent asserted, the conclusions it acted on.
• Evidence is what each claim rests on, every item carrying a confidence score so a weak input is visible rather than buried.
• Assumptions are the gaps the agent filled in for itself: inferred facts it was not given directly. Surfacing them is the point: an assumption you can see is one you can challenge.

The inference chain then shows, step by ordered step, how the agent moved from evidence and assumptions to its claims.

The third piece of evidence here, that the customer tier resolved to standard, carries a noticeably lower confidence than the rest. That is an assumption the agent leaned on: tier was inferred, not confirmed. Seen on the graph, it is the first thing a reviewer would probe, and it is exactly the kind of weak link the Fix step exists to correct.

Why this matters

Structured reasoning is what turns a black-box run into a decision you can defend and improve.

• Audit. When someone asks why an agent did what it did, you point at the claims, the evidence, and the rule it triggered, not a wall of transcript.
• Debugging. A wrong answer usually traces to one weak claim or one bad assumption. The graph shows you which, so you fix the cause, not the symptom.
• Trust. Reasoning you can inspect is reasoning a regulator, an auditor, or a customer can be shown.

Understanding a decision is the input to acting on it. From here the loop continues: Prevent stops a bad action before it runs, Fix corrects a decision that already happened, and Remember carries the result forward so the next run starts ahead.

Next steps