The six nouns, and the two things called versions
Six nouns hold this entire domain up: graph, deployment, revision, assistant, thread, run. Three of them answer “what did I ship” and three answer “what is it doing right now”. Get all six exactly right and a meaningful fraction of the ten Deploy questions answer themselves before you have finished reading the stem.
The three that answer what you shipped
A graph is your code. Nodes, edges, state schema, compiled. Nothing about deployment changes what a graph is.
A deployment is the served instance: the box the graphs run inside, with an API in front of them and a database underneath. The fact worth burning in is that a deployment holds one or more graphs, declared in the graphs key of langgraph.json. One deployment per agent is a habit people fall into, not a constraint the platform enforces.
A revision is a version of the deployment. Not of a graph, not of a config file. Of the whole deployed unit, and specifically of two things bundled together: the code and the secrets.
The three that answer what it is doing
Here is the sentence the runtime layer compresses into, and it is worth memorising word for word:
assistants for configuration, threads for state, and runs for workloads
An assistant is a named configuration over a graph. Each graph automatically gets a default assistant, so you can deploy and start running immediately, and one graph can carry many assistants. That is the entire point: ship the graph once, hang as many configurations off it as you have use cases, instead of deploying near-identical copies.
A thread holds state: conversation history, checkpointed execution, the things that must survive between calls.
A run is the unit of work. It pairs an assistant config with a thread and updates that thread’s checkpoint. A run does not exist on its own. It needs a configuration to know how to behave and a thread to know what state it is working on, and its effect is to move that thread forward.
The two things both called versions
There are two versioning concepts here and they operate on different objects.
| Concept | Versions | Contains |
|---|---|---|
| Revision | the deployment | code and secrets |
| Version | the assistant | assistant configuration, with promote and rollback |
Almost every question that looks like it is testing versioning is really testing whether you know which object each one applies to. When you see the word “version” in a stem, your first move is not to recall what versioning does. It is to ask version of what.
Try it yourself
The hierarchy sentence
The documentation compresses the whole runtime layer into one sentence. It is worth holding verbatim.
Complete the sentence: assistants for ___, threads for ___, and runs for ___. Then say what a run does to a thread.
Reveal answer
Assistants for configuration, threads for state, and runs for workloads. An assistant is a named configuration over a graph. A thread holds conversation or execution state as checkpoints. A run pairs an assistant config with a thread and updates that thread's checkpoint. So a run is the unit of work that takes a configuration and a piece of state and moves the state forward.
How many graphs fit in a deployment
Sketch the containment before you read the options. Which one matches what you drew?
Show answer
Correct answer: D — One deployment can serve one or more graphs, each declared in the config
A deployment holds one or more graphs, declared in the graphs key of langgraph.json, so a single deployment can serve several distinct agents. The tempting wrong answer is the one-to-one option, because almost every tutorial deploys a single graph and it is very easy to generalise a convention into a rule. The same-thing-under-two-names option is worth rejecting hard: a graph is your code, a deployment is the served instance of it, and collapsing those two is exactly the confusion that the versioning questions are built on.
You rotate an API key
Monday morning, security asks you to rotate the model provider key on a live deployment. What happens to the deployment?
Show answer
Correct answer: A — A new revision is created, because a revision captures code and secrets together
Revisions capture the deployed code and its secrets as one unit, so changing a secret forces a new revision. The tempting wrong answer is the in-place update, because every secret manager you have ever used treats a value as something you swap under a running process, and because secrets feel like settings. The assistant-version option is the more dangerous distractor for anyone who half-learned this lesson: assistants do version configuration, but the configuration they version is assistant config, not deployment environment. Two versioning systems, two different objects.
Which versioning system owns what
This pair is the single most confusable thing in the domain, and it gets asked obliquely more often than head-on.
Revisions and assistant versions both exist. Which object does each one version, and what does each contain?
Reveal answer
A revision versions the deployment, and it captures the deployed code and the secrets together. A version versions the assistant, meaning its configuration over a graph, such as model, prompt and tool settings, with promote and rollback available. The split inverts easily because the word configuration honestly describes both, so the word cannot be your discriminator. Ask what object is being versioned, not what kind of thing changed.
The containment sketch
Draw it top down, without looking. Deployment, graphs, revisions, assistants, threads, runs.
Your sketch shows a deployment containing one or more graphs, revisions running down the side as successive snapshots of the whole deployed unit including secrets, a default assistant hanging off each graph with room for more, threads drawn separately as state, and a run drawn as an arrow joining an assistant to a thread. Nothing in the sketch suggests a revision versions an individual graph, and nothing suggests one graph per deployment is a rule.