feat(langgraph): allow explicit type declaration for interrupt and custom stream events

[dqbd]

Sample:

import { interrupt, writer } from "@langchain/langgraph";

const builder = new StateGraph(
  z.object({
    messages: z.custom<BaseMessage[]>().register(registry, MessagesZodMeta),
    innerReason: z.string(),
  }),
  {
    input: z.object({
      messages: z.custom<BaseMessage[]>().register(registry, MessagesZodMeta),
    }),

    // Allow specifying types for interrupts and writes
    writer: writer<{ custom: string }>,
    interrupt: interrupt<{ reason: string }, { messages: string[] }>,

    // Allow optionally specifying all nodes upfront.
    // This is needed to properly type `goto` commands and removes
    // friction when dynamically constructing graphs.
    nodes: ["hello", "what"],
  }
);

const node: typeof builder.Node = async (_, runtime) => {
  const result = runtime.interrupt?.({ reason: "hello" });
  if (result != null) {
    runtime.writer?.({ custom: "hello" });
    return { messages: result.messages };
  }
  return {};
};

builder.addNode("hello", node);
builder.addEdge("__start__", "hello");

const graph = builder.compile();

const invoke = await graph.invoke({ messages: "input" });
if (graph.isInterrupted(invoke)) {
  // ... invoke[INTERRUPT].value == { reason: string }
}

This PR also removes undocumented typedNode helper, which has been superseded by this PR

[changeset-bot]

🦋 Changeset detected

Latest commit: 0053c17

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[christian-bromann]

Are there cases where writer is not defined? Wonder if we can remove the optionality.

[dqbd]

Writer is currently defined only when custom stream mode is requested

[christian-bromann]

Yeah, that's not possible to type. In this case, I would advocate to remove the optionality afterall and throw a meaningful error at runtime, because the optionality doesn't really provide any value IMHO.

[christian-bromann]

Is it possible to infer the existence of interrupt based on whether a checkpointer parameter was provided?

[dqbd]

Since I'd like to support creating the builder separately, that would entail making checkpointer a constructor parameter.

An alternative I think can be always providing the function in runtime but throwing an error in runtime if no checkpointer is passed

[christian-bromann]

I think we throw an error already that is meaningful enough.

[christian-bromann]

How is Runtime different from LangGraphRunnableConfig? Both seem to have very similar types. Maybe we can do:

export interface Runtime<
  ContextType = Record<string, unknown>,
  InterruptType = unknown,
  WriterType = unknown
> extends LangGraphRunnableConfig<ContextType, InterruptType, WriterType> {
  signal?: AbortSignal;
}

[dqbd]

Runtime is a pruned version of LangGraphRunnableConfig, so ideally it should be in reverse.