Pradra StudioDocs
Sign in

Conversations

A prediction is stateless: it answers what you asked and forgets. A session is the conversation primitive — it replays the recent transcript into the prompt so "and what about the other one?" means something, and it records every turn as it is served.

const session = await pradra.sessions.create({
  capabilityId,
  externalRef: "customer-4471",              // YOUR end user
  principal: { tenant_id: "store-a", user_id: "u_913" },
});

await pradra.predict(capabilityId, { input: "Where is order 12345?" }, { sessionId: session.id });
await pradra.predict(capabilityId, { input: "Can I still cancel it?" }, { sessionId: session.id });

Sessions work with both generative capabilities and agents. A classic ML capability is refused: it has no notion of a previous turn, so a conversation against one would accumulate history that nothing ever reads.

Your customers are not Pradra users

externalRef is your own identifier for the person talking. It exists because the alternative is worse: without it, a product has one session shared across every customer, and one customer's conversation becomes another's context.

Your end users never become Pradra accounts. The tenant boundary stays your API token, and the identity that reaches your tools is principal — stamped once when the session is created and immutable afterwards. Trying to change it later is refused rather than ignored, because silently dropping it would let you believe a conversation had been re-scoped to a different customer when it had not.

To converse as someone else, open a new session.

What a turn actually sees

Replaying an entire history would be expensive and eventually impossible, so the replay is bounded twice:

  • a message ceiling — how many recent turns are replayed verbatim, and
  • a character budget — how much text those turns may occupy.

Either limit alone fails in the opposite direction: a message count lets a few enormous turns blow the prompt, and a character budget alone lets many tiny turns be cut to almost nothing. The newest turns always survive, and a small floor of the most recent messages beats the budget — a conversation that replays nothing has no memory at all.

Older turns are not simply dropped: they are folded into a rolling summary that is regenerated off the request path. If the summarizer is unavailable, chat keeps working and only loses distant memory — an outage should not end conversations.

Tool digests

When an agent turn calls tools, a truncated digest of what those tools returned is kept with that turn. Without it, a follow-up like "what was the ETA you found?" is unanswerable whenever the number appeared in a tool result but not in the prose answer.

The digest is replayed as clearly-fenced data, never as instructions, and its retention window is shorter than the transcript's: the readable conversation outlives the bulk it was derived from.

What is recorded

The turn is written by the serving path itself, so it is recorded exactly once whether you call /predict, the streaming endpoint, or the session's own message endpoint. Two consequences worth knowing:

  • An answer withheld by the content filter is stored as the withheld message — the transcript reflects what your consumer actually received, not the flagged text they never saw.
  • A transcript write failing does not fail the request. The inference was already paid for; returning an error would charge you for an answer you never receive and make you retry and pay again.

Retention

Three windows, narrowest first: tool digests are cleared first, then idle sessions are archived, then archived conversations are purged. Deleting a conversation never deletes an agent run's trace — a conversation is memory, a trace is the record of what an agent actually did, and losing the second because someone tidied the first would remove the audit trail exactly when it is needed.

An archived session stays readable and stops accepting turns.

In the Studio

The Chat page opens a conversation against any generative or agent capability in the workspace: pick the capability, type, and watch the answer arrive. It is an operator tool for testing behaviour — console conversations carry no principal, because that identity belongs to an end user of your product and is supplied by your own server.

Next