All docs
See what's happeningSessionsdashboard

Sessions

Conversations and multi-agent workflows step by step: hand-offs checked, and business rules over the whole conversation.

A session is one conversation or one multi-step workflow: every turn of a chat, or every agent step of a claim being processed. Sessions shows them step by step, checks that facts passed between agents arrived unchanged, and checks rules that only make sense over a whole conversation.

Sessions appear when each step is sent with the same session_id. See Connect your app.

Find a session

SessionsSessions

  1. Choose a view: All sessions, Whole run failed (a wrong tool call, a missed or out-of-order step, or a tool outside the allowed ones), Hand-off failed or A step below 0.75 (a session where at least one step's overall score is under 0.75). The list covers the last 7 days.
  2. The list is read As of a moment, so rows don't shift while you page; Refresh shows steps logged since. Page with Newer and Older.
  3. Tick sessions and click Send to review to queue every scored step for a person to check, or click a row to open the session.
ColumnMeaning
SessionThe session id; for a dataset run, the run's name in bold, then the item
Agent pathThe agents the conversation passed through, in order
Whole runPassed, the checks that failed (Tool correctness, Trajectory, Only permitted tools; hover for what was wrong), Still scoring until every step is scored (the checks over the whole run are written after the last step), or Not checked when the steps sent no expected_tools or allowed_tools
Hand-offsAll fields unchanged; what went wrong, each finding in a few words ("refund-decision-agent sent response-agent no order_id (required) · refund-decision-agent had days_since_purchase as 45; sent response-agent 15"); or Not applicable when no hand-off was checked
Weakest stepThe lowest overall score of any step
Steps, Duration, Last stepSize and timing

Whole run and Hand-offs are separate checks. A run can call every expected tool in order (Passed) and still hand the next agent a wrong value, so read both columns: the Hand-off failed view lists the sessions where a hand-off failed, whatever the whole run did.

Inside a session

Session detailSession detail

  • Agent flow draws the path between agents, with the result of each hand-off.
  • Checks over the whole run (when the steps sent expected_tools or allowed_tools): Tool correctness (every expected tool called as expected, or which were missing), Trajectory (the expected steps taken, in order) and Only permitted tools, each Pass or Fail with the detail.

Checks over the whole runChecks over the whole run

  • Hand-offs has one card per hand-off, Hand-off: intake → adjudication, with a row per field: Field, Type, Sender had (the value in the sending agent's own inputs), Sent (the value it put in the hand-off) and Result. When a field was dropped or changed, the card says Where to correct: hand-off. with the first finding. Which field types apply comes from the policy version that scored the session.
  • Steps lists every step; click one to open its event details.
  • Business rules (when your project has rules with scope: session) lists each rule over the whole conversation, its verdict and what happened.
  • Add session to dataset keeps the whole conversation as a test case; Send to review queues its steps.

Example: a hand-off that dropped and changed a field

A refund workflow has three agents: retrieval finds the policy, a decision agent picks the action, and a response agent writes the reply. The project has a hand-off contract for the response agent: every hand-off to it must carry order_id and days_since_purchase.

[{"to": "response-agent",
  "fields": [{"name": "order_id", "type": "identifier", "pattern": "R-[0-9]{4}", "required": true},
             {"name": "days_since_purchase", "type": "number", "required": true}]}]

The decision agent had "Order ID: R-7421" and "Days since purchase: 45" in its input. It handed over {"days_since_purchase": 15}:

client.log(decide_prompt, decision, agent_name="refund-decision-agent", session_id=session,
           tools_called=[{"name": "deny_refund"}], expected_tools=[{"name": "deny_refund"}],
           handoff={"to": "response-agent", "fields": {"days_since_purchase": 15}})

A hand-off that dropped order_id and changed days_since_purchaseA hand-off that dropped order_id and changed days_since_purchase

  • Agent flow marks the edge: order_id dropped, and 1 hand-off failed.
  • Checks over the whole run all pass: the right tool was called, in order. The hand-off is what broke.
  • The hand-off card fails both fields: order_id was required and not sent; days_since_purchase: the sender had 45 and sent 15.
  • In the list, the session appears under Hand-off failed, with both findings in the Hand-offs column.

The same workflow handing over {"order_id": "R-7421", "days_since_purchase": 45} shows All fields unchanged. A value counts as one the sender had only when its inputs state it: label it ("Order ID: R-7421") or send it keyed by the field name in a tool result. See Hand-off contracts.

Business rules over a whole conversation

A conversation that broke a business ruleA conversation that broke a business rule

Some rules can only be broken by a conversation, not by one answer. A collections agent must offer the hardship plan before any payment arrangement if the customer mentioned hardship. The customer says it in turn 3; the agent offers an instalment plan in turn 9. Each turn looks fine on its own. The conversation breaks the rule. How to write such rules: Business rules › Rules over a whole conversation.

The Business rules card shows a summary line, how many turns were read, and a table:

RuleVerdictWhat happened
Hardship plan before any payment arrangementBrokenTurn 3 · customer · hardship — "I lost my job last month" (what came first); Turn 9 · agent · payment arrangement — "we can set you up on a 6-month instalment plan" (what followed). The reasoning model confirmed the agent commits to it in that turn. Open turn 9
No collection demand while a dispute is openHolds

The verdicts are Holds, Broken, Broken? Not confirmed (a warning: the reasoning model could not confirm it, so it never counts as a failure) and Mentioned, not committed (the agent only mentioned, refused or explained the action, for example "I can't set up a plan until your dispute is resolved"; not counted). Rules that never applied are counted under the table, not listed.

Open turn N opens the event of the turn that decided the rule. That event gets a new verdict: its Follows business rules check lists the rule, the sentence holding the value carries Breaks a business rule, and its History tab shows the new verdict as Whole conversation next to the earlier On arrival one. Grounding scores don't change.

When the rules run

The conversation's rules run when it ends. Tell variA/Bly it has ended with client.end_session(session_id) (for example when a call hangs up), or by sending the last turn with is_aggregator=True. Nothing is guessed from a pause.

for turn in call.turns():
    client.log(turn.customer_text, turn.agent_reply,
               session_id=call.id, agent_name="collections-agent",
               metadata={"balance": call.balance})
client.end_session(call.id)       # the call hung up: check the whole conversation now

Calling end_session again is safe: it answers that the session was already ended and runs nothing twice. A session id with no logged step is refused with the reason.

Common mistakes

You seeWhyFix
No session in the last 7 days matches this view.Steps were sent without session_idSend the same session_id on every step
Every message is its own sessionA new id per messageUse the conversation's id, not a message id
The Business rules card never appearsThe conversation was never ended, or no rule has scope: sessionCall client.end_session(...) when it is over
A hand-off card shows Not configuredThe project has no hand-off contract for the receiving agentAdd one under Data definitions › Hand-off contracts