​

Agent Telemetry Protocol

​

Protocol Overview

​

Event Schema

​

Required Fields

​

Optional Fields

​

Server-Generated Fields

​

Agent ID Format

• A- or a- = Real agent
• S- or s- = Simulated agent
• No prefix = Bare hex string accepted

• A-1234abcd (real agent)
• s-5678ef90 (simulated agent)
• deadbeef (bare hex)

​

Data Payload

​

1. Object Format (Recommended)

{
  "data": {
    "task": "code_review",
    "duration": 1500,
    "tokens": 2048
  }
}

• Flat key-value pairs only
• Total JSON size ≤ 1KB
• Values must be strings or integers

​

2. Base64 Format

{
  "data": "SGVsbG8gV29ybGQ="
}

• Base64-encoded string
• Decoded size ≤ 1KB
• For arbitrary binary data

​

Complete Event Example

{
  "agent": "A-1234abcd",
  "user": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "time": 1642781234567,
  "bid": 1000,
  "mult": 1,
  "data": {
    "task": "code_review",
    "duration": 1500,
    "language": "python",
    "lines_changed": 42
  }
}

​

Validation Rules

​

Agent Validation

• Must exist in the system database
• Case-insensitive matching
• Hex characters only (0-9, A-F, a-f)
• Length: 1-8 characters (excluding prefix)

​

User Validation

• Must be valid ULID format (26 characters)
• Auto-filled from Bearer token if missing
• Required if no valid token provided

​

Time Validation

• Must be valid epoch milliseconds
• UTC timezone assumed
• Future timestamps accepted

​

Bid Validation

• Non-negative integer
• Represents micro-cents (1000 = $0.01)
• Default: 0 if not specified

​

Data Validation

• Total size limit: 1KB
• Object format: flat key-value pairs only
• String format: valid base64 encoding

​

Error Responses

​

Validation Errors

{
  "status": "rejected",
  "accepted_count": 0,
  "rejected_count": 1,
  "rejected": [
    {"index": 0, "error": "unknown_agent"}
  ]
}

​

Common Error Codes

• unknown_agent - Agent not registered
• invalid_user - User ULID invalid/missing
• missing_required_field - Required field absent
• bad_data_size - Data exceeds 1KB limit
• validation_error - Schema validation failed

​

Batch Processing

[
  {
    "agent": "A-1234abcd",
    "bid": 1000,
    "time": 1642781234567,
    "data": {"task": "review"}
  },
  {
    "agent": "A-1234abcd", 
    "bid": 1500,
    "time": 1642781234890,
    "data": {"task": "debug"}
  }
]

• Maximum 100 events per request
• Each event validated independently
• Partial success returns 207 status
• Event IDs returned in order (accepted events only)

​

Security Requirements

• Transport: HTTPS required (TLS 1.3)
• Authentication: Optional Bearer token
• Validation: Server-side schema validation
• Rate limiting: Applied per IP/token

​

Protocol Versioning

• Current version: v1
• Endpoint: /api/events
• Breaking changes will increment version
• Backward compatibility maintained when possible

​

Implementation Notes

​

Timestamps

// JavaScript
const timestamp = Date.now();

// Python
import time
timestamp = int(time.time() * 1000)

// Go
timestamp := time.Now().UnixMilli()

​

Error Handling

const response = await fetch('/api/events', {
  method: 'POST',
  body: JSON.stringify(event)
});

if (!response.ok) {
  const error = await response.json();
  console.error('Event submission failed:', error);
}

​

Deduplication

​

Testing

# Validate single event
arden events send --agent "test" --bid 1000 --dry-run --print

# Validate batch events
arden events send --file events.json --dry-run --print

​

Migration from Legacy Formats

• Agent IDs match the hex format requirement
• Timestamps are in epoch milliseconds
• Data payloads are flattened to key-value pairs
• File sizes are under 1KB per event