Implementation:Explodinggradients Ragas Messages Module

Metadata	Value
Source	src/ragas/messages.py (Lines 6-134)
Domains	Data_Model, Messages
Last Updated	2026-02-10

Overview

Defines the core message type hierarchy used throughout Ragas for representing conversations between humans, AI models, and tools, built on Pydantic BaseModel.

Description

This module provides five Pydantic model classes that form the message type system:

• Message is the base class with a content (str) field and an optional metadata (Dict) field. All other message types inherit from it.

• ToolCall represents a tool invocation with a name (str) and args (Dict[str, Any]). It is not a message itself but is referenced by AIMessage.

• HumanMessage represents a user message. It has a fixed type literal of "human" and a pretty_repr() method that formats the content as "Human: {content}".

• ToolMessage represents output from a tool execution. It has a fixed type literal of "tool" and a pretty_repr() that formats as "ToolOutput: {content}".

• AIMessage represents a response from an AI model. It has:
  • A fixed type literal of "ai".
  • An optional tool_calls field (List[ToolCall]) for when the AI invokes tools.
  • A to_dict() method that serializes the message, nesting tool calls under a "tool_calls" key within the content when present.
  • A pretty_repr() method that formats the content and lists any tool calls with their arguments.

All classes use Pydantic for validation and serialization.

Usage

These message types are used throughout Ragas for:

• Representing multi-turn conversations in evaluation samples.
• Converting framework-specific trace data (Amazon Bedrock, LlamaIndex) into a standardized format.
• Providing human-readable representations of conversation traces via pretty_repr().

Code Reference

Source Location

Item	Detail
File	src/ragas/messages.py
Lines	6-134
Module	ragas.messages

Class Signatures

class Message(BaseModel):
    content: str
    metadata: Optional[Dict[str, Any]] = None

class ToolCall(BaseModel):
    name: str
    args: Dict[str, Any]

class HumanMessage(Message):
    type: Literal["human"] = "human"
    def pretty_repr(self) -> str: ...

class ToolMessage(Message):
    type: Literal["tool"] = "tool"
    def pretty_repr(self) -> str: ...

class AIMessage(Message):
    type: Literal["ai"] = "ai"
    tool_calls: Optional[List[ToolCall]] = None
    metadata: Optional[Dict[str, Any]] = None
    def to_dict(self, **kwargs) -> dict: ...
    def pretty_repr(self) -> str: ...

Import

from ragas.messages import HumanMessage, AIMessage, ToolCall, ToolMessage

I/O Contract

Class Hierarchy

Class	Parent	Type Literal	Key Fields
Message	BaseModel	(none)	content, metadata
HumanMessage	Message	"human"	content, metadata
ToolMessage	Message	"tool"	content, metadata
AIMessage	Message	"ai"	content, metadata, tool_calls
ToolCall	BaseModel	(none)	name, args

AIMessage.to_dict() Output Format

Condition	Output Structure
No tool calls	{"content": "text", "type": "ai"}
With tool calls	{"content": {"text": "text", "tool_calls": [{"name": ..., "args": ...}]}, "type": "ai"}

Usage Examples

Creating Messages

from ragas.messages import HumanMessage, AIMessage, ToolCall, ToolMessage

# Create a human message
human_msg = HumanMessage(content="What is the weather in London?")
print(human_msg.pretty_repr())
# "Human: What is the weather in London?"

# Create an AI message with tool calls
ai_msg = AIMessage(
    content="Let me check the weather for you.",
    tool_calls=[
        ToolCall(name="get_weather", args={"city": "London"}),
    ],
)
print(ai_msg.pretty_repr())
# "AI: Let me check the weather for you."
# "Tools:"
# "  get_weather: {'city': 'London'}"

# Create a tool response
tool_msg = ToolMessage(content="London: 15C, partly cloudy")
print(tool_msg.pretty_repr())
# "ToolOutput: London: 15C, partly cloudy"

Serializing an AI Message

from ragas.messages import AIMessage, ToolCall

msg = AIMessage(
    content="I'll search for that.",
    tool_calls=[ToolCall(name="search", args={"query": "RAG evaluation"})],
)

# Serialize to dictionary
data = msg.to_dict()
# {"content": {"text": "I'll search for that.",
#              "tool_calls": [{"name": "search", "args": {"query": "RAG evaluation"}}]},
#  "type": "ai"}

Using with Metadata

from ragas.messages import HumanMessage, AIMessage

human_msg = HumanMessage(
    content="Explain RAG.",
    metadata={"timestamp": "2026-01-01T00:00:00Z", "session_id": "abc123"},
)

ai_msg = AIMessage(
    content="RAG stands for Retrieval Augmented Generation.",
    metadata={"model": "gpt-4o", "latency_ms": 245},
)

Related Pages

• Amazon Bedrock Integration - Converts Bedrock traces to HumanMessage and AIMessage
• LlamaIndex Integration - Converts LlamaIndex agent events to the full message hierarchy including ToolCall and ToolMessage
• EvaluatorChain Class - Processes evaluation inputs that may contain message data