@langchain/langgraph 0.2.39 → 0.2.41

package/dist/prebuilt/index.d.ts

@@ -3,3 +3,4 @@ export { type FunctionCallingExecutorState, createFunctionCallingExecutor, } fro
 export { type AgentState, type CreateReactAgentParams, createReactAgent, } from "./react_agent_executor.js";
 export { type ToolExecutorArgs, type ToolInvocationInterface, ToolExecutor, } from "./tool_executor.js";
 export { ToolNode, toolsCondition, type ToolNodeOptions } from "./tool_node.js";
+export type { HumanInterruptConfig, ActionRequest, HumanInterrupt, HumanResponse, } from "./interrupt.js";

package/dist/prebuilt/interrupt.cjs

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/prebuilt/interrupt.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Configuration interface that defines what actions are allowed for a human interrupt.
+ * This controls the available interaction options when the graph is paused for human input.
+ *
+ * @property {boolean} allow_ignore - Whether the human can choose to ignore/skip the current step
+ * @property {boolean} allow_respond - Whether the human can provide a text response/feedback
+ * @property {boolean} allow_edit - Whether the human can edit the provided content/state
+ * @property {boolean} allow_accept - Whether the human can accept/approve the current state
+ */
+export interface HumanInterruptConfig {
+    allow_ignore: boolean;
+    allow_respond: boolean;
+    allow_edit: boolean;
+    allow_accept: boolean;
+}
+/**
+ * Represents a request for human action within the graph execution.
+ * Contains the action type and any associated arguments needed for the action.
+ *
+ * @property {string} action - The type or name of action being requested (e.g., "Approve XYZ action")
+ * @property {Record<string, any>} args - Key-value pairs of arguments needed for the action
+ */
+export interface ActionRequest {
+    action: string;
+    args: Record<string, any>;
+}
+/**
+ * Represents an interrupt triggered by the graph that requires human intervention.
+ * This is passed to the `interrupt` function when execution is paused for human input.
+ *
+ * @property {ActionRequest} action_request - The specific action being requested from the human
+ * @property {HumanInterruptConfig} config - Configuration defining what actions are allowed
+ * @property {string} [description] - Optional detailed description of what input is needed
+ */
+export interface HumanInterrupt {
+    action_request: ActionRequest;
+    config: HumanInterruptConfig;
+    description?: string;
+}
+/**
+ * The response provided by a human to an interrupt, which is returned when graph execution resumes.
+ *
+ * @property {("accept"|"ignore"|"response"|"edit")} type - The type of response:
+ *   - "accept": Approves the current state without changes
+ *   - "ignore": Skips/ignores the current step
+ *   - "response": Provides text feedback or instructions
+ *   - "edit": Modifies the current state/content
+ * @property {null|string|ActionRequest} args - The response payload:
+ *   - null: For ignore/accept actions
+ *   - string: For text responses
+ *   - ActionRequest: For edit actions with updated content
+ */
+export type HumanResponse = {
+    type: "accept" | "ignore" | "response" | "edit";
+    args: null | string | ActionRequest;
+};

package/dist/prebuilt/interrupt.js

@@ -0,0 +1 @@
+export {};

package/dist/prebuilt/react_agent_executor.cjs

@@ -1,11 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createReactAgent = void 0;
+exports.createReactAgent = exports.createReactAgentAnnotation = void 0;
 const messages_1 = require("@langchain/core/messages");
 const runnables_1 = require("@langchain/core/runnables");
 const index_js_1 = require("../graph/index.cjs");
-const messages_annotation_js_1 = require("../graph/messages_annotation.cjs");
 const tool_node_js_1 = require("./tool_node.cjs");
