Agents from scratch (TypeScript) · Chapter 12 of 18

Tracing

By the end of this chapter you can record what an agent did, step by step, in a file anyone can read later: a span per request and per tool call, a trace id per run, a summary of a run in five lines, and a replay of a run's decisions without the model. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: Agents that hold up
  • 4 tasks
  • TypeScript
  • In the all labs plan

The first 2 chapters of Agents from scratch (TypeScript) are free. This one comes with the all labs plan.

Why you need this

A customer writes to Meenakshi at 6 pm: "your bot said it booked an electrician, nobody came." What happened at 11:04 that morning? The conversation is gone, the model will not remember, and running the request again today gives today's answer, from today's slots. lab steps showed you runs in the lab, but GharFix's server answers thousands of customers, and nobody is watching a terminal.

Agents fail in ways ordinary programs do not. A step can be "fine" (no exception, status 200) and still be the step where the run went wrong: a lookup that came back empty, a result missing a key the next tool needed, a model that answered instead of booking. To find that step afterwards, the run must have written down, as it went, what it sent, what came back, what it cost and how long it took. Vikram calls that a trace, and Farooq likes it for another reason: it is where the tokens are.

What you build: 4 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    tracer.ts: a span per line

    In tracer.ts, export a class Tracer, made with new Tracer(path). A new Tracer has a traceId, a new random id as text, so that every run has its own. record(kind, fields) adds one span to the file at path, as one line of JSON: an object with traceId, span (the span's number in this trace, from 1), kind, and then every field given; it returns that object. Spans are added to the end of the file, so one file holds many traces.

    Then export readTrace(path, traceId?): the spans in the file, in order, as objects; given a traceId, only that trace's.

  2. Task 2

    traced-run.ts: trace a booking

    In traced-run.ts, export async runTraced(question, tracer): chapter 3's loop with lab-chat, a system message saying today is 2026-10-22, the question, and GharFix's TOOLS, at most 10 requests, returning the final answer's text. Record, with the tracer it is given:

    after every request, a span of kind model with step (the request's number, from 1), model (the response's model), promptTokens, completionTokens, ms (how long the request took, in milliseconds), finishReason and tools (the names of the tools asked for, an array);

    after every call, a span of kind tool with step (the request that asked for it), tool, arguments (the JSON text the model wrote), resultChars (the length of the result's JSON text sent back), error (the result's error text, or null) and ms.

    The check runs a booking and a reschedule GharFix refuses, and compares the spans with what the model received.

  3. Task 3

    summary.ts: a trace in five lines

    In summary.ts, export summarize(path, traceId). It reads one trace (use readTrace from ./tracer.ts) and returns an array of lines:

    trace <id>: <n> model calls, <n> tool calls

    tokens: <total prompt> prompt, <total completion> completion

    time: <the ms of every span added up, rounded to a whole number> ms

    tools: <the tools called, in order, with a comma and a space between them, or none>

    and then one line per tool span with an error, error at step <step>, <tool>: <error>, or, when there are none, errors: none.

    The check writes a file with two traces in it and summarizes each.

  4. Task 4 · interview question

    Interview: fix-from-trace.ts, find the failing step

    Farooq asked for smaller tool results, so the team wrapped findTechnicians to keep only what the agent needs. Since then, bookings end without a booking, and no result is ever an error. fix-from-trace.ts runs a booking and writes its trace to fix-from-trace.jsonl.

    Read the trace, find the step where the run went wrong, and fix the tool so that the run books: for the booking in the file, and for one that names no slot. Keep the trim: findTechnicians's rows still leave jobs_done out.

    Keep run(question), findTechnicians and FUNCTIONS, exported. The check calls your findTechnicians and runs both bookings.

What you will learn

  • Spans: one record per model request and per tool call.
  • A trace: a run's spans, tied together by a trace id, one JSON line each.
  • Reading a trace: a summary, and finding the step that went wrong.
  • Replaying a run from its trace, without the model.

More in Agents that hold up

Build "Tracing" yourself

GharFix, a Bengaluru home-services company, needs an assistant that books, reschedules and refunds safely. You build it in TypeScript. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of Agents from scratch (TypeScript) are free. This one comes with the all labs plan.