@langchain/langgraph 0.2.32 → 0.2.34

package/dist/constants.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports._isCommand = exports.Command = exports._isSend = exports.Send = exports._isSendInterface = exports.CHECKPOINT_NAMESPACE_END = exports.CHECKPOINT_NAMESPACE_SEPARATOR = exports.RESERVED = exports.NULL_TASK_ID = exports.TASK_NAMESPACE = exports.PULL = exports.PUSH = exports.TASKS = exports.SELF = exports.TAG_NOSTREAM = exports.TAG_HIDDEN = exports.RECURSION_LIMIT_DEFAULT = exports.RUNTIME_PLACEHOLDER = exports.RESUME = exports.INTERRUPT = exports.CONFIG_KEY_CHECKPOINT_MAP = exports.CONFIG_KEY_CHECKPOINT_NS = exports.CONFIG_KEY_SCRATCHPAD = exports.CONFIG_KEY_WRITES = exports.CONFIG_KEY_RESUME_VALUE = exports.CONFIG_KEY_STREAM = exports.CONFIG_KEY_TASK_ID = exports.CONFIG_KEY_RESUMING = exports.CONFIG_KEY_CHECKPOINTER = exports.CONFIG_KEY_READ = exports.CONFIG_KEY_SEND = exports.ERROR = exports.INPUT = exports.MISSING = void 0;
+exports.isCommand = exports.Command = exports._isSend = exports.Send = exports._isSendInterface = exports.CHECKPOINT_NAMESPACE_END = exports.CHECKPOINT_NAMESPACE_SEPARATOR = exports.RESERVED = exports.NULL_TASK_ID = exports.TASK_NAMESPACE = exports.PULL = exports.PUSH = exports.TASKS = exports.SELF = exports.TAG_NOSTREAM = exports.TAG_HIDDEN = exports.RECURSION_LIMIT_DEFAULT = exports.RUNTIME_PLACEHOLDER = exports.RESUME = exports.INTERRUPT = exports.CONFIG_KEY_CHECKPOINT_MAP = exports.CONFIG_KEY_CHECKPOINT_NS = exports.CONFIG_KEY_SCRATCHPAD = exports.CONFIG_KEY_WRITES = exports.CONFIG_KEY_RESUME_VALUE = exports.CONFIG_KEY_STREAM = exports.CONFIG_KEY_TASK_ID = exports.CONFIG_KEY_RESUMING = exports.CONFIG_KEY_CHECKPOINTER = exports.CONFIG_KEY_READ = exports.CONFIG_KEY_SEND = exports.ERROR = exports.INPUT = exports.MISSING = void 0;
 exports.MISSING = Symbol.for("__missing__");
 exports.INPUT = "__input__";
 exports.ERROR = "__error__";