+const annotation_js_1 = require("../graph/annotation.cjs");
+const message_js_1 = require("../graph/message.cjs");
 function _convertMessageModifierToStateModifier(messageModifier) {
     // Handle string or SystemMessage
     if (typeof messageModifier === "string" ||
@@ -65,6 +66,14 @@ function _getModelPreprocessingRunnable(stateModifier, messageModifier) {
     }
     return _getStateModifierRunnable(stateModifier);
 }
+const createReactAgentAnnotation = () => annotation_js_1.Annotation.Root({
+    messages: (0, annotation_js_1.Annotation)({
+        reducer: message_js_1.messagesStateReducer,
+        default: () => [],
+    }),
+    structuredResponse: (annotation_js_1.Annotation),
+});
+exports.createReactAgentAnnotation = createReactAgentAnnotation;
 /**
  * Creates a StateGraph agent that relies on a chat model utilizing tool calling.
  *
@@ -108,7 +117,7 @@ function _getModelPreprocessingRunnable(stateModifier, messageModifier) {
  * ```
  */
 function createReactAgent(params) {
-    const { llm, tools, messageModifier, stateModifier, stateSchema, checkpointSaver, interruptBefore, interruptAfter, store, } = params;
+    const { llm, tools, messageModifier, stateModifier, stateSchema, checkpointSaver, interruptBefore, interruptAfter, store, responseFormat, } = params;
     let toolClasses;
     if (!Array.isArray(tools)) {
         toolClasses = tools.tools;
@@ -128,25 +137,58 @@ function createReactAgent(params) {
         const lastMessage = messages[messages.length - 1];
         if ((0, messages_1.isAIMessage)(lastMessage) &&
             (!lastMessage.tool_calls || lastMessage.tool_calls.length === 0)) {
-            return index_js_1.END;
+            return responseFormat != null ? "generate_structured_response" : index_js_1.END;
         }
         else {
             return "continue";
         }
     };
+    const generateStructuredResponse = async (state, config) => {
+        if (responseFormat == null) {
+            throw new Error("Attempted to generate structured output with no passed response schema. Please contact us for help.");
+        }
+        // Exclude the last message as there's enough information
+        // for the LLM to generate the structured response
+        const messages = state.messages.slice(0, -1);
+        let modelWithStructuredOutput;
+        if (typeof responseFormat === "object" &&
+            "prompt" in responseFormat &&
+            "schema" in responseFormat) {
+            const { prompt, schema } = responseFormat;
+            modelWithStructuredOutput = llm.withStructuredOutput(schema);
+            messages.unshift(new messages_1.SystemMessage({ content: prompt }));
+        }
+        else {
+            modelWithStructuredOutput = llm.withStructuredOutput(responseFormat);
+        }
+        const response = await modelWithStructuredOutput.invoke(messages, config);
+        return { structuredResponse: response };
+    };
     const callModel = async (state, config) => {
         // TODO: Auto-promote streaming.
         return { messages: [await modelRunnable.invoke(state, config)] };
     };
-    const workflow = new index_js_1.StateGraph(stateSchema ?? messages_annotation_js_1.MessagesAnnotation)
+    const workflow = new index_js_1.StateGraph(stateSchema ?? (0, exports.createReactAgentAnnotation)())
         .addNode("agent", callModel)
         .addNode("tools", new tool_node_js_1.ToolNode(toolClasses))
         .addEdge(index_js_1.START, "agent")
-        .addConditionalEdges("agent", shouldContinue, {
-        continue: "tools",
-        [index_js_1.END]: index_js_1.END,
-    })
         .addEdge("tools", "agent");
+    if (responseFormat !== undefined) {
+        workflow
+            .addNode("generate_structured_response", generateStructuredResponse)
+            .addEdge("generate_structured_response", index_js_1.END)
+            .addConditionalEdges("agent", shouldContinue, {
+            continue: "tools",
+            [index_js_1.END]: index_js_1.END,
+            generate_structured_response: "generate_structured_response",
+        });
+    }
+    else {
+        workflow.addConditionalEdges("agent", shouldContinue, {
+            continue: "tools",
+            [index_js_1.END]: index_js_1.END,
+        });
+    }
     return workflow.compile({
         checkpointer: checkpointSaver,
         interruptBefore,

package/dist/prebuilt/react_agent_executor.d.ts

@@ -3,18 +3,33 @@ import { BaseMessage, BaseMessageLike, SystemMessage } from "@langchain/core/mes
 import { Runnable, RunnableToolLike } from "@langchain/core/runnables";
 import { StructuredToolInterface } from "@langchain/core/tools";
 import { All, BaseCheckpointSaver, BaseStore } from "@langchain/langgraph-checkpoint";
+import { z } from "zod";
 import { START, CompiledStateGraph, AnnotationRoot } from "../graph/index.js";
 import { MessagesAnnotation } from "../graph/messages_annotation.js";
 import { ToolNode } from "./tool_node.js";
 import { LangGraphRunnableConfig } from "../pregel/runnable_types.js";
-export interface AgentState {
+import { Messages } from "../graph/message.js";
+export interface AgentState<StructuredResponseType extends Record<string, any> = Record<string, any>> {
     messages: BaseMessage[];
+    structuredResponse: StructuredResponseType;
 }
 export type N = typeof START | "agent" | "tools";
+export type StructuredResponseSchemaAndPrompt<StructuredResponseType> = {
+    prompt: string;
+    schema: z.ZodType<StructuredResponseType> | Record<string, any>;
+};
 export type StateModifier = SystemMessage | string | ((state: typeof MessagesAnnotation.State, config: LangGraphRunnableConfig) => BaseMessageLike[]) | ((state: typeof MessagesAnnotation.State, config: LangGraphRunnableConfig) => Promise<BaseMessageLike[]>) | Runnable;
 /** @deprecated Use StateModifier instead. */
 export type MessageModifier = SystemMessage | string | ((messages: BaseMessage[]) => BaseMessage[]) | ((messages: BaseMessage[]) => Promise<BaseMessage[]>) | Runnable;
-export type CreateReactAgentParams<A extends AnnotationRoot<any> = AnnotationRoot<any>> = {
+export declare const createReactAgentAnnotation: <T extends Record<string, any> = Record<string, any>>() => AnnotationRoot<{
+    messages: import("../web.js").BinaryOperatorAggregate<BaseMessage[], Messages>;
+    structuredResponse: {
+        (): import("../web.js").LastValue<T>;
+        (annotation: import("../graph/annotation.js").SingleReducer<T, T>): import("../web.js").BinaryOperatorAggregate<T, T>;
+        Root: <S extends import("../graph/annotation.js").StateDefinition>(sd: S) => AnnotationRoot<S>;
+    };
+}>;
+export type CreateReactAgentParams<A extends AnnotationRoot<any> = AnnotationRoot<any>, StructuredResponseType = Record<string, any>> = {
     /** The chat model that can utilize OpenAI-style tool calling. */
     llm: BaseChatModel;
     /** A list of tools or a ToolNode. */
@@ -81,6 +96,19 @@ export type CreateReactAgentParams<A extends AnnotationRoot<any> = AnnotationRoo
     /** An optional list of node names to interrupt after running. */
     interruptAfter?: N[] | All;
     store?: BaseStore;
+    /**
+     * An optional schema for the final agent output.
+     *
+     * If provided, output will be formatted to match the given schema and returned in the 'structured_response' state key.
+     * If not provided, `structured_response` will not be present in the output state.
+     *
+     * Can be passed in as:
+     *   - Zod schema
+     *   - Dictionary object
+     *   - [prompt, schema], where schema is one of the above.
+     *        The prompt will be used together with the model that is being used to generate the structured response.
+     */
+    responseFormat?: z.ZodType<StructuredResponseType> | StructuredResponseSchemaAndPrompt<StructuredResponseType> | Record<string, any>;
 };
 /**
  * Creates a StateGraph agent that relies on a chat model utilizing tool calling.
@@ -124,4 +152,4 @@ export type CreateReactAgentParams<A extends AnnotationRoot<any> = AnnotationRoo
  * // Returns the messages in the state at each step of execution
  * ```
  */
-export declare function createReactAgent<A extends AnnotationRoot<any> = AnnotationRoot<any>>(params: CreateReactAgentParams<A>): CompiledStateGraph<(typeof MessagesAnnotation)["State"], (typeof MessagesAnnotation)["Update"], typeof START | "agent" | "tools", typeof MessagesAnnotation.spec & A["spec"], typeof MessagesAnnotation.spec & A["spec"]>;
+export declare function createReactAgent<A extends AnnotationRoot<any> = AnnotationRoot<{}>, StructuredResponseFormat extends Record<string, any> = Record<string, any>>(params: CreateReactAgentParams<A, StructuredResponseFormat>): CompiledStateGraph<(typeof MessagesAnnotation)["State"], (typeof MessagesAnnotation)["Update"], any, typeof MessagesAnnotation.spec & A["spec"], ReturnType<typeof createReactAgentAnnotation<StructuredResponseFormat>>["spec"] & A["spec"]>;

package/dist/prebuilt/react_agent_executor.js

@@ -1,8 +1,9 @@
 import { isAIMessage, isBaseMessage, SystemMessage, } from "@langchain/core/messages";
 import { Runnable, RunnableLambda, } from "@langchain/core/runnables";
 import { END, START, StateGraph, } from "../graph/index.js";
-import { MessagesAnnotation } from "../graph/messages_annotation.js";
 import { ToolNode } from "./tool_node.js";
+import { Annotation } from "../graph/annotation.js";
+import { messagesStateReducer } from "../graph/message.js";
 function _convertMessageModifierToStateModifier(messageModifier) {
     // Handle string or SystemMessage
     if (typeof messageModifier === "string" ||
@@ -62,6 +63,13 @@ function _getModelPreprocessingRunnable(stateModifier, messageModifier) {
     }
     return _getStateModifierRunnable(stateModifier);
 }
+export const createReactAgentAnnotation = () => Annotation.Root({
+    messages: Annotation({
+        reducer: messagesStateReducer,
+        default: () => [],
+    }),
+    structuredResponse: (Annotation),
+});
 /**
  * Creates a StateGraph agent that relies on a chat model utilizing tool calling.
  *
@@ -105,7 +113,7 @@ function _getModelPreprocessingRunnable(stateModifier, messageModifier) {
  * ```
  */
 export function createReactAgent(params) {
-    const { llm, tools, messageModifier, stateModifier, stateSchema, checkpointSaver, interruptBefore, interruptAfter, store, } = params;
+    const { llm, tools, messageModifier, stateModifier, stateSchema, checkpointSaver, interruptBefore, interruptAfter, store, responseFormat, } = params;
     let toolClasses;
     if (!Array.isArray(tools)) {
         toolClasses = tools.tools;
@@ -125,25 +133,58 @@ export function createReactAgent(params) {
         const lastMessage = messages[messages.length - 1];
         if (isAIMessage(lastMessage) &&
             (!lastMessage.tool_calls || lastMessage.tool_calls.length === 0)) {
-            return END;
+            return responseFormat != null ? "generate_structured_response" : END;
         }
         else {
             return "continue";
         }
     };
+    const generateStructuredResponse = async (state, config) => {
+        if (responseFormat == null) {
+            throw new Error("Attempted to generate structured output with no passed response schema. Please contact us for help.");
+        }
+        // Exclude the last message as there's enough information
+        // for the LLM to generate the structured response
+        const messages = state.messages.slice(0, -1);
+        let modelWithStructuredOutput;
+        if (typeof responseFormat === "object" &&
+            "prompt" in responseFormat &&
+            "schema" in responseFormat) {
+            const { prompt, schema } = responseFormat;
+            modelWithStructuredOutput = llm.withStructuredOutput(schema);
+            messages.unshift(new SystemMessage({ content: prompt }));
+        }
+        else {
+            modelWithStructuredOutput = llm.withStructuredOutput(responseFormat);
+        }
+        const response = await modelWithStructuredOutput.invoke(messages, config);
+        return { structuredResponse: response };
+    };
     const callModel = async (state, config) => {
         // TODO: Auto-promote streaming.
         return { messages: [await modelRunnable.invoke(state, config)] };
     };
-    const workflow = new StateGraph(stateSchema ?? MessagesAnnotation)
+    const workflow = new StateGraph(stateSchema ?? createReactAgentAnnotation())
         .addNode("agent", callModel)
         .addNode("tools", new ToolNode(toolClasses))
         .addEdge(START, "agent")
-        .addConditionalEdges("agent", shouldContinue, {
-        continue: "tools",
-        [END]: END,
-    })
         .addEdge("tools", "agent");
+    if (responseFormat !== undefined) {
+        workflow
+            .addNode("generate_structured_response", generateStructuredResponse)
+            .addEdge("generate_structured_response", END)
+            .addConditionalEdges("agent", shouldContinue, {
+            continue: "tools",
+            [END]: END,
+            generate_structured_response: "generate_structured_response",
+        });
+    }
+    else {
+        workflow.addConditionalEdges("agent", shouldContinue, {
+            continue: "tools",
+            [END]: END,
+        });
+    }
     return workflow.compile({
         checkpointer: checkpointSaver,
         interruptBefore,

package/dist/pregel/io.cjs

@@ -94,8 +94,15 @@ function* mapCommand(cmd, pendingWrites) {
         if (typeof cmd.update !== "object" || !cmd.update) {
             throw new Error("Expected cmd.update to be a dict mapping channel names to update values");
         }
-        for (const [k, v] of Object.entries(cmd.update)) {
-            yield [constants_js_1.NULL_TASK_ID, k, v];
+        if (Array.isArray(cmd.update)) {
+            for (const [k, v] of cmd.update) {
+                yield [constants_js_1.NULL_TASK_ID, k, v];
+            }
+        }
+        else {
+            for (const [k, v] of Object.entries(cmd.update)) {
+                yield [constants_js_1.NULL_TASK_ID, k, v];
+            }
         }
     }
 }

package/dist/pregel/io.js

@@ -89,8 +89,15 @@ export function* mapCommand(cmd, pendingWrites) {
         if (typeof cmd.update !== "object" || !cmd.update) {
             throw new Error("Expected cmd.update to be a dict mapping channel names to update values");
         }
-        for (const [k, v] of Object.entries(cmd.update)) {
-            yield [NULL_TASK_ID, k, v];
+        if (Array.isArray(cmd.update)) {
+            for (const [k, v] of cmd.update) {
+                yield [NULL_TASK_ID, k, v];
+            }
+        }
+        else {
+            for (const [k, v] of Object.entries(cmd.update)) {
+                yield [NULL_TASK_ID, k, v];
+            }
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@langchain/langgraph",
-  "version": "0.2.39",
+  "version": "0.2.41",
   "description": "LangGraph",
   "type": "module",
   "engines": {
@@ -72,7 +72,7 @@
     "pg": "^8.13.0",
     "prettier": "^2.8.3",
     "release-it": "^17.6.0",
-    "rollup": "^4.24.1",
+    "rollup": "^4.29.0",
     "ts-jest": "^29.1.0",
     "tsx": "^4.7.0",
     "typescript": "^4.9.5 || ^5.4.5",