Chris4K/agent-trace

1---2title: agent-trace — FORGE Telemetry3emoji: 📊4colorFrom: blue5colorTo: red6sdk: docker7pinned: true8license: mit9short_description: Telemetry backbone for the FORGE AI agent ecosystem10---11 12# 📊 agent-trace13### FORGE Telemetry Backbone14 15Every agent in the FORGE ecosystem sends events here.16Owns: ingest, retention, aggregation, real-time dashboard.17 18## What it stores19 20Every agent action produces a **trace event**:21 22```json23{24  "agent":      "nexus",25  "event_type": "llm_call",26  "session_id": "abc123",27  "task_id":    "task-xyz",28  "status":     "ok",29  "latency_ms": 1240,30  "tokens_in":  512,31  "tokens_out": 128,32  "model":      "qwen/qwen3.5-35b-a3b",33  "reward":     null,34  "payload":    {}35}36```37 38## Event types39 40`llm_call` · `tool_use` · `react_step` · `skill_load` · `kanban_move` · `slot_event` · `self_reflect` · `reward_signal` · `error` · `custom`41 42## REST API43 44```45POST /api/trace            Ingest single event46POST /api/traces/batch     Ingest array of events47GET  /api/traces           Query with filters48GET  /api/stats            Aggregated stats (window_hours param)49GET  /api/agents           List active agents50GET  /api/session/{id}     Full session timeline51PATCH /api/trace/{id}/reward  Assign reward (called by agent-learn)52DELETE /api/purge          Purge old traces53```54 55## MCP56 57```58GET  /mcp/sse   SSE transport59POST /mcp       JSON-RPC 2.060 61Tools: trace_ingest, trace_query, trace_stats, trace_agents, trace_session, trace_reward62```63 64## Secrets65 66| Key | Description |67|-----|-------------|68| `TRACE_KEY` | Optional write auth key (X-Trace-Key header) |69| `RETAIN_DAYS` | Retention period in days (default: 7) |70 71## Integration72 73Every FORGE space sends traces here. Add to any agent:74 75```python76import requests77 78TRACE_URL = "https://chris4k-agent-trace.hf.space"79 80def trace(agent, event_type, **kwargs):81    requests.post(f"{TRACE_URL}/api/trace", json={82        "agent": agent,83        "event_type": event_type,84        **kwargs85    }, timeout=3)86```87 88Built by [Chris4K](https://huggingface.co/Chris4K) — ki-fusion-labs.de89