README.md

metadata

title: agent-trace — FORGE Telemetry
emoji: 📊
colorFrom: blue
colorTo: red
sdk: docker
pinned: true
license: mit
short_description: Telemetry backbone for the FORGE AI agent ecosystem

📊 agent-trace

FORGE Telemetry Backbone

Every agent in the FORGE ecosystem sends events here. Owns: ingest, retention, aggregation, real-time dashboard.

What it stores

Every agent action produces a trace event:

{
  "agent":      "nexus",
  "event_type": "llm_call",
  "session_id": "abc123",
  "task_id":    "task-xyz",
  "status":     "ok",
  "latency_ms": 1240,
  "tokens_in":  512,
  "tokens_out": 128,
  "model":      "qwen/qwen3.5-35b-a3b",
  "reward":     null,
  "payload":    {}
}

Event types

llm_call · tool_use · react_step · skill_load · kanban_move · slot_event · self_reflect · reward_signal · error · custom

REST API

POST /api/trace            Ingest single event
POST /api/traces/batch     Ingest array of events
GET  /api/traces           Query with filters
GET  /api/stats            Aggregated stats (window_hours param)
GET  /api/agents           List active agents
GET  /api/session/{id}     Full session timeline
PATCH /api/trace/{id}/reward  Assign reward (called by agent-learn)
DELETE /api/purge          Purge old traces

MCP

GET  /mcp/sse   SSE transport
POST /mcp       JSON-RPC 2.0

Tools: trace_ingest, trace_query, trace_stats, trace_agents, trace_session, trace_reward

Secrets

Key	Description
TRACE_KEY	Optional write auth key (X-Trace-Key header)
RETAIN_DAYS	Retention period in days (default: 7)

Integration

Every FORGE space sends traces here. Add to any agent:

import requests

TRACE_URL = "https://chris4k-agent-trace.hf.space"

def trace(agent, event_type, **kwargs):
    requests.post(f"{TRACE_URL}/api/trace", json={
        "agent": agent,
        "event_type": event_type,
        **kwargs
    }, timeout=3)

Built by Chris4K — ki-fusion-labs.de