@@ -126,6 +126,65 @@ function _isSend(x) {
 exports._isSend = _isSend;
 /**
  * One or more commands to update the graph's state and send messages to nodes.
+ * Can be used to combine routing logic with state updates in lieu of conditional edges
+ *
+ * @example
+ * ```ts
+ * import { Annotation, Command } from "@langchain/langgraph";
+ *
+ * // Define graph state
+ * const StateAnnotation = Annotation.Root({
+ *   foo: Annotation<string>,
+ * });
+ *
+ * // Define the nodes
+ * const nodeA = async (_state: typeof StateAnnotation.State) => {
+ *   console.log("Called A");
+ *   // this is a replacement for a real conditional edge function
+ *   const goto = Math.random() > .5 ? "nodeB" : "nodeC";
+ *   // note how Command allows you to BOTH update the graph state AND route to the next node
+ *   return new Command({
+ *     // this is the state update
+ *     update: {
+ *       foo: "a",
+ *     },
+ *     // this is a replacement for an edge
+ *     goto,
+ *   });
+ * };
+ *
+ * // Nodes B and C are unchanged
+ * const nodeB = async (state: typeof StateAnnotation.State) => {
+ *   console.log("Called B");
+ *   return {
+ *     foo: state.foo + "|b",
+ *   };
+ * }
+ *
+ * const nodeC = async (state: typeof StateAnnotation.State) => {
+ *   console.log("Called C");
+ *   return {
+ *     foo: state.foo + "|c",
+ *   };
+ * }
+ *
+ * import { StateGraph } from "@langchain/langgraph";
+
+ * // NOTE: there are no edges between nodes A, B and C!
+ * const graph = new StateGraph(StateAnnotation)
+ *   .addNode("nodeA", nodeA, {
+ *     ends: ["nodeB", "nodeC"],
+ *   })
+ *   .addNode("nodeB", nodeB)
+ *   .addNode("nodeC", nodeC)
+ *   .addEdge("__start__", "nodeA")
+ *   .compile();
+ *
+ * await graph.invoke({ foo: "" });
+ *
+ * // Randomly oscillates between
+ * // { foo: 'a|c' } and { foo: 'a|b' }
+ * ```
  */
 class Command {
     constructor(args) {
@@ -135,11 +194,11 @@ class Command {
             writable: true,
             value: "Command"
         });
-        Object.defineProperty(this, "resume", {
+        Object.defineProperty(this, "lc_direct_tool_output", {
             enumerable: true,
             configurable: true,
             writable: true,
-            value: void 0
+            value: true
         });
         Object.defineProperty(this, "graph", {
             enumerable: true,
@@ -149,6 +208,12 @@ class Command {
         });
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         Object.defineProperty(this, "update", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "resume", {
             enumerable: true,
             configurable: true,
             writable: true,
@@ -167,6 +232,20 @@ class Command {
             this.goto = Array.isArray(args.goto) ? args.goto : [args.goto];
         }
     }
+    _updateAsTuples() {
+        if (this.update &&
+            typeof this.update === "object" &&
+            !Array.isArray(this.update)) {
+            return Object.entries(this.update);
+        }
+        else if (Array.isArray(this.update) &&
+            this.update.every((t) => Array.isArray(t) && t.length === 2 && typeof t[0] === "string")) {
+            return this.update;
+        }
+        else {
+            return [["__root__", this.update]];
+        }
+    }
 }
 exports.Command = Command;
 Object.defineProperty(Command, "PARENT", {
@@ -175,7 +254,7 @@ Object.defineProperty(Command, "PARENT", {
     writable: true,
     value: "__parent__"
 });
-function _isCommand(x) {
+function isCommand(x) {
     return typeof x === "object" && !!x && x.lg_name === "Command";
 }
-exports._isCommand = _isCommand;
+exports.isCommand = isCommand;

package/dist/constants.d.ts

@@ -117,14 +117,75 @@ export type CommandParams<R> = {
 };
 /**
  * One or more commands to update the graph's state and send messages to nodes.
+ * Can be used to combine routing logic with state updates in lieu of conditional edges
+ *
+ * @example
+ * ```ts
+ * import { Annotation, Command } from "@langchain/langgraph";
+ *
+ * // Define graph state
+ * const StateAnnotation = Annotation.Root({
+ *   foo: Annotation<string>,
+ * });
+ *
+ * // Define the nodes
+ * const nodeA = async (_state: typeof StateAnnotation.State) => {
+ *   console.log("Called A");
+ *   // this is a replacement for a real conditional edge function
+ *   const goto = Math.random() > .5 ? "nodeB" : "nodeC";
+ *   // note how Command allows you to BOTH update the graph state AND route to the next node
+ *   return new Command({
+ *     // this is the state update
+ *     update: {
+ *       foo: "a",
+ *     },
+ *     // this is a replacement for an edge
+ *     goto,
+ *   });
+ * };
+ *
+ * // Nodes B and C are unchanged
+ * const nodeB = async (state: typeof StateAnnotation.State) => {
+ *   console.log("Called B");
+ *   return {
+ *     foo: state.foo + "|b",
+ *   };
+ * }
+ *
+ * const nodeC = async (state: typeof StateAnnotation.State) => {
+ *   console.log("Called C");
+ *   return {
+ *     foo: state.foo + "|c",
+ *   };
+ * }
+ *
+ * import { StateGraph } from "@langchain/langgraph";
+
+ * // NOTE: there are no edges between nodes A, B and C!
+ * const graph = new StateGraph(StateAnnotation)
+ *   .addNode("nodeA", nodeA, {
+ *     ends: ["nodeB", "nodeC"],
+ *   })
+ *   .addNode("nodeB", nodeB)
+ *   .addNode("nodeC", nodeC)
+ *   .addEdge("__start__", "nodeA")
+ *   .compile();
+ *
+ * await graph.invoke({ foo: "" });
+ *
+ * // Randomly oscillates between
+ * // { foo: 'a|c' } and { foo: 'a|b' }
+ * ```
  */
 export declare class Command<R = unknown> {
     lg_name: string;
-    resume?: R;
+    lc_direct_tool_output: boolean;
     graph?: string;
-    update?: Record<string, any>;
+    update?: Record<string, any> | [string, any][];
+    resume?: R;
     goto: string | Send | (string | Send)[];
     static PARENT: string;
     constructor(args: CommandParams<R>);
+    _updateAsTuples(): [string, unknown][];
 }
-export declare function _isCommand(x: unknown): x is Command;
+export declare function isCommand(x: unknown): x is Command;

package/dist/constants.js

@@ -120,6 +120,65 @@ export function _isSend(x) {
 }
 /**
  * One or more commands to update the graph's state and send messages to nodes.
+ * Can be used to combine routing logic with state updates in lieu of conditional edges
+ *
+ * @example
+ * ```ts
+ * import { Annotation, Command } from "@langchain/langgraph";
+ *
+ * // Define graph state
+ * const StateAnnotation = Annotation.Root({
+ *   foo: Annotation<string>,
+ * });
+ *
+ * // Define the nodes
+ * const nodeA = async (_state: typeof StateAnnotation.State) => {
+ *   console.log("Called A");
+ *   // this is a replacement for a real conditional edge function
+ *   const goto = Math.random() > .5 ? "nodeB" : "nodeC";
+ *   // note how Command allows you to BOTH update the graph state AND route to the next node
+ *   return new Command({
+ *     // this is the state update
+ *     update: {
+ *       foo: "a",
+ *     },
+ *     // this is a replacement for an edge
+ *     goto,
+ *   });
+ * };
+ *
+ * // Nodes B and C are unchanged
+ * const nodeB = async (state: typeof StateAnnotation.State) => {
+ *   console.log("Called B");
+ *   return {
+ *     foo: state.foo + "|b",
+ *   };
+ * }
+ *
+ * const nodeC = async (state: typeof StateAnnotation.State) => {
+ *   console.log("Called C");
+ *   return {
+ *     foo: state.foo + "|c",
+ *   };
+ * }
+ *
+ * import { StateGraph } from "@langchain/langgraph";
+
+ * // NOTE: there are no edges between nodes A, B and C!
+ * const graph = new StateGraph(StateAnnotation)
+ *   .addNode("nodeA", nodeA, {
+ *     ends: ["nodeB", "nodeC"],
+ *   })
+ *   .addNode("nodeB", nodeB)
+ *   .addNode("nodeC", nodeC)
+ *   .addEdge("__start__", "nodeA")
+ *   .compile();
+ *
+ * await graph.invoke({ foo: "" });
+ *
+ * // Randomly oscillates between
+ * // { foo: 'a|c' } and { foo: 'a|b' }
+ * ```
  */
 export class Command {
     constructor(args) {
@@ -129,11 +188,11 @@ export class Command {
             writable: true,
             value: "Command"
         });
-        Object.defineProperty(this, "resume", {
+        Object.defineProperty(this, "lc_direct_tool_output", {
             enumerable: true,
             configurable: true,
             writable: true,
-            value: void 0
+            value: true
         });
         Object.defineProperty(this, "graph", {
             enumerable: true,
@@ -143,6 +202,12 @@ export class Command {
         });
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         Object.defineProperty(this, "update", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "resume", {
             enumerable: true,
             configurable: true,
             writable: true,
@@ -161,6 +226,20 @@ export class Command {
             this.goto = Array.isArray(args.goto) ? args.goto : [args.goto];
         }
     }
+    _updateAsTuples() {
+        if (this.update &&
+            typeof this.update === "object" &&
+            !Array.isArray(this.update)) {
+            return Object.entries(this.update);
+        }
+        else if (Array.isArray(this.update) &&
+            this.update.every((t) => Array.isArray(t) && t.length === 2 && typeof t[0] === "string")) {
+            return this.update;
+        }
+        else {
+            return [["__root__", this.update]];
+        }
+    }
 }
 Object.defineProperty(Command, "PARENT", {
     enumerable: true,
@@ -168,6 +247,6 @@ Object.defineProperty(Command, "PARENT", {
     writable: true,
     value: "__parent__"
 });
-export function _isCommand(x) {
+export function isCommand(x) {
     return typeof x === "object" && !!x && x.lg_name === "Command";
 }

package/dist/errors.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getSubgraphsSeenSet = exports.RemoteException = exports.MultipleSubgraphsError = exports.InvalidUpdateError = exports.EmptyChannelError = exports.EmptyInputError = exports.isGraphInterrupt = exports.isGraphBubbleUp = exports.isParentCommand = exports.ParentCommand = exports.NodeInterrupt = exports.GraphInterrupt = exports.GraphValueError = exports.GraphRecursionError = exports.GraphBubbleUp = exports.BaseLangGraphError = void 0;
+exports.getSubgraphsSeenSet = exports.RemoteException = exports.UnreachableNodeError = exports.MultipleSubgraphsError = exports.InvalidUpdateError = exports.EmptyChannelError = exports.EmptyInputError = exports.isGraphInterrupt = exports.isGraphBubbleUp = exports.isParentCommand = exports.ParentCommand = exports.NodeInterrupt = exports.GraphInterrupt = exports.GraphValueError = exports.GraphRecursionError = exports.GraphBubbleUp = exports.BaseLangGraphError = void 0;
 // TODO: Merge with base LangChain error class when we drop support for core@0.2.0
 class BaseLangGraphError extends Error {
     constructor(message, fields) {
@@ -153,6 +153,16 @@ class MultipleSubgraphsError extends BaseLangGraphError {
     }
 }
 exports.MultipleSubgraphsError = MultipleSubgraphsError;
+class UnreachableNodeError extends BaseLangGraphError {
+    constructor(message, fields) {
+        super(message, fields);
+        this.name = "UnreachableNodeError";
+    }
+    static get unminifiable_name() {
+        return "UnreachableNodeError";
+    }
+}
+exports.UnreachableNodeError = UnreachableNodeError;
 /**
  * Exception raised when an error occurs in the remote graph.
  */

package/dist/errors.d.ts

@@ -51,6 +51,10 @@ export declare class MultipleSubgraphsError extends BaseLangGraphError {
     constructor(message?: string, fields?: BaseLangGraphErrorFields);
     static get unminifiable_name(): string;
 }
+export declare class UnreachableNodeError extends BaseLangGraphError {
+    constructor(message?: string, fields?: BaseLangGraphErrorFields);
+    static get unminifiable_name(): string;
+}
 /**
  * Exception raised when an error occurs in the remote graph.
  */

package/dist/errors.js

@@ -136,6 +136,15 @@ export class MultipleSubgraphsError extends BaseLangGraphError {
         return "MultipleSubgraphError";
     }
 }
+export class UnreachableNodeError extends BaseLangGraphError {
+    constructor(message, fields) {
+        super(message, fields);
+        this.name = "UnreachableNodeError";
+    }
+    static get unminifiable_name() {
+        return "UnreachableNodeError";
+    }
+}
 /**
  * Exception raised when an error occurs in the remote graph.
  */

package/dist/graph/graph.cjs

@@ -299,7 +299,15 @@ class Graph {
         // validate targets
         for (const node of Object.keys(this.nodes)) {
             if (!allTargets.has(node)) {
-                throw new Error(`Node \`${node}\` is not reachable`);
+                throw new errors_js_1.UnreachableNodeError([
+                    `Node \`${node}\` is not reachable.`,
+                    "",
+                    "If you are returning Command objects from your node,",
+                    'make sure you are passing names of potential destination nodes as an "ends" array',
+                    'into ".addNode(..., { ends: ["node1", "node2"] })".',
+                ].join("\n"), {
+                    lc_error_code: "UNREACHABLE_NODE",
+                });
             }
         }
         for (const target of allTargets) {

package/dist/graph/graph.js

@@ -9,7 +9,7 @@ import { EphemeralValue } from "../channels/ephemeral_value.js";
 import { ChannelWrite, PASSTHROUGH } from "../pregel/write.js";
 import { _isSend, CHECKPOINT_NAMESPACE_END, CHECKPOINT_NAMESPACE_SEPARATOR, TAG_HIDDEN, } from "../constants.js";
 import { gatherIterator, gatherIteratorSync, RunnableCallable, } from "../utils.js";
-import { InvalidUpdateError, NodeInterrupt } from "../errors.js";
+import { InvalidUpdateError, NodeInterrupt, UnreachableNodeError, } from "../errors.js";
 import { isPregelLike } from "../pregel/utils/subgraph.js";
 /** Special reserved node name denoting the start of a graph. */
 export const START = "__start__";
@@ -295,7 +295,15 @@ export class Graph {
         // validate targets
         for (const node of Object.keys(this.nodes)) {
             if (!allTargets.has(node)) {
-                throw new Error(`Node \`${node}\` is not reachable`);
+                throw new UnreachableNodeError([
+                    `Node \`${node}\` is not reachable.`,
+                    "",
+                    "If you are returning Command objects from your node,",
+                    'make sure you are passing names of potential destination nodes as an "ends" array',
+                    'into ".addNode(..., { ends: ["node1", "node2"] })".',
+                ].join("\n"), {
+                    lc_error_code: "UNREACHABLE_NODE",
+                });
             }
         }
         for (const target of allTargets) {

package/dist/graph/state.cjs

@@ -347,59 +347,101 @@ function _getChannels(schema) {
  */
 class CompiledStateGraph extends graph_js_1.CompiledGraph {
     attachNode(key, node) {
-        const stateKeys = Object.keys(this.builder.channels);
+        let outputKeys;
+        if (key === graph_js_1.START) {
+            // Get input schema keys excluding managed values
+            outputKeys = Object.entries(this.builder._schemaDefinitions.get(this.builder._inputDefinition))
+                .filter(([_, v]) => !(0, base_js_2.isConfiguredManagedValue)(v))
+                .map(([k]) => k);
+        }
+        else {
+            outputKeys = Object.keys(this.builder.channels);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         function _getRoot(input) {
-            if ((0, constants_js_1._isCommand)(input)) {
+            if ((0, constants_js_1.isCommand)(input)) {
                 if (input.graph === constants_js_1.Command.PARENT) {
-                    return write_js_1.SKIP_WRITE;
+                    return null;
+                }
+                return input._updateAsTuples();
+            }
+            else if (Array.isArray(input) &&
+                input.length > 0 &&
+                input.some((i) => (0, constants_js_1.isCommand)(i))) {
+                const updates = [];
+                for (const i of input) {
+                    if ((0, constants_js_1.isCommand)(i)) {
+                        if (i.graph === constants_js_1.Command.PARENT) {
+                            continue;
+                        }
+                        updates.push(...i._updateAsTuples());
+                    }
+                    else {
+                        updates.push([ROOT, i]);
+                    }
                 }
-                return input.update;
+                return updates;
             }
-            return input;
+            else if (input != null) {
+                return [[ROOT, input]];
+            }
+            return null;
         }
         // to avoid name collision below
         const nodeKey = key;
-        function getStateKey(key, input) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        function _getUpdates(input) {
             if (!input) {
-                return write_js_1.SKIP_WRITE;
+                return null;
             }
-            else if ((0, constants_js_1._isCommand)(input)) {
+            else if ((0, constants_js_1.isCommand)(input)) {
                 if (input.graph === constants_js_1.Command.PARENT) {
-                    return write_js_1.SKIP_WRITE;
+                    return null;
                 }
-                return getStateKey(key, input.update);
+                return input._updateAsTuples();
             }
-            else if (typeof input !== "object" || Array.isArray(input)) {
+            else if (Array.isArray(input) &&
+                input.length > 0 &&
+                input.some(constants_js_1.isCommand)) {
+                const updates = [];
+                for (const item of input) {
+                    if ((0, constants_js_1.isCommand)(item)) {
+                        if (item.graph === constants_js_1.Command.PARENT) {
+                            continue;
+                        }
+                        updates.push(...item._updateAsTuples());
+                    }
+                    else {
+                        const itemUpdates = _getUpdates(item);
+                        if (itemUpdates) {
+                            updates.push(...(itemUpdates ?? []));
+                        }
+                    }
+                }
+                return updates;
+            }
+            else if (typeof input === "object" && !Array.isArray(input)) {
+                return Object.entries(input).filter(([k]) => outputKeys.includes(k));
+            }
+            else {
                 const typeofInput = Array.isArray(input) ? "array" : typeof input;
                 throw new errors_js_1.InvalidUpdateError(`Expected node "${nodeKey.toString()}" to return an object, received ${typeofInput}`, {
                     lc_error_code: "INVALID_GRAPH_NODE_RETURN_VALUE",
                 });
             }
-            else {
-                return key in input ? input[key] : write_js_1.SKIP_WRITE;
-            }
         }
-        // state updaters
-        const stateWriteEntries = stateKeys.map((key) => key === ROOT
-            ? {
-                channel: key,
+        const stateWriteEntries = [
+            {
                 value: write_js_1.PASSTHROUGH,
-                skipNone: true,
                 mapper: new utils_js_1.RunnableCallable({
-                    func: _getRoot,
+                    func: outputKeys.length && outputKeys[0] === ROOT
+                        ? _getRoot
+                        : _getUpdates,
                     trace: false,
                     recurse: false,
                 }),
-            }
-            : {
-                channel: key,
-                value: write_js_1.PASSTHROUGH,
-                mapper: new utils_js_1.RunnableCallable({
-                    func: getStateKey.bind(null, key),
-                    trace: false,
-                    recurse: false,
-                }),
-            });
+            },
+        ];
         // add node and output channel
         if (key === graph_js_1.START) {
             this.nodes[key] = new read_js_1.PregelNode({
@@ -541,7 +583,7 @@ function _controlBranch(value) {
     if ((0, constants_js_1._isSend)(value)) {
         return [value];
     }
-    if (!(0, constants_js_1._isCommand)(value)) {
+    if (!(0, constants_js_1.isCommand)(value)) {
         return [];
     }
     if (value.graph === constants_js_1.Command.PARENT) {