# Agent Chat Messages Protocol

> **NOTE**: This document is the single source of truth. All implementations must follow this specification.

## Overview

Chat messages in agent conversations with metadata for tracking and telemetry.

## Version

- **Current**: `1.0`
- **Status**: Active

---

## Message Metadata

```typescript
interface AgentChatMessageMetadata {
  run_id?: string;       // Unique run identifier
  stage?: string;       // Processing stage (e.g., "intent", "execution")
  latency_ms?: number;  // Processing latency in milliseconds
  message_id?: string;  // Message identifier
  [key: string]: any;   // Additional custom fields allowed
}
```

---

## Database Field

| Field | Type | Description |
|-------|------|-------------|
| metadata | jsonb | Message metadata including run_id, stage, latency_ms, message_id |

---

## JSON Examples

### Basic Message Metadata

```json
{
  "run_id": "run_1773286460762"
}
```

### Stage Completion Metadata

```json
{
  "run_id": "run_1773286460762",
  "stage": "intent",
  "latency_ms": 2610,
  "message_id": "intent-run_1773286460762"
}
```

### Tool Execution Metadata

```json
{
  "run_id": "run_1773287162123",
  "stage": "tool_execution",
  "latency_ms": 1500,
  "message_id": "tool_run_abc123",
  "tool_name": "calendar_create_event"
}
```