Assistants, threads, and runs

Here is the sentence the whole runtime layer compresses into, and it is worth memorising verbatim:

assistants for configuration, threads for state, and runs for workloads

Three nouns, three jobs, no overlap. If you can say which of the three a question is about, you have usually already narrowed the options to two.

Assistant: configuration

An assistant is a named configuration over a graph. Same code, different settings: a different model, a different prompt, a different set of tool permissions.

Two facts about the relationship:

• Each graph automatically gets a default assistant. You do not have to create one to start running. Deploy, and there is already something to call.
• One graph, many assistants. That is the whole point. You ship the graph once and hang as many configurations off it as you have use cases, instead of deploying near-identical copies.

Assistant versions, and the update trap

Assistants are versioned, with promote and rollback. This is the other versioning concept, the one that pairs with revisions from the last lesson.

Revisions version the deployment. Versions version the assistant. Deployment side is code plus secrets. Assistant side is configuration. Two objects, two version streams, and confusing them is the single easiest mistake in this domain.

That is an excellent quiz question and you should expect to see it.

Thread: state

A thread holds state. Conversation history, checkpointed execution, the stuff that has to survive between calls.

A thread has exactly four statuses:

• idle: nothing is running against it
• busy: a run is in flight
• interrupted: execution paused, waiting to be resumed
• error: a run failed

Four. Learn the count as well as the names, because a fifth plausible option like completed or pending in an answer list is exactly the shape of a distractor.

Run: workload

A run is the unit of work. It pairs an assistant config with a thread, and updates that thread's checkpoint.

Read that once more, because it does the whole job. A run is not a thing that exists on its own. It needs a configuration to know how to behave, and it needs a thread to know what state it is working on, and its effect is to move that thread's checkpoint forward.

The picture, complete

Deployment holds graphs. Each graph has a default assistant and can have many more. Threads hold state, independently of any of that. A run is the arrow that connects an assistant to a thread and advances the checkpoint.

Draw it once now, on paper. Every remaining lesson in this course hangs off that diagram.