Implementation:Explodinggradients Ragas LangGraph Convert Messages

LangGraph Convert Messages

LangGraph Convert Messages is a wrapper module in the Ragas library that converts LangChain/LangGraph message objects into Ragas standard message types, enabling evaluation of agent conversations built with the LangGraph framework.

Type

Wrapper Doc

Source Location

File: src/ragas/integrations/langgraph.py (lines 9-110)
Repository: explodinggradients/ragas

Import

from ragas.integrations.langgraph import convert_to_ragas_messages

Function Signature

def convert_to_ragas_messages(
    messages: List[Union[HumanMessage, SystemMessage, AIMessage, ToolMessage]],
    metadata: bool = False,
) -> List[Union[r.HumanMessage, r.AIMessage, r.ToolMessage]]

Parameters

Parameter	Type	Default	Description
`messages`	`List[Union[HumanMessage, SystemMessage, AIMessage, ToolMessage]]`	(required)	List of LangChain message objects to be converted. These are imported from `langchain_core.messages`.
`metadata`	`bool`	`False`	Whether to include framework-specific metadata in the converted Ragas messages. When True, all message attributes except `content` are preserved in the `metadata` field.

Return Value

A list of Ragas message objects: List[Union[r.HumanMessage, r.AIMessage, r.ToolMessage]]

SystemMessage instances from LangChain are silently skipped and not included in the output.

Exceptions

Exception	Condition
`ValueError`	An unsupported message type is encountered (not HumanMessage, SystemMessage, AIMessage, or ToolMessage)
`TypeError`	A message's `content` field is not a string

Conversion Logic

Message Type Mapping

LangChain Type	Ragas Type	Notes
`langchain_core.messages.HumanMessage`	`ragas.messages.HumanMessage`	Direct content transfer
`langchain_core.messages.AIMessage`	`ragas.messages.AIMessage`	Content transfer plus tool call extraction
`langchain_core.messages.ToolMessage`	`ragas.messages.ToolMessage`	Direct content transfer
`langchain_core.messages.SystemMessage`	(skipped)	System messages are not included in evaluation

Tool Call Extraction

For AIMessage instances, tool calls are extracted from the LangChain message's additional_kwargs dictionary:

def _extract_tool_calls(message: AIMessage) -> List[r.ToolCall]:
    tool_calls = message.additional_kwargs.get("tool_calls", [])
    return [
        r.ToolCall(
            name=tool_call["function"]["name"],
            args=json.loads(tool_call["function"]["arguments"]),
        )
        for tool_call in tool_calls
    ]

Each tool call in LangChain's format has a nested function dictionary containing name (string) and arguments (JSON-encoded string). The arguments string is parsed via json.loads into a Python dictionary.

If the AI message has no additional_kwargs, tool_calls is set to None.

Metadata Extraction

When metadata=True, the function extracts all attributes from the original message except content:

def _extract_metadata(message) -> dict:
    return {k: v for k, v in message.__dict__.items() if k != "content"}

This preserves framework-specific information such as response IDs, token usage, and model metadata.

Content Validation

All message types have their content field validated to be a string. Non-string content (such as lists of content blocks used by some LangChain multimodal messages) raises a TypeError:

def _validate_string_content(message, message_type: str) -> str:
    if not isinstance(message.content, str):
        raise TypeError(
            f"{message_type} content must be a string, got {type(message.content).__name__}. "
            f"Content: {message.content}"
        )
    return message.content

Usage Example

from langchain_core.messages import HumanMessage, AIMessage, ToolMessage
from ragas.integrations.langgraph import convert_to_ragas_messages
from ragas.dataset_schema import MultiTurnSample

# LangGraph conversation messages
langgraph_messages = [
    HumanMessage(content="Find me a Chinese restaurant"),
    AIMessage(
        content="Let me search for that.",
        additional_kwargs={
            "tool_calls": [
                {
                    "function": {
                        "name": "restaurant_search",
                        "arguments": '{"cuisine": "Chinese"}'
                    }
                }
            ]
        }
    ),
    ToolMessage(content="Found: Golden Dragon, Jade Palace"),
    AIMessage(content="I found Golden Dragon and Jade Palace.")
]

# Convert to Ragas messages
ragas_messages = convert_to_ragas_messages(langgraph_messages)

# Use in evaluation
sample = MultiTurnSample(
    user_input=ragas_messages,
    reference_tool_calls=[...]
)

Usage with Metadata

# Include metadata for debugging
ragas_messages_with_meta = convert_to_ragas_messages(langgraph_messages, metadata=True)

# Each message now has a metadata field with framework-specific attributes
for msg in ragas_messages_with_meta:
    if msg.metadata:
        print(msg.metadata)

External Reference

LangGraph Documentation -- the LangGraph framework for building multi-agent systems with LangChain

Internal Dependencies

langchain_core.messages -- LangChain message types (HumanMessage, AIMessage, ToolMessage, SystemMessage)
ragas.messages -- Ragas standard message types (HumanMessage, AIMessage, ToolMessage, ToolCall)
json -- for parsing JSON-encoded tool call arguments

Implements

Framework Message Conversion -- the principle of converting framework-specific messages to Ragas standard types

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment