AI Agent Dependency Lockfiles: Stop Silent Tool and Package Drift
An agent can behave differently on Tuesday even when nobody changed its prompt or application code. A package resolves to a newer release, an MCP server updates a tool description, a model alias moves, or a tool image is rebuilt. The workflow still starts. The tests may still be green. But the agent is no longer the runtime you reviewed. That is why a normal package-lock.json is necessary but…
An AI agent can behave unpredictably even when the prompt or application code remains unchanged. This inconsistency arises from various factors, such as package updates, MCP server changes, model alias migrations, or rebuilt tool images. A normal package-lock.json is insufficient for an AI feature because it only pins part of the application while the agent depends on additional elements like models, prompts, tool servers, policy bundles, retrieval configurations, and external packages. To address this issue, an AI agent dependency lockfile should be created.
The lockfile should record dependencies that can alter behavior or permissions without changing the business workflow. It should include both the requested selector and the resolved identity. A useful lockfile records the requested selector and the resolved identity for models, prompts, MCP tools, libraries, and policy bundles. Dependency selectors should be recorded as both the original request and the resolved identity.
For example, for models, the lockfile should include the selector (e.g., "support-fast") and the resolved ID (e.g., "support-fast-2026-10-18").
It is essential to separate intent from resolution. While the latest version can remain an input to an update job, it should not be the only record of what production executed. Configuration changes, although often perceived as less risky than code changes, can significantly impact the output quality, tool availability, permissions, latency, or data handling in an agent system. Similarly, agent-installed dependencies can introduce unexpected transitive trees if not properly managed.
Current public guidance on agent supply chains explicitly includes models, agents, libraries, developer tools, and MCP-server packages in scope. The boundary of dependencies is broader than requirements.txt. A small, easy-to-review lockfile format should be used, such as JSON. The format should be easily parseable by tools, and reviewers should be able to understand it.
The lockfile should not contain credentials or raw customer data. An example lockfile structure includes the lock version, agent name, workflow commit, policy selector and resolved digest, model selector and resolved ID, prompts with their paths and git commits, tools with their server images, versions, schema digests, and scopes, and packages including the agent SDK version and integrity hash, retrieval index revision, embedding model, and chunker digest.
To generate the lockfile, create a command that resolves inputs, validates them, and writes a canonical lockfile. A minimal TypeScript-style sketch demonstrates how to lock a tool. This command should be automated to ensure consistency and prevent manual lockfile modifications in production.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
