isAiMessageChunk returns true for instance of AIMessage - is it a bug?

[abogacki]

Checked other resources

• I added a very descriptive title to this question.
• I searched the LangChain documentation with the integrated search.
• I used the GitHub search to find a similar question and didn't find it.

Commit to Help

• I commit to help with one of those options 👆

Example Code

const State = MessagesAnnotation;

export const generateResponseNode = async (state: typeof State.State) => {
  const llm = new ChatOpenAI({
    model: "gpt-4.1-mini",
    temperature: 0.5,
    streaming: true,
  });

  const conversationPrompt = ChatPromptTemplate.fromMessages([
    [
      "system",
      `You are an AI in a chat platform.
      Respond to the conversation in a natural, engaging way.
      Keep responses short and social, not long essays.
      Reference recent messages when appropriate.`,
    ],
    ["human", "Recent messages: {recentMessages}"],
  ]);

  const message = state.messages[state.messages.length - 1];
  const formattedPrompt = await conversationPrompt.invoke({
    currentMessage: message.content,
    recentMessages: state.messages
      .map(
        (message) => `[${message.additional_kwargs?.name}]: ${message.content}`
      )
      .join("\n"),
  });

  const response = await llm.invoke(formattedPrompt);

  return {
    messages: [new AIMessage(response.content as string)],
  };
};

const graph = new StateGraph(State)
  .addNode("generate_response", generateResponseNode)
  .addEdge(START, "generate_response")
  .addEdge("generate_response", END)
  .compile();

export async function* langraphToWordsStreamTransducer(stream) {
  for await (const [message, metadata] of stream) {
    const node = metadata?.langgraph_node;
    if (
      isAIMessageChunk(message) && // the issue I mentioned is here - for the `AIMessage` instance, not `AIMessageChunk ` it returns true
      node === 'generate_response' &&
      message.content
    ) {
      yield message.content;
    }
  }
}

const streamResult = graph.stream({ messages: [new HumanMessage('Hello there')])

for await (const word of langraphToWordsStreamTransducer(await streamResult)) {
  if (word) {
    console.log(word);
  }
}

Description

I've am using LangGraph in streamMode: 'messages'. In last node of my graph I am producing an output that is written to MessagesAnnotation as AIMessage instance.
During the lifetime of the stream I am receiving chunks that are instances of AIMessageChunk class.
At the end of the stream, when output is produced and updates messages state, there's one last message that is instance of AIMessage class, and contains whole (due to the fact that I want to save the complete message as a single message in state.messages instead of saving each chunk separately).

I've created a transducer that converts chunks to words and I tried to yield results only in case it's a chunk (to prevent from duplicated yielding after the last state updates with AIMessage.
The problem is that isAiMessageChunk returns true, regardless if message is instance of BaseMessage or BaseMessageChunk.

Question is - is this a bug?
isAiMessageChunk could potentially check if message is instance of correct class like:

// curently
export function isAIMessage(x: BaseMessage): x is AIMessage {
  return x._getType() === "ai";
}

export function isAIMessageChunk(x: BaseMessageChunk): x is AIMessageChunk {
  return x._getType() === "ai";
}

// potentially
export function isAIMessage(x: BaseMessage): x is AIMessage {
  return x instanceof BaseMessage && x._getType() === "ai";
}

export function isAIMessageChunk(x: BaseMessageChunk): x is AIMessageChunk {
  return x instanceof BaseMessageChunk && x._getType() === "ai";
}

System Info

[email protected]
mac
[email protected]

[dosubot[bot]]

Hi @abogacki! I'm Dosu and I’m helping the langchainjs team.

This isn't a bug, but rather a limitation of the current implementation. Both isAIMessage and isAIMessageChunk only check if _getType() returns "ai", which is true for both AIMessage and AIMessageChunk instances. This means isAIMessageChunk will return true for an AIMessage as well, since both share the same type string and don't have a unique runtime discriminator beyond their class hierarchy. The intended differentiation relies on TypeScript's static typing and correct usage, not on runtime checks alone (source).

If you need to distinguish at runtime, you could extend the check to use instanceof BaseMessageChunk in your own utility, as you suggested. This would more reliably separate chunks from full messages in your streaming logic.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}   

[abogacki]

@dosu shouldn't this be handled within the library itself?

[dosubot[bot]]

Great question. The current implementation relies on TypeScript's static typing and the _getType() method, which returns "ai" for both AIMessage and AIMessageChunk. This means the provided type guards (isAIMessage, isAIMessageChunk) can't distinguish between the two at runtime, which can be confusing in streaming scenarios like yours. This isn't a bug, but it is a limitation of the current design—there's no runtime check for the actual class, just the type string, so both functions can return true for either class see source.

It would be reasonable for the library to improve these type guards to use instanceof checks, making them more robust for runtime differentiation. This would help prevent subtle bugs and make streaming workflows easier to implement safely. As of now, though, you'll need to add your own runtime checks (like instanceof BaseMessageChunk) if you need this distinction.

If you think this should be handled by the library, it's a valid suggestion and could be proposed as an enhancement to make the API safer and more intuitive for users.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}