Messages

Understanding message structure and roles

Messages

Messages represent individual turns in a conversation. Each message has a role and content. The order is automatically inferred from the message’s position in the array.

Structure

{
  "role": "assistant",
  "content": "How can I help you today?",
  "steps": [...],
  "meta": {...}
}

Required Fields

role

The role of the message sender. Must be one of:

Role	Description
user	Message from the human user
assistant	Message from the AI agent
system	System instructions or context
tool	Output from a tool execution

content

The text content of the message. This field is required.

"content": "I'd like to return my order"

Optional Fields

steps

Array of processing steps. See Steps for details. Typically used for assistant messages to capture reasoning and tool usage.

meta

Custom metadata for the message.

"meta": {
  "timestamp": "2024-01-20T14:30:00Z",
  "latency_ms": 150
}

Role Examples

User Messages

{
  "role": "user",
  "content": "I need to cancel my subscription"
}

Assistant Messages

{
  "role": "assistant",
  "content": "I can help you cancel. Can you confirm your account email?",
  "steps": [
    {
      "thinking": "User wants to cancel. Need account info first.",
      "output_content": "I can help you cancel. Can you confirm your account email?"
    }
  ]
}

System Messages

{
  "role": "system",
  "content": "You are a helpful customer service agent for Acme Corp."
}

Tool Messages

{
  "role": "tool",
  "content": "{\"order_id\": \"ORD-123\", \"status\": \"shipped\"}",
  "meta": {
    "tool_name": "lookup_order"
  }
}

Best Practices

Message order is automatic: The order of messages is automatically inferred from their position in the array. Keep messages in chronological order.

Use steps for assistant messages: Capturing the reasoning process enables more detailed evaluation of agent behavior.

Store raw content: Keep the original message content even if you also use steps, for easier human review.