Designing Observable Agent Systems
Telemetry is part of what a system is for, so it belongs from the first commit rather than being added after production.
A Question Asked Months Later
Imagine a team builds an assistant that recommends refunds to customers. The core feature works, the assistant ships, and real users begin arriving. Nobody has yet written anything that records what the assistant does, because the early code is small and the team believes they will remember what happened. Months later, someone asks a narrow question: why did the system make that recommendation on a particular date? This lesson is about why the answer to that question depends entirely on decisions made at the very beginning of the project.
What do you think happens?
The team added no recording of model calls or tool invocations until after launch. Six months later, someone asks why the assistant recommended a refund on a specific date. What can the team reliably answer?
Reveal answer
The team can answer only from records that were written at the time, so with none, the question is largely unanswerable
The source material notes that investigations often happen months later, after models and prompts have changed, so only records written at the time can answer them. Rerunning today's model does not reproduce what the system did then, and the original people may have moved on.
Telemetry as Part of the Design
Many teams treat monitoring and event recording as a finishing task. The core product is built first, the system is shipped, and only once real users arrive does someone ask how to see what it is doing. The source material argues that this ordering is a mistake, and that the mistake becomes expensive exactly when the system matters most.
Telemetry is the record a system produces of the work it does. In this lesson's framing, telemetry is part of what a system is for, so it belongs from the first commit rather than being added after production.
A useful way to see why telemetry belongs in the design is to ask what it is for. A system exists to do work, and the record of that work is how its owners later understand, defend, and improve it. If the record is absent, the system is effectively unaccountable for what it did. Telemetry therefore belongs in the design alongside the features, not in a maintenance backlog that begins after launch.
Events the First Slice Should Record
The source gives a concrete starting point. The first slice of the system, meaning the first working piece built in the course of the project, should already be writing structured logs. Those logs should capture six kinds of events. The point is not that any single event is individually dramatic. The point is that together they make the system's behavior visible from the beginning.
- Model calls: each request the system sends to a model, so later readers can tell which model version was asked what
- Tool invocations: each time the agent uses an external tool, so the actions it took can be traced
- Customer inputs: each thing the customer types, which is the starting point of any investigation
- Outputs: each response the system returns, which is what the customer actually received
- Human interventions: each place a person stepped in, since a human decision can change the outcome
- Escalations: each place the agent handed the case onward, which marks where autonomous behavior ended
Each kind answers a question a later investigator is likely to ask. Customer inputs and outputs establish what happened at the boundary. Model calls and tool invocations explain what the system did internally. Human interventions and escalations show where responsibility moved between the system and people. Leaving out any one kind creates a blind spot in exactly the place a later reader may need to look.
Tracing One Interaction as Ordered Events
A single record is useful, but the real value comes from how records accumulate. Each interaction produces several events, and those events are written in order as the system works. Later, an investigator reads them as a sequence and rebuilds the path from the customer's input to the final output. The diagram below traces one interaction through the components that produce events and the store where those events are kept.
Read the arrows in the order of their numbers. Each step produces a record, and the record is written before the next step is later rebuilt from the log. If a step never produced a record, the later reader has a gap with no way to fill it. The investigation depends entirely on what the records captured while the work was happening.
Rebuilding a Refund Decision
Reconstructing a refund recommendation from its records
An investigator must explain why the refund assistant recommended a refund to a customer on a given date. Only the recorded events are available. Work out what the investigator can rebuild, step by step.
- 1Find the customer's input
The investigator searches for the recorded customer input for that date. This is the starting point of the path, because it shows what the customer actually asked.
- 2Check which model answered
The model call record names the model version that was used. This matters because the model may have been swapped out since, so the current model cannot stand in for the one that ran that day.
- 3Follow any tool invocations
Tool invocation records show what the agent looked up or did before deciding. If a tool result shaped the recommendation, its record is part of the explanation.
- 4Check for human or escalation events
Human intervention and escalation records show whether a person changed the outcome or the case was handed onward. These records mark where responsibility moved.
- 5Compare with the recorded output
The output record confirms what was returned to the customer. The investigator now has the full ordered path from input to output.
The investigator can rebuild the path because each event was written at the time. If the model call record were missing, the investigator could not say which model made the recommendation, and the explanation would have a gap at its center.
Why Structured Records Beat Free Text
The logs must be useful later, not just readable at the moment they are written. The source asks that logs include enough context to reconstruct the trace afterward, and that they be shaped so they can be analyzed. A line of plain text that says the assistant recommended a refund is easy for a person to skim, but hard for a program to filter by date, by model version, or by customer.
Named fields make the questions answerable. When each piece of context sits in its own field, a query can select by date, by model version, or by customer without parsing sentences. The format itself is a practical decision. JSON is the example the source gives, and the phrase about whatever the customer's observability stack accepts signals that the format should fit the surrounding tools. What stays constant is the requirement that the record be structured and rich enough to rebuild what happened.
Anatomy of a Structured Event
The following illustrative record shows what one structured event could look like. The field names here are invented for this lesson to show the idea. The source does not prescribe them. Each field answers a question a later investigator might ask.
event_typesays what kind of event this is, so events can be filtered by kind- timestamp places the event in time, so events can be ordered and queried by date
interaction_idties this event to the other events from the same interactioncustomer_idlets an investigator select every event belonging to one customermodel_versionandprompt_versionrecord which model and prompt were in effect, since both may change over timeinput_summaryandoutput_summarykeep the content of the exchange in fields a program can read
Notice that the record does not depend on a person remembering anything. Every field that an investigator would later need is written at the moment the event happens. The interaction identifier is especially important, because it lets the separate events from one interaction be gathered and read together in order.
Mistakes Beginners Make with Telemetry
Common mistake Adding event recording after the first real users arrive
Why it failsInvestigations often happen months later, and by then the early behavior cannot be recovered from records that were never written.
Do this insteadWrite the first slice's events from the start, as part of the feature work.
Common mistake Logging only the final answer
What it looks likeThe log shows the refund was recommended but not which model, tool results, or human steps led to it.
Why it failsThe path from input to output is what makes the behavior explainable, and the final answer alone leaves that path empty.
Do this insteadRecord every model call, tool invocation, input, output, human intervention, and escalation.
Common mistake Writing free-text sentences instead of structured fields
What it looks likeAssistant recommended a refund for customer 4481 on March 14.
Why it failsA program cannot reliably filter sentences by date, model version, or customer.
Do this insteadUse named fields such as timestamp, model_version, and customer_id in a format the observability stack accepts.
Common mistake Assuming the current model or prompt explains an old decision
Why it failsModels and prompts change over time, so today's configuration may not match what ran on the date in question.
Do this insteadRecord the model and prompt versions in effect with each event.
Common mistake Treating the record as a maintenance task instead of part of the system's purpose
Checking a First Slice for Gaps
A first slice of an agent system handles a customer's question. It records the customer input, the model call, and the final output, but it does not record tool invocations, human interventions, or escalations. Explain which later question becomes hard or impossible to answer, and name the missing record kinds that would close the gap.
Hints
- Think about the question an investigator would ask if the agent looked up a order record before recommending a refund.
- Consider what the investigator would need to know if a support staff member changed the recommendation.
- Ask whether the path from input to output can be rebuilt with a missing step.
Key Takeaways
- Telemetry is part of what a system is for, so it belongs from the first version rather than being added after release, because investigations often happen months later when only records written at the time can answer them.
- The first slice should record model calls, tool invocations, customer inputs, outputs, human interventions, and escalations, since together they make the system's behavior visible from the beginning.
- Each interaction produces several events written in order, and a later reader rebuilds the path from input to output by reading them as a sequence, so a missing record leaves a permanent gap.
- Logs should be structured, such as JSON or a format the observability stack accepts, with named fields like timestamp, model version, and customer, so they can be filtered and analyzed rather than skimmed.