Skip to main content

​
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:
RoleDescription
userMessage from the human user
assistantMessage from the AI agent
systemSystem instructions or context
toolOutput 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.