README.md

---
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**:

```json
{
  "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:

```python
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](https://huggingface.co/Chris4K) — ki-fusion-labs.de