Custom Integration

Integrate any agent or application with Arden telemetry tracking.

Overview

Send telemetry events from your custom agents using either the CLI or direct API calls. Perfect for tracking usage of your own AI agents, tools, or applications.

Using the CLI

The simplest way to send events from any application:
arden events send --agent "my-agent" --bid 1000

Basic Event

arden events send --agent "my-agent" --bid 1000 --data '{"task": "code_review"}'

Batch Events

Create a JSON file with multiple events:
[
  {
    "agent": "my-agent",
    "bid": 1000,
    "data": {"task": "code_review"}
  },
  {
    "agent": "my-agent", 
    "bid": 1500,
    "data": {"task": "bug_fix"}
  }
]
Send the batch:
arden events send --file events.json

Using the API

For direct integration without the CLI:
curl -X POST https://api.ardenstats.com/api/events \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-agent",
    "bid": 1000,
    "time": 1642781234567,
    "data": {"task": "code_review"}
  }'

Language Examples

Python

import requests
import time

def send_telemetry(agent_id, bid, data=None):
    event = {
        "agent": agent_id,
        "bid": bid,
        "time": int(time.time() * 1000),
        "data": data or {}
    }
    
    response = requests.post(
        "https://api.ardenstats.com/api/events",
        json=event,
        headers={"Content-Type": "application/json"}
    )
    
    return response.json()

# Usage
send_telemetry("my-python-agent", 1000, {"task": "data_analysis"})

JavaScript/Node.js

async function sendTelemetry(agentId, bid, data = {}) {
  const event = {
    agent: agentId,
    bid: bid,
    time: Date.now(),
    data: data
  };

  const response = await fetch('https://api.ardenstats.com/api/events', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(event)
  });

  return response.json();
}

// Usage
sendTelemetry('my-js-agent', 1000, { task: 'code_generation' });

Go

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
    "time"
)

type Event struct {
    Agent string                 `json:"agent"`
    Bid   int                    `json:"bid"`
    Time  int64                  `json:"time"`
    Data  map[string]interface{} `json:"data"`
}

func sendTelemetry(agentId string, bid int, data map[string]interface{}) error {
    event := Event{
        Agent: agentId,
        Bid:   bid,
        Time:  time.Now().UnixMilli(),
        Data:  data,
    }

    jsonData, _ := json.Marshal(event)
    
    resp, err := http.Post(
        "https://api.ardenstats.com/api/events",
        "application/json",
        bytes.NewBuffer(jsonData),
    )
    
    return err
}

Best Practices

Agent Naming

  • Use descriptive agent IDs: "my-company.code-reviewer"
  • Keep it consistent across sessions
  • Avoid special characters (use hyphens or dots)

Bid Values

  • Use micro-cents (1000 = $0.01)
  • Track actual usage costs when possible
  • Be consistent with your pricing model

Data Payload

  • Keep under 1KB total size
  • Include relevant context: task type, duration, etc.
  • Use flat key-value pairs for better analytics

Error Handling

  • Always check response status
  • Retry on network failures
  • Log errors for debugging

Common Integration Patterns

Wrapper Function

Create a utility function for your application:
#!/bin/bash
# my-agent-wrapper.sh
MY_AGENT_ID="my-company.custom-agent"

# Run your agent
python my_agent.py "$@"

# Send telemetry after completion
arden events send --agent "$MY_AGENT_ID" --bid 1000 --data "{\"args\": \"$*\"}"

Process Monitoring

Track long-running processes:
# Start event
arden events send --agent "long-runner" --bid 0 --data '{"status": "started"}'

# Your long process
./my-long-process.sh

# End event
arden events send --agent "long-runner" --bid 2000 --data '{"status": "completed"}'

Testing Your Integration

Use dry-run mode to test without sending real events:
arden events send --agent "test-agent" --bid 1000 --dry-run
View the leaderboard to confirm your events are being tracked:
arden agents leaderboard

Troubleshooting

Events not appearing?
  • Check agent ID format (alphanumeric with optional prefix)
  • Verify network connectivity
  • Use --dry-run --print to debug payload
Rate limiting?
  • Batch events when possible (max 100 per request)
  • Add delays between requests
  • Use exponential backoff for retries
Authentication issues?
  • Set ARDEN_API_TOKEN environment variable
  • Check token validity
  • Verify API endpoint URL