Overview

Understanding the TurnWise data format

Data Format Overview

TurnWise uses a hierarchical JSON format to represent AI agent conversations. This format captures the full context of conversations including messages, tool usage, and agent reasoning.

Structure

Dataset (top level)
├── conversations[] (required)
│   ├── name (optional)
│   ├── description (optional)
│   ├── agents[] (optional)
│   │   ├── name
│   │   ├── description
│   │   └── tools{}
│   └── messages[] (required)
│       ├── role (required)
│       ├── content (optional)
│       └── steps[] (optional)
│           ├── model_name
│           ├── thinking
│           ├── tool_call
│           ├── tool_result
│           └── output_content

Minimal Example

The simplest valid TurnWise file:

{
  "conversations": [
    {
      "messages": [
        {
          "role": "user",
          "content": "Hello"
        },
        {
          "role": "assistant",
          "content": "Hi there!"
        }
      ]
    }
  ]
}

Note: Message order (sequence_number) and step order (step_order) are automatically inferred from array positions.

Required vs Optional Fields

Required Fields

Field	Level	Description
conversations	Root	Array of conversation objects
messages	Conversation	Array of message objects
role	Message	One of: user, assistant, system, tool

Optional Fields

Field	Level	Description
name	Conversation	Human-readable name
description	Conversation	Description text
agents	Conversation	Agent definitions
content	Message	Message text content
steps	Message	Processing steps
thinking	Step	Model’s reasoning
tool_call	Step	Tool invocation
tool_result	Step	Tool output
output_content	Step	Final output
meta	All levels	Custom metadata

The meta Field

Every level supports an optional meta field for storing custom data:

{
  "conversations": [
    {
      "name": "Support Chat",
      "meta": {
        "customer_id": "cust_123",
        "session_id": "sess_456",
        "channel": "web"
      },
      "messages": [...]
    }
  ]
}

This data is preserved but not used by TurnWise evaluations unless referenced in custom metrics.

Next Steps

Conversations

Learn about conversation structure

Messages

Understand message roles and content

Steps

Capture reasoning and tool usage

Agents

Define agent capabilities