Originally published on tamiz.pro.
You built the agent. The prompt looks solid. The RAG pipeline is technically "working" because your vector DB returns results. But when you watch the agent in production, it stalls. It hallucinates. It loops on tool calls it shouldn't be making. It forgets context from ten turns ago.
The problem isn't the LLM itself; it's that we treat agentic systems like black boxes. We send a prompt and hope for a completion. But an AI agent is a stateful, asynchronous system with complex feedback loops—memory accumulation, tool execution side-effects, and multi-hop reasoning paths. Without granular observability, you are flying blind.
This is not a guide on how to build a RAG pipeline. This is a guide on how to debug one when it fails. We will dissect the three critical pillars of agent observability: Memory State, Tool Execution, and Retrieval Validity. By the end, you will have a diagnostic framework to identify exactly where your agent is breaking and how to fix it.
The Observability Gap in Agentic Systems
Traditional application observability relies on three pillars: logs, metrics, and traces (spans). In a standard API call, a trace is simple: Request → Processing → Response.
In an agentic loop, a single user query can generate:
- A sequence of LLM calls (reasoning steps).
- Multiple tool invocations (database queries, API calls).
- Complex memory read/write operations.
- RAG retrieval requests with varying chunk sizes and overlap.
If you only log the final output, you lose the causal chain. Did the agent fail because it didn't retrieve the right document? Or did it retrieve the document but fail to follow the tool instructions because its previous memory state was corrupted?
Observability for AI agents requires semantic tracing—understanding not just that a tool was called, but why the model decided to call it, and what context it had at that moment.
Pillar 1: Tracing the Tool Call Lifecycle
Tools are the hands of your agent. When an agent fails, the most common symptom is a "tool failure" or a "loop failure." This usually stems from three issues: schema mismatch, permission/environment errors, or reasoning drift.
What to Trace
Every tool call must be instrumented with a high-fidelity trace that captures:
- Thought Process: The LLM's internal monologue or reasoning string preceding the tool call. This is crucial for understanding if the model chose the wrong tool or just used it incorrectly.
- Arguments Serialization: The exact JSON arguments sent. LLMs are notorious for slight JSON formatting errors (missing commas, unescaped quotes).
- Tool Latency & Error Codes: Distinguish between network timeouts and application logic errors.
- Output Size: Tool outputs (especially from APIs or DB queries) can exceed the context window, causing silent truncations that break downstream reasoning.
The "Tool Use" Debugging Pattern
Let's look at how you should structure your observability data. Whether you are using LangSmith, Phoenix, Arize, or OpenTelemetry, the structure should look like this:
{
"trace_id": "a1b2c3d4-5678-90ef-ghij-klmnopqrstuv",
"span_id": "tool-789",
"span_kind": "tool",
"name": "get_customer_order",
"input": {
"thought": "The user mentioned order #12345. I need to fetch the status. I will use get_customer_order.",
"arguments": {
"order_id": "12345",
"include_history": true
},
"tool_schema_version": "v1.2"
},
"output": {
"result": "{\"status\": \"shipped\", \"carrier\": \"FedEx\"}",
"latency_ms": 120,
"error": null
},
"metadata": {
"model": "claude-sonnet-4-20250514",
"temperature": 0.1
}
}
Common Tool Failure Modes
When debugging, check for these specific patterns:
- The Hallucinated Argument: The model calls the tool but passes a value that doesn't exist (e.g.,
order_id: "undefined"). This usually indicates poor tool documentation or ambiguous schemas. Fix: Enforce strict JSON schema validation in your prompt or use function-calling fine-tuning. - The Silent Failure: The tool returns an error, but the agent treats it as a valid response and continues. Fix: Implement a "re-prompt on error" strategy where the agent sees the error and must retry with corrected arguments.
- The Infinite Loop: The agent calls the same tool repeatedly without making progress. This often happens when the tool output is too large or irrelevant. Fix: Add a loop detection heuristic in your observability dashboard.
Pillar 2: Memory State Auditing
Memory is the second major failure point. Agents use two types of memory:
- Short-term (Context Window): The conversation history passed to each LLM call.
- Long-term (Vector Store/Database): Persistent facts retrieved via RAG or written to a knowledge base.
The Short-Term Memory Problem
As conversations grow, the context window fills up. If you simply truncate the beginning of the conversation, the agent loses early instructions or user preferences. If you don't manage this, you get "lost in the middle" phenomena, where the model ignores critical info sandwiched between new and old tokens.
What to Trace:
- Context Window Utilization: Track the number of tokens consumed vs. the model limit at every step.
- Summarization Events: If you use a summarization model to compress old history, log the summary input and output. Did the summary capture key details?
- Insertion Order: Verify that the system prompt, tools, and history are injected in the correct order. A common bug is accidentally placing the system prompt after the conversation history, which renders it ineffective.
The Long-Term Memory Problem
Long-term memory is where RAG comes in. But "RAG" is often a black box. You insert text, you query text. But is the agent actually using the retrieved chunks effectively?
The Retrieval-Generation Gap:
A frequent failure mode is Relevant Retrieval but Poor Utilization. The agent retrieves the correct document, but fails to ground its answer in it. This suggests the prompt is not explicitly instructing the model to only use the provided context, or the context is cluttered with irrelevant noise.
Conversely, you might see Irrelevant Retrieval leading to Hallucination. The agent invents an answer based on a retrieved document that is only tangentially related. This indicates your embedding model or chunking strategy is flawed.
Pillar 3: The RAG Checklist
To systematically diagnose RAG failures, use this checklist. Each item corresponds to a specific observable metric.
1. Retrieval Precision
- Metric: Hit Rate (Did the retrieved chunk contain the answer?) and mAP (Mean Average Precision).
- Debug Action: Inspect the top-K chunks returned for failed queries. Are they topically relevant? If not, your embeddings are failing. Consider switching embedding models or adding hybrid search (BM25 + Vector).
2. Chunking Integrity
- Metric: Chunk Overlap and Semantic Completeness.
- Debug Action: If a document is split mid-sentence or mid-table, the agent may misunderstand the data. Visualize chunk boundaries. Ensure chunks are semantically self-contained (e.g., a paragraph or a table, not arbitrary token counts).
3. Context Relevance Filtering
- Metric: Noise Ratio (Relevant tokens vs. Total context tokens).
- Debug Action: Implement a re-ranking step. After initial retrieval, use a cross-encoder or the LLM itself to score relevance before passing to the generation step. If the noise ratio is high, the agent is distracted by irrelevant information.
4. Grounding Verification
- Metric: Answer Faithfulness Score.
- Debug Action: Use an evaluator LLM to compare the agent's answer against the retrieved context. Does the answer introduce facts not present in the context? If yes, your prompt needs stronger grounding constraints (e.g., "Answer only using the provided context. If the context does not contain the answer, say so.").
Building a Diagnostic Dashboard
To operationalize this, you need a dashboard that correlates these three pillars. Here is a conceptual layout for an agent observability view:
The "Single Request" Timeline
A vertical timeline showing:
- User Input: The original query.
- Intent Classification: What the model thought the user wanted (e.g., "Look up order status").
- Memory Fetch: Which long-term memories were retrieved and their relevance scores.
- Tool Calls: A nested list of all tool invocations with their inputs, outputs, and latency.
- Context Construction: A view of the actual prompt sent to the LLM (with sensitive data redacted), showing token counts.
- LLM Output: The raw completion and the final response.
- Evaluation Score: If you have an evaluator, show the faithfulness and relevance scores.
Anomaly Detection Patterns
Set up alerts for:
- High Tool Error Rate: Sudden spike in tool failures indicates a breaking change in an upstream API or schema.
- Long Loop Detection: If the agent makes >5 tool calls for a simple query, flag it. This indicates reasoning drift.
- Low Retrieval Confidence: If the similarity scores for RAG queries drop below a threshold, your vector database may be drifting or your index may be stale.
- Context Overflow: Alerts when token usage exceeds 90% of the context window, signaling the need for better summarization or chunking.
Case Study: The "Stalled" Agent
Let's walk through a real-world debugging scenario.
Symptom: Users report that the customer support agent often hangs or gives vague answers like "I can help with that" without taking action.
Step 1: Inspect Traces.
You filter traces for queries where the final response was vague. You notice a pattern: the agent retrieves the "Returns Policy" document but then calls check_return_eligibility with null for the order ID.
Step 2: Analyze Memory.
Looking at the memory trace, you see the user mentioned the order ID in the first turn, but by the time the agent needed it, the context had been summarized, and the order ID was dropped.
Step 3: Identify the Root Cause.
This is a Memory Failure, not a RAG failure. The retrieval was perfect (the policy was found), but the short-term memory lost critical structured data.
Step 4: Implement the Fix.
Instead of naively summarizing the entire history, you implement a structured memory extraction step. Before summarizing, a lightweight model extracts key entities (Order ID, Product SKU, Customer Name) into a separate JSON object that is always preserved, regardless of context window pressure.
Step 5: Validate.
You re-run the failing traces. The agent now retrieves the policy and correctly fills in the Order ID from the structured memory. The "vague answer" rate drops by 80%.
Tools of the Trade
You don't need to build all of this from scratch. Several tools specialize in agent observability:
- LangSmith / LangFuse: Excellent for tracing LangChain/LlamaIndex agents. Provides built-in evaluation datasets and prompt management.
- Phoenix (Arize): Great for visualizing embeddings and understanding retrieval quality. Strong integration with OpenTelemetry.
- Helicone: A proxy-based observability layer that works with any LLM provider. Good for cost tracking and latency analysis.
- LangGraph: If you are building complex agent workflows, LangGraph provides built-in persistence and checkpointing, making state debugging much easier than with standard LangChain agents.
Frequently Asked Questions
Q: How do I know if my RAG retrievals are actually being used by the agent?
A: Compare the retrieved chunks to the final answer. Use a tool like RAGAS or a custom evaluator to measure "Answer Relevance" and "Context Precision." If context precision is low, the agent is ignoring the retrieved chunks.
Q: My agent loops infinitely on tool calls. How do I stop it?
A: Implement a hard limit on tool iterations in your code. Additionally, add a "reflection" step where the agent evaluates if its last action made progress. If not, it should ask the user for clarification or give up. Observability helps here by letting you visualize the loop and identify which tool is causing the cycle.
Q: Should I log the full conversation history?
A: Only if necessary. Conversation history can contain PII. Instead, log a hash of the history or a summary of the history. For debugging, you can reconstruct the history from the trace IDs in your storage, but don't include raw PII in your observability platform.
Conclusion
Building an AI agent is easy; making it reliable is hard. Reliability comes from understanding the internal state of your system. By tracing tool calls, auditing memory states, and rigorously checking your RAG pipeline, you can move from guessing why your agent fails to knowing exactly how to fix it.
Start small. Instrument one agent. Define the traces you need. Build your checklist. The complexity of agentic systems is manageable when you have visibility into every decision they make.
For more insights on AI engineering best practices, visit Tamiz's Insights to stay updated on the latest trends in LLM tooling and architecture.
