langchain-ai/docs
1
0
Fork 0
mirror of https://github.com/langchain-ai/docs.git synced 2026-07-21 03:45:28 -04:00
Code Issues 490 Packages Projects Releases Wiki Activity

[PR #3843] [MERGED] feat: Add backward compatiblity for langgraph #3856

New Issue
Closed
opened 2026-06-05 18:53:22 -04:00 by yindo · 0 comments
yindo commented 2026-06-05 18:53:22 -04:00
Owner
Copy Link
Copy Source

📋 Pull Request Information

Original PR: https://github.com/langchain-ai/docs/pull/3843
Author: @longquanzheng
Created: 5/1/2026
Status: ✅ Merged
Merged: 5/2/2026
Merged by: @lnhsingh

Base: main ← Head: long/versionoing

📝 Commits (2)

📊 Changes

2 files changed (+169 additions, -0 deletions)

View changed files

📝 src/docs.json (+2 -0)
➕ src/oss/langgraph/backward-compatibility.mdx (+167 -0)

📄 Description

Overview

Adds a new docs page Backward compatibility under the LangGraph Production tab (right after Test) that explains how to safely change graph code in production without breaking in-flight runs.

LangGraph applies the latest deployed graph immediately to every thread, including threads that resume from a checkpoint. That makes most code changes implicit backward-compatible API changes against your existing checkpoints, and there are no team-wide guidelines today that walk users through what is safe vs. what isn't. This page fills that gap.

The page is organized around three categories of compatibility issues, in roughly the order users will hit them:

  1. Technical compatibility (most common) — the new code must still load and execute against existing State. Covers renaming/removing nodes, State key removal/rename, tightening State field types, and clarifies that edge topology is not persisted in the checkpoint.
  2. Business compatibility — the new code is technically valid but the new behavior shouldn't apply to in-flight threads. Covers the "stamp a flow_version flag on the State at thread start, branch on it via a conditional edge" pattern.
  3. Non-determinism — only relevant for the Functional API, since the Graph API does not replay node bodies. Cross-links to the existing Determinism / Common pitfalls sections rather than re-deriving them.

Also includes a Detecting in-flight threads subsection that tells users how to find threads parked on a node before deprecating it, leading with the Agent Server's threads.search(status="interrupted"|"busy"), falling back to LangSmith tracing, and finally to per-thread get_state / get_state_history when you already have a thread_id.

The structure and three-category framing are inspired by iWF's versioning guide, adapted for LangGraph (WorkflowState → Node, Input → State), Python-only examples, and reflecting that LangGraph has no Search Attribute equivalent — Agent Server thread search and LangSmith tracing are the analogues.

Type of change

Type: New documentation page

Related issues/PRs

  • GitHub issue:
  • Feature PR:
  • Linear issue:
  • Slack thread:

Checklist

  • I have read the contributing guidelines, including the language policy
  • I have tested my changes locally using docs dev
  • All code examples have been tested and work correctly
  • I have used root relative paths for internal links
  • I have updated navigation in src/docs.json if needed

(Internal team members only / optional): Create a preview deployment as necessary using the Create Preview Branch workflow

Additional notes

Reviewer pointers

  • Title. Went with Backward compatibility over alternatives (Versioning, Update graphs in production, Evolving graph code) since it matches the noun-style of neighboring Production-tab pages (Test, Studio, Deploy, Observability) and is the most direct description of the topic. Easy to rename if reviewers prefer otherwise.
  • Overlap with graph-api.mdx#graph-migrations. That existing five-bullet section is a quick reference; this page is the longer narrative companion with patterns and examples. Cross-linked from a <Tip> near the top so readers who land on either entry point find the other.
  • Python-first by design. The conceptual prose applies to both Python and TypeScript; only the State-versioning code example is Python-only (wrapped in :::python). JS readers still see the prose and SDK pointers (graph.getState, graph.getStateHistory). Happy to add a TS code example for the versioning pattern if reviewers want symmetry.
  • Code examples. The State-versioning Python snippet is illustrative — the triage / policy_check / respond node bodies are stubbed with ... since the point is the conditional edge wiring, not the work each node does. The smaller NotRequired snippet is a copy/paste-runnable schema fragment. Neither has been executed as a full graph.
  • Cross-links manually verified (since mint isn't available in my env to run make broken-links): #starting-points-for-resuming-workflows (durable-execution), #determinism and #common-pitfalls (functional-api), #filter-by-thread-status and #list-threads (use-threads), #conditional-edges and #graph-migrations (graph-api), #checkpointer-libraries and #get-state (persistence).
  • Vale clean. make lint_prose FILES="src/oss/langgraph/backward-compatibility.mdx" passes with 0 errors / 0 warnings.

AI agent involvement

This PR was drafted with assistance from an AI coding agent (Cursor + Claude). All technical claims (in particular the "edges are not persisted in the checkpoint" clarification and the Agent Server threads.search recommendation) were cross-checked against the existing docs before being included.

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/langchain-ai/docs/pull/3843 **Author:** [@longquanzheng](https://github.com/longquanzheng) **Created:** 5/1/2026 **Status:** ✅ Merged **Merged:** 5/2/2026 **Merged by:** [@lnhsingh](https://github.com/lnhsingh) **Base:** `main` ← **Head:** `long/versionoing` --- ### 📝 Commits (2) - [`ff82c72`](https://github.com/langchain-ai/docs/commit/ff82c7229ee762af5008ffa7d5ad64cfe516ea6d) done - [`04f991e`](https://github.com/langchain-ai/docs/commit/04f991eaf41304313c579b64322329c9b659748b) Apply suggestions from code review ### 📊 Changes **2 files changed** (+169 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `src/docs.json` (+2 -0) ➕ `src/oss/langgraph/backward-compatibility.mdx` (+167 -0) </details> ### 📄 Description ## Overview Adds a new docs page **Backward compatibility** under the LangGraph **Production** tab (right after **Test**) that explains how to safely change graph code in production without breaking in-flight runs. LangGraph applies the latest deployed graph immediately to every thread, including threads that resume from a checkpoint. That makes most code changes implicit backward-compatible API changes against your existing checkpoints, and there are no team-wide guidelines today that walk users through what is safe vs. what isn't. This page fills that gap. The page is organized around three categories of compatibility issues, in roughly the order users will hit them: 1. **Technical compatibility** (most common) — the new code must still load and execute against existing State. Covers renaming/removing nodes, State key removal/rename, tightening State field types, and clarifies that edge topology is *not* persisted in the checkpoint. 2. **Business compatibility** — the new code is technically valid but the new behavior shouldn't apply to in-flight threads. Covers the "stamp a `flow_version` flag on the State at thread start, branch on it via a conditional edge" pattern. 3. **Non-determinism** — only relevant for the Functional API, since the Graph API does not replay node bodies. Cross-links to the existing Determinism / Common pitfalls sections rather than re-deriving them. Also includes a **Detecting in-flight threads** subsection that tells users how to find threads parked on a node before deprecating it, leading with the Agent Server's ``threads.search(status="interrupted"|"busy")``, falling back to LangSmith tracing, and finally to per-thread ``get_state`` / ``get_state_history`` when you already have a ``thread_id``. The structure and three-category framing are inspired by [iWF's versioning guide](https://github.com/indeedeng/iwf/wiki/%5BVersioning%5DHow-to-modify-workflow-code-without-breaking-changes), adapted for LangGraph (WorkflowState → Node, Input → State), Python-only examples, and reflecting that LangGraph has no Search Attribute equivalent — Agent Server thread search and LangSmith tracing are the analogues. ## Type of change **Type:** New documentation page ## Related issues/PRs - GitHub issue: - Feature PR: - Linear issue: - Slack thread: ## Checklist - [ ] I have read the [contributing guidelines](README.md), including the [language policy](https://docs.langchain.com/oss/python/contributing/overview#language-policy) - [ ] I have tested my changes locally using `docs dev` - [ ] All code examples have been tested and work correctly - [x] I have used **root relative** paths for internal links - [x] I have updated navigation in `src/docs.json` if needed (Internal team members only / optional): Create a preview deployment as necessary using the [Create Preview Branch workflow](https://github.com/langchain-ai/docs/actions/workflows/create-preview-branch.yml) ## Additional notes ### Reviewer pointers - **Title.** Went with `Backward compatibility` over alternatives (`Versioning`, `Update graphs in production`, `Evolving graph code`) since it matches the noun-style of neighboring Production-tab pages (`Test`, `Studio`, `Deploy`, `Observability`) and is the most direct description of the topic. Easy to rename if reviewers prefer otherwise. - **Overlap with [`graph-api.mdx#graph-migrations`](https://docs.langchain.com/oss/langgraph/graph-api#graph-migrations).** That existing five-bullet section is a quick reference; this page is the longer narrative companion with patterns and examples. Cross-linked from a `<Tip>` near the top so readers who land on either entry point find the other. - **Python-first by design.** The conceptual prose applies to both Python and TypeScript; only the State-versioning code example is Python-only (wrapped in `:::python`). JS readers still see the prose and SDK pointers (`graph.getState`, `graph.getStateHistory`). Happy to add a TS code example for the versioning pattern if reviewers want symmetry. - **Code examples.** The State-versioning Python snippet is illustrative — the `triage` / `policy_check` / `respond` node bodies are stubbed with `...` since the point is the conditional edge wiring, not the work each node does. The smaller `NotRequired` snippet is a copy/paste-runnable schema fragment. Neither has been executed as a full graph. - **Cross-links manually verified** (since `mint` isn't available in my env to run `make broken-links`): `#starting-points-for-resuming-workflows` (durable-execution), `#determinism` and `#common-pitfalls` (functional-api), `#filter-by-thread-status` and `#list-threads` (use-threads), `#conditional-edges` and `#graph-migrations` (graph-api), `#checkpointer-libraries` and `#get-state` (persistence). - **Vale clean.** `make lint_prose FILES="src/oss/langgraph/backward-compatibility.mdx"` passes with 0 errors / 0 warnings. ### AI agent involvement This PR was drafted with assistance from an AI coding agent (Cursor + Claude). All technical claims (in particular the "edges are not persisted in the checkpoint" clarification and the Agent Server `threads.search` recommendation) were cross-checked against the existing docs before being included. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
yindo added the pull-request label 2026-06-05 18:53:22 -04:00
yindo closed this issue 2026-06-05 18:53:22 -04:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
deepagents
docs-infra
external
external
help wanted
integration
internal
internal
javascript
js/ts
langchain
langgraph
langsmith
needs-title
pull-request
Mirrored from GitHub Pull Request
 python
reference
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: langchain-ai/docs#3856
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?