Four nouns: session, message, run, step
Lesson 1 of 5 in Sessions and Streaming: The Conversation Plumbing.
An agent that answers one question needs no plumbing. An agent that holds a conversation, calls tools, gets interrupted, resumes, and gets audited six weeks later needs a data model — and every provider and platform has independently landed on roughly the same four objects.
The session (also thread, or conversation) is the container: one continuing interaction with one user, holding the transcript. The message (also item) is one entry in that transcript — a user turn, an assistant turn, a tool call, a tool result. The run (also response, or invocation) is one execution of the agent loop against that session: the agent wakes up, reasons, calls tools, produces output, finishes. The step is one iteration inside a run — which tool the model chose, what arguments it sent, what came back.
Two of these are nouns of storage and two are nouns of execution, and confusing the pair is the most common design mistake in this whole area. Sessions and messages accumulate; they outlive processes. Runs and steps are activity; they start, they end, they can fail and be retried. A session with no active run is just a transcript sitting in a database.
Key terms: session, run, transcript, agent loop, tool call, context window
One run, from request to record
- Create or fetch session
A session id is the join key for everything that follows: the transcript, the traces, the billing records, the deletion request that arrives in eight months.
- Append user message
The user turn lands in the transcript before the run starts. If the run crashes, the question is still on record.
- Start run
A run is an execution handle: it has an id, a status, and a lifetime. Client and server both refer to it by id, which is what makes reconnecting possible.
- Step: model reasons, emits tool call
One iteration of the loop. The step record is the unit your trace viewer and your evals will read.
- Needs something from outside?
A tool the platform cannot execute itself, or a human approval. The run parks in a waiting state instead of dying — this is how approval gates are implemented underneath.
- Caller submits tool output / approval
The run resumes from where it parked. Note who is driving: the client pushes the result back into a server-side run.
- Assistant message appended
The result becomes another message in the transcript, so the next run sees it as ordinary history.
- Run terminal: completed / failed / cancelled
Terminal statuses are the only ones safe to report to a user or bill for. Everything before is provisional.
Notice the parked state in the middle. A run that needs a tool the platform cannot run itself — your internal API, a human clicking approve — does not fail; it waits, and the caller submits the missing output against the run id. That single mechanism is how human-in-the-loop gates, long-running tools, and client-side tool execution all work on a server-side run model.
Notice also what the run id buys you: a name for work in progress. Without it there is nothing to reconnect to, nothing to cancel, and nothing to attach a trace to. Most of the next three lessons is consequences of that one identifier existing.
| Concept | Classic Assistants-style naming | Microsoft Foundry Agent Service naming | What it actually is |
|---|---|---|---|
The container | Thread | Conversation | Durable server-side history for one continuing interaction |
The entries | Messages | Items | Messages, tool calls, and tool outputs, in order |
The execution | Run | Response | One execution of a model or agent against input |
The agent definition | Assistant | Agent version | The persisted, versioned orchestration definition |
Interactive sorting exercise: Sort each item by which layer owns it. The test: does it accumulate and outlive the process (storage), or does it start, finish, and get retried (execution)?
Interactive checkpoint quiz (2 questions) — open this page in a browser to take it.