Versioning LangGraph Graphs, Prompts, and Tools for SR 26-2 Change Management

Why one version number is not enough

A LangGraph agent does not change behavior through a single artifact. The graph topology, the prompt templates, and the tool definitions each alter what the agent does, and they usually live in different places with different owners. A graph may sit in a repository, prompts in a configuration store or a shared document, and tool schemas inside a service owned by another team. If only one of them is versioned, a behavior change can occur with no record that anything changed.

The practical consequence is reconstruction. When an examiner or internal auditor asks which graph, prompt, and tool versions were live on a given date, the answer must come from a record, not from memory or from inspecting today's configuration. The scheme below treats each artifact as separately versioned and links them through a manifest. The artifact mapping is a practitioner design, not a prescribed standard.

General guidance points the same way. A NIST draft profile for generative AI, since labelled withdrawn, recommends tracking version numbers, planned updates, hotfixes, and other change information, and keeping version control so changes can be rolled back. It names models and datasets specifically. Extending the idea to graphs, prompts, and tools is an inference, but a reasonable one.

Version each artifact on its own terms

Each artifact type needs an identifier scheme that fits how it changes. The common requirement is that an identifier always resolves to exactly one content state.

• Graph: Keep graph definitions, state schema, node logic, and conditional routing in source control. Identify a release by a tag and commit hash. Include compiled graph configuration and checkpointer settings in the same repository so they cannot drift.
• Prompts: Store each template as a file or registry entry with an immutable identifier, such as a content hash plus a human-readable label. Never edit a published version in place. A wording fix creates a new version.
• Tools: Apply semantic versioning to each tool schema. Treat a new parameter, a changed permission scope, or a changed external endpoint as separately reviewable. A scope expansion is a major change even if the schema is unchanged.
• Pipeline dependencies: Pin framework and library versions and review unexpected changes to build tooling. NIST's secure software development guidance treats build and interpreter tools as change-managed assets, which supports doing the same for the agent release pipeline.

Classify changes and set approval depth

Not every change deserves the same review. A classification scheme lets low-risk changes move quickly while keeping scrutiny on those that expand what the agent can do. No standard scheme exists for this, so define one and document it.

A workable split has three tiers. A prompt wording change that leaves intent, tools, and routing alone is a standard change, validated against a regression set. A new or modified conditional edge, a new node, or a changed state schema alters control flow and warrants a deeper validation and a named approver. A new tool, a broader permission scope, or a new external endpoint changes what the agent can reach, and should require approval from the owner of the affected data or system as well as the platform owner.

The NIST draft recommends running change management and risk and impact assessment before deploying updates, across all intended uses and contexts. Record the assessment outcome with the change so the approval can be read in context. Keep decommissioned and replacement versions clearly identifiable, so a retired prompt or tool is never mistaken for a current one.

What versioning shows and what runtime evidence adds

Versioning and the change record establish what was intended to run: the approved combination of graph, prompts, and tools. They do not establish what the agent was permitted to do in a specific interaction, or what it did. A correctly pinned manifest can still be in force while a tool call behaves in a way nobody reviewed.

That gap is where runtime policy enforcement complements version control. Trussed enforces policy in the execution path across agents and tool calls, applying allow, redact, block, or escalate for human approval at the level of individual interactions and tool calls. Because enforcement happens at runtime, not reviewed after the fact, it produces audit-ready evidence of what was allowed and what occurred.

To make that evidence useful for change management, carry the manifest identifier with each request so enforcement records can be joined to the versions in force. The change record then explains why a version was approved, and the enforcement evidence shows how it behaved in operation. Together they let a reviewer move from an individual tool call back to the manifest, the approval, and the validation behind it.