Docs

First Trace

Understand how traces are captured in Agent Lab and via the ingestion API.

A trace is a stored record of one AI execution: prompt, response, model, tokens, latency, and metadata.

Agent Lab path (local)

The fastest way to create a trace:

Run agent — POST /api/local/run with recordTrace: true
Agent chat — each turn uses the same endpoint with a messages array
Coach — creates coach_local_draft and optional coach_curated traces

Traces from local runs use parameters.source: agent_lab or coach and estimatedCostUsd: 0.

Example (dashboard)

Run agent → enter prompt → Run & trace → open the trace link.

Example (API)

curl -X POST http://localhost:3000/api/local/run \
  -H "Content-Type: application/json" \
  -H "Cookie: <session>" \
  -d '{
    "prompt": "Hello",
    "model": "llama3.2",
    "actionName": "my_first_trace",
    "recordTrace": true
  }'

Response includes traceId when ingestion succeeds.

Production path (SDK / API)

For apps calling cloud models, ingest traces after each completion:

from aitracer import AITracer
 
client = AITracer(api_key="your-api-key")
 
trace = client.trace(
    model="gpt-4o",
    input="Summarize this quarterly report",
    metadata={"workflow": "finance-review"},
)

Or POST /api/traces with a Trace Ingestion API payload.

What to inspect

In Dashboard → Traces, each record includes:

Field	Description
`actionName`	Groups runs for training export
`model`	Model ID used
`prompt` / `response`	Training pair when both present
`parameters`	e.g. `trainingPreferred`, `coachSessionId`
`estimatedCostUsd`	$0 for Ollama; provider cost when applicable

Trace → training

Completed traces with prompt + response become trainable examples.

Export via Training data
Mark curated picks in Coach (trainingPreferred: true)

Advanced: governance & verification

Production deployments can attach policy results and integrity verification to traces. See:

These are optional layers on top of basic trace capture.

Terminal agent Installation