Principle:Explodinggradients Ragas Swarm Message Conversion

Swarm Message Conversion

Swarm Message Conversion is the principle of converting OpenAI Swarm framework message dictionaries into Ragas standard message types. Swarm uses plain Python dictionaries with role-based dispatching to represent conversations, and this conversion maps those dictionary fields to typed Ragas message classes while preserving tool call structures.

Theoretical Foundation

Swarm's Dictionary-Based Message Format

The OpenAI Swarm framework represents messages as plain Python dictionaries with a role field that determines the message type. Unlike LangChain, which uses class hierarchies with distinct types for each role, Swarm relies on a uniform dictionary structure where the role string ("user", "assistant", "tool") dictates interpretation.

A typical Swarm conversation consists of:

• User messages: {"role": "user", "content": "..."}
• Assistant messages: {"role": "assistant", "content": "...", "tool_calls": [...]}
• Tool messages: {"role": "tool", "content": "..."}

Role-Based Dispatching

The conversion relies on the role field to dispatch each dictionary to the appropriate Ragas message constructor:

• "user" maps to HumanMessage
• "assistant" maps to AIMessage
• "tool" maps to ToolMessage

This dispatching pattern is simpler than class-based conversion (as used for LangChain) because all messages share the same dictionary structure, differing only in which fields are present and what value the role field holds.

Tool Call Structure Preservation

Swarm encodes tool calls in the same format as the OpenAI Chat Completions API:

{
    "role": "assistant",
    "content": null,
    "tool_calls": [
        {
            "function": {
                "name": "search_restaurants",
                "arguments": "{\"cuisine\": \"Chinese\"}"
            }
        }
    ]
}

The conversion must:

1. Extract the tool_calls list from the assistant message
2. For each tool call, extract the function name from function.name
3. Parse the JSON-encoded arguments string from function.arguments into a Python dictionary
4. Construct ToolCall objects with the extracted name and parsed arguments

Strict Role Validation

Unlike the LangGraph converter, which silently skips system messages, the Swarm converter enforces strict role validation. Only the three recognized roles ("user", "assistant", "tool") are accepted. Messages with any other role, including missing roles, raise errors. This strictness ensures that conversion failures are detected immediately rather than producing silently incorrect evaluation data.

Relationship to Other Concepts

Swarm message conversion is a specific implementation of the broader Framework Message Conversion concept. While the general principle applies to any LLM framework, this variant addresses the particular dictionary-based format used by OpenAI Swarm.

The converted messages feed into Multi-Turn Evaluation Schema samples for evaluation by metrics such as tool call accuracy, F1, and goal accuracy.

Implemented By

• Swarm Convert Messages -- the Ragas integration module that implements this conversion

See Also

• Implementation:Explodinggradients_Ragas_Swarm_Convert_Messages
• Framework Message Conversion -- the general principle of framework-agnostic message conversion
• Multi-Turn Evaluation Schema -- the schema that uses the converted messages
• Tool Call Accuracy Evaluation -- a metric that evaluates tool calls from converted messages