Skip to main content

​
Agent Telemetry Protocol

Technical specification for the Arden telemetry event format.

​
Protocol Overview

Arden uses a minimal, language-agnostic JSON protocol for logging AI agent telemetry events. It follows syslog semantics with no server-side deduplication.

​
Event Schema

​
Required Fields

FieldTypeFormatDescription
agentstring^(?:[aAsS]-)?[0-9a-fA-F]{1,8}$Agent identifier (case-insensitive hex)
bidintegerMicro-centsUsage cost (6 decimal places implicit)
timeintegerEpoch milliseconds UTCEvent timestamp
dataobject/string≤1KBMetadata payload or base64 string

​
Optional Fields

FieldTypeFormatDescription
userstringULID (26 chars)User identifier (auto-filled from token)
multinteger-Reserved multiplier for future pricing

​
Server-Generated Fields

FieldTypeDescription
event_idstringUUID-7 assigned by server

​
Agent ID Format

Agent IDs support optional prefixes:
  • A- or a- = Real agent
  • S- or s- = Simulated agent
  • No prefix = Bare hex string accepted
Examples:
  • A-1234abcd (real agent)
  • s-5678ef90 (simulated agent)
  • deadbeef (bare hex)

​
Data Payload

The data field accepts two formats: 
{
  "data": {
    "task": "code_review",
    "duration": 1500,
    "tokens": 2048
  }
}
Constraints:
  • Flat key-value pairs only
  • Total JSON size ≤ 1KB
  • Values must be strings or integers

​
2. Base64 Format

{
  "data": "SGVsbG8gV29ybGQ="
}
Constraints:
  • 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

Send up to 100 events in a single request: 
[
  {
    "agent": "A-1234abcd",
    "bid": 1000,
    "time": 1642781234567,
    "data": {"task": "review"}
  },
  {
    "agent": "A-1234abcd", 
    "bid": 1500,
    "time": 1642781234890,
    "data": {"task": "debug"}
  }
]
Batch Rules:
  • 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

Always use current timestamp when sending events: 
// JavaScript
const timestamp = Date.now();

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

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

​
Error Handling

Always check response status and handle errors: 
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

The protocol intentionally does not perform deduplication. Each event is treated as unique, even if identical to previous events.

​
Testing

Use the CLI to validate event format: 
# 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

If migrating from other telemetry systems, ensure:
  • 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