AI observability is the practice of collecting and connecting records that help a team understand how an AI application behaved. For agents, those records can include model requests, retrieved sources, tool calls, outputs, errors and resource usage. Their usefulness depends on what the application actually captures.
A report can arrive on time, cite a genuine document and still lead a team to the wrong conclusion. A successful execution status will not explain whether the document covered the right product version or whether a later customer report contradicted it.
Useful observability makes those questions answerable. It gives a reviewer a way to move from a disputed conclusion to the evidence, recorded activity and human decisions around it. The aim is to make the next correction more precise and the next evaluation more meaningful.
A completed run leaves three questions open
Imagine an agent preparing a weekly customer issue report. The application finishes without an error, saves a summary and records its token usage. That establishes something about execution. The team still needs to answer three different questions.
First, did the process complete the work it was assigned? A report might exist even though one source was unavailable or a tool returned only part of the requested material.
Second, does the evidence support the conclusion? A citation can point to a real record that applies to a different customer group, product revision or period.
Third, did any claimed external action occur? If the agent says it updated a support record, the team needs evidence from that system. A generated sentence about an update is not the update itself.
Keeping these questions separate prevents one status from carrying more meaning than it should. A completed execution, an accepted assessment and a confirmed external change need their own evidence.
Our guide to agentic AI describes how agents choose actions and use tools. Observability concerns the records available to inspect that activity afterward, including the gaps those records leave.
What do logs, traces and metrics show?
IBM's overview of AI observability describes the use of telemetry to understand AI systems, including their resource use and output quality. Three familiar forms of telemetry answer different questions.
A log records an event. It might say that a request failed, a source was retrieved or a result was saved. Its value depends on the context attached to it: which operation, which result and which point in the work.
A trace connects related operations. It can show how a request passed through retrieval, a model call and a tool operation, where those stages were instrumented. A span represents one recorded operation within that trace, such as a tool call with a start time, duration and outcome.
A metric summarizes a measurement across events or time. It can help a team notice that latency increased, failures became more frequent or a particular responsibility consumed more tokens. The individual records are still needed to investigate a specific case.
OpenTelemetry's agent conventions describe spans for agent, workflow and tool operations. Those conventions remain in Development status. They offer a shared vocabulary for instrumentation, not a guarantee that every client records the same information.
A trace also has limits. It describes observed or reported activity; it does not provide direct access to a model's private internal reasoning. An explanation generated after the event should not be treated as an independent account of why the model produced its answer.
The missing record can be the important one
Before interpreting a dashboard, establish its coverage. Which parts of the application emit events? Are unsuccessful calls recorded? Can a session end before its final records are delivered? Is sensitive content omitted deliberately?
If the trace contains no retrieval event, several explanations may remain possible. Retrieval may not have happened, the client may not instrument it, or the event may be missing. The record supports a conclusion only when its collection behavior is understood.
Missing measurements need the same care. An absent token count is not zero token use. An unavailable source identifier is not evidence that the answer used no source. Preserve the distinction between a measured value, an estimate and an unknown.
Coverage can also differ between participants in the same project. One client may provide detailed tool events while another saves only the result. A shared review should make that difference visible before comparing their behavior.
For retrieved information, distinguish what a search returned from what the application actually supplied to the model. Our context engineering guide explains that selection. The RAG and memory guide covers the persistent sources behind it.
Example: a resolved issue that was still happening
In this illustrative example, a consumer electronics company is reviewing reports of a device pairing problem. Support has supplied the week's cases. Engineering has supplied a closure note for a firmware fix. An agent prepares the weekly issue summary for a product lead.
The summary says that the pairing issue is resolved. A support specialist challenges it because customers with another hardware revision are still reporting the same symptom.
The team supplies the records described here. The example assumes no automatic connection to its support or engineering systems.
Begin with the disputed claim
Keep the report as it was delivered and identify the exact conclusion under review. Save the assignment that produced it, including the reporting period and the requirement to distinguish affected hardware revisions.
The investigation needs an original result to compare with the correction. Editing the report immediately and losing the earlier text would remove useful evidence about the failure.
Read the cited source in full
The engineering note says that the fix passed verification on hardware revision A. It does not establish that revision B is resolved. The agent cited a genuine source but extended its scope.
The reviewer also checks the supplied support cases. They include reports involving revision B after the fix was released. Those reports need assessment; their existence does not by itself establish that every case has the same technical cause.
The defensible conclusion is narrower: the closure evidence covers revision A, while revision B remains unresolved in the supplied material.
Compare the evidence with the recorded activity
Suppose the instrumented client retained the selected context references and the model request. The reviewer can check whether the full engineering note, its revision limitation and the newer support cases were included.
If the model received all of them, the failure concerns how the answer used the available evidence. If the application omitted the later cases, the selection process needs attention. If the relevant request content was never retained, the team cannot establish the distinction from the trace alone.
That uncertainty matters. It would be premature to label the problem a retrieval failure merely because retrieval is a convenient part of the system to change.
Correct the record without broadening the claim
The product lead records the accepted correction: the fix is verified for revision A; the supplied reports do not support closure for revision B. The support specialist identifies what further evidence is required.
The corrected result links to the original report and the records used to challenge it. A later participant can distinguish the rejected conclusion from the accepted assessment. Customer communication remains with the responsible people.
Test the explanation before changing the system
If authorized records establish that the application omitted a necessary source, test a revised selection process against the same reporting task. If the source was present but its limitation was lost in the answer, test an output requirement that preserves the scope of each conclusion.
Change one relevant part at a time where practical. Replacing the model, changing retrieval and rewriting the brief together would make a better result harder to interpret. A comparison should record which inputs and configuration changed, with no assumption that a single successful repeat proves reliability.
Measure cost in the context of useful work
Resource measurements can reveal work that deserves investigation. Repeated calls to the same tool may reflect a retry, an ambiguous response or an agent that has not recognized it already has enough information. The event sequence helps distinguish those possibilities.
Time also needs context. Separate the duration of a model call from the time a task spent waiting for a source, an executor or human review. A long approval wait is a different operational problem from slow inference.
Token usage is useful when its origin is clear. Identify the model and operation where available, retain reported usage and label estimates. A token count alone is not an invoice; the applicable pricing and other charges need separate accounting.
Compare useful results under a consistent acceptance rule. A cheap report that omits an affected product revision has not delivered the same result as a report that identifies the unresolved issue. A quality assessment should accompany the resource comparison.
Turn a correction into an evaluation case
An investigation becomes more valuable when the team can use it to test a future change. Retain a permitted version of the inputs, the question being asked and the criteria for an acceptable answer.
For the pairing report, the criteria could be specific:
Identify the hardware revision covered by the verification note.
Preserve the unresolved status of the other revision when the supplied evidence cannot establish closure.
Cite the records that materially support each conclusion.
State when a necessary record is missing or inaccessible.
These criteria describe behavior the team can inspect. They do not require a particular sentence or a polished tone to stand in for correctness.
MLflow's trace evaluation documentation shows how recorded intermediate activity can inform evaluation, alongside outputs, expected results and human feedback. In the proposed test, the final report and the selected evidence would both matter.
Choose the evaluator to fit the criterion. A program can check that a required source identifier is present. Establishing that the source supports a conclusion may require an informed reviewer or a carefully tested model based judge. Automated judgments should be checked against human reviewed cases, particularly when the distinction is subtle.
Include a case where both revisions really are resolved and another where one source is unavailable. Otherwise, a system could pass the original example by always declaring that revision B is unresolved.
Test retained cases before accepting a change, then inspect new work for different failures. Keep the evaluation set controlled and separate from information the agent can simply copy while answering. Repeatedly tuning to one known mistake can conceal weak performance elsewhere.
Saving feedback or an evaluation does not itself retrain the underlying model.
What belongs in a reviewable record?
A team does not need every available field to investigate every result. It needs enough linked information to answer the questions that matter for the assignment.
For the weekly report, a useful record would include the assignment and reporting period; the result as delivered; the identities and revisions of relevant sources; and the recorded operations available from the client. Attach the review separately, including who accepted the correction and what remains unresolved.
Record the origin of each measurement or event. A tool receipt, an event emitted by a client and an explanation written by an agent have different evidential roles. A detailed explanation can help a reviewer without becoming independent proof of the action it describes.
Where content cannot be retained, keep permitted identifiers and an explicit coverage note. An authorized reviewer may be able to inspect the source in its owning system. A reference preserves a route to evidence; it does not give the reader permission to access it.
Make the record usable across sessions. Someone continuing the work should be able to locate the original claim, the accepted correction and the reason the distinction matters. A large collection of disconnected events can still leave those questions unanswered.
How does Swarm fit into AI observability?
Swarm brings shared work into Spaces, where authorized participants can use project records, outputs, Runs and human decisions together. That provides a place to connect an execution result with the evidence and review that give it meaning.
For a disputed report, an authorized reviewer can inspect the Run, full output, relevant source records and available action trace. The public guide distinguishes a client reported trace from proof of an external effect: an action's own receipt is still needed to establish that effect.
A Run's execution outcome also remains separate from the judgment on its result. Swarm evaluations are saved judgments and can support configured follow up work. They are not human approval. Saving a review does not authorize a client to communicate with customers or change an external system.
What Swarm can show depends on the records actually supplied through its supported execution and connection paths. Connecting a client does not automatically instrument every model request, local file access or external tool call. An OpenTelemetry connection would require its own supported integration; a Space connection alone does not establish one.
Our MCP guide explains supported tool connections. A connection protocol, an instrumentation library and a shared work record address different responsibilities. Teams may need more than one of them to investigate a result.
An accepted correction should remain distinguishable from the earlier proposal or output. The next authorized session can retrieve that decision, check its scope and continue from it. The agentic workflows guide covers the responsibilities and approval boundaries around those handoffs.
The public connection guide describes the current supported operations. Keep instrumentation and evaluation requirements explicit when building on those operations. A record of ongoing work is useful precisely when its contents and limitations can be inspected.
How much information should a team capture?
Capturing everything can expose information that the operational reviewers do not need. Prompts, tool arguments and outputs may contain customer details, confidential documents or credentials. The telemetry system can become another destination for that material.
OpenTelemetry's content guidance recommends keeping instruction and message capture off by default, with deliberate opt in. It also describes storing content separately and retaining references so access can be controlled independently.
Define the audience and retention period before collecting sensitive content. Remove credentials and unnecessary personal data before transmission. A later dashboard filter cannot undo a secret that was already copied into storage.
Review access to traces as carefully as access to the underlying project records. A support reviewer may need the fact that an engineering source was consulted without receiving the confidential contents of that source. When records are redacted, sampled or omitted, preserve enough information to make that limitation visible.
Make the next failure easier to understand
Start with one result that required a meaningful human correction. Ask whether another reviewer could reconstruct the disputed claim, inspect its supporting evidence and identify what changed after the review.
If the record cannot answer those questions, add the specific missing connection. It might be a source revision, the scope of an accepted decision or the origin of a tool result. More telemetry is useful when it resolves an uncertainty that matters.
Then turn the correction into a test the team can run before accepting its next change. Preserve the distinction between successful execution, a supported conclusion and an authorized action. That is how observability becomes part of maintaining useful AI work, with evidence that people can continue to examine as the system evolves.