What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
To diagnose an AI agent failure, keep four kinds of evidence connected: logs that show what happened, errors that capture the observed failure, code that explains the behavior, and version details that identify the implementation that ran. None is a diagnosis by itself. The four-part model is a practical debugging framework, not a formally mandated standard; observability guidance explicitly treats logs, metrics, and traces as complementary signals.
Why a final answer rarely identifies the failure
An agent’s visible response is an outcome, not a reliable explanation of how the run failed. An agent can make many model and tool calls, pass work between sub-agents, and continue after an earlier mistake. In these long, probabilistic workflows, the final error may be several steps removed from the first problem. Microsoft Research’s AgentRx framework focuses on finding the first unrecoverable failure step rather than treating the final response as the whole story: Microsoft Research’s AgentRx overview.
Operationally, it helps to distinguish three standard observability signals from the two additional debugging anchors in this article. Logs record events and errors; metrics measure behavior such as latency and token use; traces expose the execution path and intermediate steps. Code and version metadata connect that runtime evidence to the behavior that produced it. Google Cloud describes logs, metrics, and traces as inputs for debugging failures, monitoring costs, and analyzing agent behavior: Google Cloud’s agent observability guidance.
What each of the four evidence types tells you
| Evidence | Question it answers | Useful contents |
|---|---|---|
| Logs | What happened, and when? | Timestamped events for run starts and ends, model requests and responses, tool calls and results, retries, state changes, and handoffs. |
| Errors | What failure was actually observed? | Exception or API/tool failure, emitting component, status code, retryability, and enough surrounding context to separate an upstream cause from a downstream symptom. |
| Code | What behavior could have produced that event? | The relevant orchestration logic, prompt, tool schema, validation rule, policy, and error handling. |
| Versions | Which implementation produced this run? | Where available, the model identifier, prompt or configuration revision, agent and tool versions, dependency or container image version, and source commit or deployment identifier. |
Logs, errors, code, and versions are not interchangeable. A log may show a tool returned an unexpected value; an error record may show the resulting exception; the code may reveal how the value was handled; version metadata tells you which code and configuration were active. Metrics add another perspective: they can show whether the incident coincided with changes in latency, token use, or error rates, but they do not replace per-run evidence.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →#1 Best Overall
- Used Book in Good Condition
How to build the four-part record
1. Log structured events across the run
Record significant agent actions as structured, timestamped events rather than relying on free-form messages alone. Include a stable run or trace identifier that travels with the work across services. A common time basis and consistent fields help teams reconstruct a sequence and correlate it with logs from other components. The CNCF’s discussion of cloud-native agentic standards covers consistent structured data, common identifiers, and canonical logging: CNCF’s standards discussion.
For agent workflows, useful events include model calls, tool invocations, retries, state transitions, and sub-agent handoffs. Microsoft Foundry’s Build 2026 article describes traces that can include prompts, model calls, tool invocations, and sub-agent hops: Microsoft Foundry’s agent observability article. Capture sensitive prompt and payload data only under appropriate access controls and retention policies.
2. Record the precise observed error
Preserve the actual exception, tool or API failure, status code, emitting component, and whether the operation was retryable. Keep enough adjacent trace context to determine whether a failure began upstream or appeared downstream. Avoid labeling a suspected defect as a proven root cause before the evidence supports it.
Error grouping can help when incidents recur. For example, Google Cloud documents Error Reporting as analyzing Cloud Logging entries to group errors and expose their history and causes. That is a capability of that service, not a property guaranteed by every logging platform.
3. Inspect the implementation at the failing step
Use the trace to identify the component and step to inspect. Then check the prompt and orchestration logic, tool schema, validation rules, applicable policy, and error handling for the behavior visible in the record. AgentRx illustrates an approach in which tool schemas and domain policies become executable constraints, allowing violations to be logged at specific steps.
State what the evidence shows before stating why it happened. “The tool received an argument that did not match its schema” is an observation if the trace establishes it; “the prompt caused the mismatch” is a hypothesis until a reproduction or other supporting evidence confirms it.
Rank #4
- Ultimate Gift Mug That Stands Out From the Rest: Do you spend your days debugging code and your nights dreaming about syntax errors? Then you know that debugging is a process that can take you on an emotional rollercoaster. That's why we created the "6 Stages of Debugging" mug - to help you laugh through the pain. Just don't blame us if you start talking to your code like it's a person - we've all been there.
- Premium Ceramic Coffee Mug: This high-quality ceramic mug has a premium hard coat that provides crisp and vibrant color reproduction sure to last for years. Printed on both sides for either left or right-handed person so the awesome message and art will be visible. High-gloss and has a premium finish that can make you enjoy your drink more. Can also be used as pen holders on your office work table, planter for your kitchen herb, jewelry holder, or serving your favorite dessert.
- Relatable Humorous Quote: Why settle for a boring old mug when you can have this one-of-a-kind drinkware on your dining, kitchen, or work table? Bring a smile to your loved ones' faces with this hilarious mug. Featuring a witty and relatable quote, this mug is sure to brighten anyone's day. Whether you're enjoying your morning coffee or taking a well-deserved break at work, this mug is the perfect pick-me-up. A conversation starter, it's also a surefire way to lift anyone's mood.
- Hilarious and Quirky Gift Mug: A great gift for anyone who works in software development or coding, especially those who have a good sense of humor about the ups and downs of debugging. It could also be a fun gift for anyone who enjoys programming or technology-related humor, even if they're not a professional coder.
- Dishwasher and Microwave Safe: These fantastic drinking mugs can go straight in the dishwasher, all day every day, meaning it can save you time, and be more hygienic. Perfect for your favorite hot or cold beverages. Easily reheat that coffee or tea you forgot to drink right away because it is microwave safe. Saves you time, is very convenient, and is perfect for your busy lifestyle.
4. Attach version context to each run
Record the implementation identifiers available in your system: model, prompt and configuration revision, agent and tool versions, dependency or container image, and source commit or deployment. This is a recommended engineering practice, not a universal version schema prescribed by the cited sources. Without version context, an investigator may inspect code that has changed since the run occurred and mistake current behavior for historical behavior.
A practical sequence for investigating a failed run
- Find and correlate the run. Start with the run or trace ID, then follow it across the agent, tools, services, and queues involved. Cross-boundary tracing can avoid manual reconstruction from disconnected systems; AWS identifies boundary-limited tracing as a production observability weakness in its agent monitoring, management, and recovery guidance.
- Read the trace chronologically. Mark the first unexpected observation, not just the user-visible failure at the end. Determine whether later errors are new failures or consequences of that earlier event.
- Compare actual inputs and outputs with expectations. Check tool arguments and results against the relevant schema and policy. Preserve the specific trace evidence for each suspected violation.
- Open the matching implementation. Use the run’s version metadata to inspect the code, prompt, configuration, and tool definitions that were active at the time.
- Separate observation from diagnosis. Record the observed error, the suspected cause, and remaining uncertainty as distinct findings. Reproduce the failure where possible, and test the proposed change against the failing case or representative evaluations.
- Check neighboring runs. Look for recurrence and associated changes in errors, latency, or token use. Databricks describes using production traces to support evaluation workflows and build representative evaluation or golden datasets: Databricks’ agent observability and quality documentation.
What to compare when choosing observability tooling
For a team evaluating implementation options, compare capabilities against its failure modes and operational constraints rather than treating a product label as proof of coverage.
Best Value
- Programmer present idea with funny saying for developer, or coder who loves programming, coding. Cool geek apparel in nerd themed clothes for those who study information technology, and science.
- Get this funny computer science clothing for birthday & Christmas for best software engineer. Funny gag present for men, women, mom, dad, grandma, grandpa, sister, brother, or kids.
- Lightweight, Classic fit, Double-needle sleeve and bottom hem
- Trace completeness: Can traces cover model calls, tool activity, sub-agent handoffs, and asynchronous service or queue boundaries?
- Signal correlation: Can logs, errors, metrics, and traces be joined through stable identifiers and a consistent time basis?
- Payload controls: Can prompt, response, and tool payload capture be governed with appropriate access controls and retention?
- Version context: Can run records carry deployment, code, model, tool, and configuration identifiers?
- Evaluation workflow: Can production failures be turned into reproducible tests or representative evaluation cases?
- Interoperability: Can telemetry be exported and mapped to common conventions, including OpenTelemetry where appropriate? Google recommends vendor-neutral OpenTelemetry instrumentation in broader observability guidance, while the CNCF discusses standard semantic conventions.
- Operating cost: What retention, storage, access-control, and maintenance overhead follows from the detail you choose to capture?
What AgentRx’s reported results do—and do not—show
Microsoft Research reports that AgentRx was evaluated on 115 manually annotated failed trajectories spanning τ-bench, Flash, and Magentic-One. Against prompting baselines, the framework reported a 23.6% improvement in failure localization and a 22.9% improvement in root-cause attribution. These are results for one framework and benchmark, not a guarantee that a particular observability setup will improve every team’s debugging performance.
The practical lesson is narrower and more durable: preserve enough evidence to identify where the run first went wrong, connect that evidence to the implementation that ran, and test the diagnosis against the actual failure rather than inferring cause from the final response alone.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
