Agent Trace Ingestion

Feed your agent's execution traces into Cerebe and get structured memories, plan coherence analysis, and tool reliability tracking back. Your agents learn from every run.

What Happens When You Ingest a Trace

Step memories — Each execution step is stored as an execution_history memory with importance scoring (failures score higher)
Plan coherence — If a plan was provided, Cerebe computes an LCS-based coherence score between planned and actual steps
Tool reliability — Per-tool success rates, latencies, and failure reasons are tracked in the agent's cognitive profile
PEOA observation — The trace triggers a Plan-Execute-Observe-Adapt cycle that updates the agent's strategy preferences

Ingest a Trace

result = await client.traces.ingest(
    trace_id="trace_001",
    task_id="research_task",
    agent_id="agent_alpha",
    steps=[
        {
            "step_id": "s1",
            "node_name": "plan",
            "outcome": "success",
            "duration_ms": 120,
            "timestamp": "2025-01-15T10:00:00Z",
        },
        {
            "step_id": "s2",
            "node_name": "search",
            "tool_name": "web_search",
            "outcome": "success",
            "duration_ms": 850,
            "timestamp": "2025-01-15T10:00:01Z",
        },
        {
            "step_id": "s3",
            "node_name": "synthesize",
            "outcome": "success",
            "duration_ms": 200,
            "timestamp": "2025-01-15T10:00:02Z",
        },
    ],
    plan={
        "goal": "Research competitive landscape",
        "expected_steps": ["plan", "search", "synthesize"],
    },
    outcome={
        "success": True,
        "steps_taken": 3,
        "total_duration_ms": 1170,
        "result_summary": "Competitive analysis complete",
    },
)

print(result.memories_created)          # 4
print(result.plan_coherence)            # 1.0 (perfect adherence)
print(result.tool_reliability_updated)  # True

const result = await client.traces.ingest({
  traceId: 'trace_001',
  taskId: 'research_task',
  agentId: 'agent_alpha',
  steps: [
    { stepId: 's1', nodeName: 'plan', outcome: 'success', durationMs: 120, timestamp: '2025-01-15T10:00:00Z' },
    { stepId: 's2', nodeName: 'search', toolName: 'web_search', outcome: 'success', durationMs: 850, timestamp: '2025-01-15T10:00:01Z' },
    { stepId: 's3', nodeName: 'synthesize', outcome: 'success', durationMs: 200, timestamp: '2025-01-15T10:00:02Z' },
  ],
  plan: { goal: 'Research competitive landscape', expectedSteps: ['plan', 'search', 'synthesize'] },
  outcome: { success: true, stepsTaken: 3, totalDurationMs: 1170, resultSummary: 'Competitive analysis complete' },
})

console.log(result.memoriesCreated)         // 4
console.log(result.planCoherence)            // 1.0
console.log(result.toolReliabilityUpdated)   // true

curl -X POST https://api.cerebe.ai/api/v1/traces/ingest \
  -H "X-API-Key: ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "trace_id": "trace_001",
    "task_id": "research_task",
    "agent_id": "agent_alpha",
    "steps": [
      {"step_id": "s1", "node_name": "plan", "outcome": "success", "duration_ms": 120, "timestamp": "2025-01-15T10:00:00Z"}
    ],
    "outcome": {"success": true, "steps_taken": 3, "total_duration_ms": 1170}
  }'

Plan Coherence Scoring

When you provide a plan with expected_steps, Cerebe computes a coherence score:

1.0 — Agent followed the plan exactly
0.5 — Significant divergence from plan
0.0 — Complete deviation

The score uses Longest Common Subsequence (LCS) ratio, so reordered steps still get partial credit.

Tool Reliability Tracking

Every tool invocation in a trace updates the agent's cognitive profile with:

Success rate — EWMA-smoothed success rate per tool
Average latency — Smoothed latency tracking
Last failure reason — Most recent error for debugging
Call count — Total invocations

Importance Scoring

Steps are automatically scored for memory importance:

Outcome	Base Score
`failure`	0.8
`timeout`	0.7
`success`	0.5
+ tool invocation	+0.1

Failures are scored higher because they're more valuable for learning.

API Reference

Method	Endpoint	Description
`POST`	`/api/v1/traces/ingest`	Ingest an execution trace

Next Steps

Cognitive Profiles — See how traces build agent profiles
Meta-Learning — PLRE/PEOA frameworks
Memory Fabric — Where trace memories are stored

Agent Traces