Implementation:Explodinggradients Ragas Swarm Convert Messages

Swarm Convert Messages

Swarm Convert Messages is a wrapper module in the Ragas library that converts OpenAI Swarm framework message dictionaries into Ragas standard message types, enabling evaluation of agent conversations built with the Swarm framework.

Type

Wrapper Doc

Source Location

• File: src/ragas/integrations/swarm.py (lines 7-81)
• Repository: explodinggradients/ragas

Import

from ragas.integrations.swarm import convert_to_ragas_messages

Function Signature

def convert_to_ragas_messages(
    messages: List[Dict[str, Any]],
) -> List[Union[HumanMessage, AIMessage, ToolMessage]]

Parameters

Parameter	Type	Default	Description
messages	List[Dict[str, Any]]	(required)	List of Swarm message dictionaries. Each dictionary must contain a role key with one of: "user", "assistant", or "tool".

Return Value

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

Exceptions

Exception	Condition
KeyError	A message dictionary is missing the required role key
ValueError	A message has a role value that is not one of "assistant", "user", or "tool"

Conversion Logic

Role-Based Dispatching

The function iterates over each message dictionary and dispatches based on the role field:

for message in messages:
    role = message.get("role")
    if role is None:
        raise KeyError("'role' key not present in message")

    if role == "assistant":
        converted_messages.append(handle_assistant_message(message))
    elif role == "tool":
        converted_messages.append(handle_tool_message(message))
    elif role == "user":
        converted_messages.append(handle_user_message(message))
    else:
        raise ValueError(
            f"Role must be one of ['assistant', 'user', 'tool'], but found '{role}'"
        )

User Message Handling

def handle_user_message(message: Dict[str, str]) -> HumanMessage:
    return HumanMessage(content=message["content"])

Extracts the content field and creates a Ragas HumanMessage.

Assistant Message Handling

def handle_assistant_message(message: Dict[str, Any]) -> AIMessage:
    tool_calls = (
        convert_tool_calls(message["tool_calls"]) if message["tool_calls"] else []
    )
    ai_message_content = message.get("content")
    return AIMessage(
        content=ai_message_content if ai_message_content else "",
        tool_calls=tool_calls,
    )

Handles the assistant message by:

1. Extracting and converting tool calls (if present)
2. Getting the content field, defaulting to an empty string if None
3. Constructing a Ragas AIMessage

Tool Call Conversion

def convert_tool_calls(tool_calls_data: List[Dict[str, Any]]) -> List[ToolCall]:
    return [
        ToolCall(
            name=tool_call["function"]["name"],
            args=json.loads(tool_call["function"]["arguments"]),
        )
        for tool_call in tool_calls_data
    ]

Converts Swarm's OpenAI-format tool calls to Ragas ToolCall objects. The function.arguments field is a JSON-encoded string that is parsed via json.loads into a Python dictionary.

Tool Message Handling

def handle_tool_message(message: Dict[str, str]) -> ToolMessage:
    return ToolMessage(content=message["content"])

Extracts the content field and creates a Ragas ToolMessage.

Usage Example

from ragas.integrations.swarm import convert_to_ragas_messages
from ragas.dataset_schema import MultiTurnSample

# Swarm conversation messages (plain dictionaries)
swarm_messages = [
    {"role": "user", "content": "Find me a Chinese restaurant"},
    {
        "role": "assistant",
        "content": "Let me search for that.",
        "tool_calls": [
            {
                "function": {
                    "name": "restaurant_search",
                    "arguments": '{"cuisine": "Chinese"}'
                }
            }
        ]
    },
    {"role": "tool", "content": "Found: Golden Dragon, Jade Palace"},
    {"role": "assistant", "content": "I found Golden Dragon and Jade Palace.", "tool_calls": None}
]

# Convert to Ragas messages
ragas_messages = convert_to_ragas_messages(swarm_messages)

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

Comparison with LangGraph Converter

Feature	Swarm Converter	LangGraph Converter
Input format	Plain dictionaries with role field	LangChain message class instances
System messages	Raises ValueError	Silently skipped
Metadata support	Not supported	Optional via metadata=True parameter
Tool call source	message["tool_calls"] dictionary field	message.additional_kwargs["tool_calls"] attribute
Content validation	Implicit (dictionary access)	Explicit isinstance(content, str) check

Internal Dependencies

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

Implements

• Swarm Message Conversion -- the principle of converting Swarm dictionary messages to Ragas standard types

See Also

• Principle:Explodinggradients_Ragas_Swarm_Message_Conversion
• LangGraph Convert Messages -- similar conversion for LangChain/LangGraph messages
• MultiTurnSample Class -- the data schema that consumes the converted messages