Understanding and Debugging Agent Behavior › Common Agent Problems and How to Spot Them

Through experience debugging agents, certain patterns of problems emerge repeatedly. Knowing what to look for helps you diagnose issues faster.

Wrong Tool Selection: The agent picks a tool that doesn't match the task.

Look for logs where the selected tool doesn't make sense for the query. For example:

2025-11-10 17:20:15 - assistant - INFO - User query: What's the capital of France?
2025-11-10 17:20:15 - assistant - INFO - Selected tool: calculator

The agent chose the calculator for a geography question. This suggests the tool selection logic needs improvement, or the agent needs clearer descriptions of what each tool does.

Missing Context: The agent doesn't retrieve or use relevant information from memory.

Look for cases where the agent should have remembered something but didn't:

2025-11-10 17:25:30 - assistant - INFO - User query: What did I tell you my favorite color was?
2025-11-10 17:25:30 - assistant - INFO - Searching memory for: favorite color
2025-11-10 17:25:30 - assistant - INFO - Found 0 relevant items in memory
2025-11-10 17:25:31 - assistant - INFO - Assistant response: I don't have that information.

If the user previously mentioned their favorite color, the memory search should have found it. This indicates either the information wasn't stored properly, or the search query didn't match how it was stored.

Incorrect Reasoning: The agent makes a logical error in its thinking.

We saw this in the train example above. Look for reasoning steps that don't follow logically from previous steps, or where the agent makes incorrect assumptions.

Tool Call Failures: A tool returns an error or unexpected result.

2025-11-10 17:30:45 - assistant - INFO - Calling weather_api with: get_weather(city='Nowhere')
2025-11-10 17:30:46 - assistant - ERROR - Weather API failed: City not found
2025-11-10 17:30:46 - assistant - INFO - Assistant response: I couldn't get the weather information.

The tool failed because the city doesn't exist. This might mean the agent needs to validate inputs before calling tools, or handle errors more gracefully by asking the user for clarification.

Hallucination: The agent makes up information instead of admitting it doesn't know.

This is harder to spot in logs alone because the agent's logs might look reasonable even though the information is wrong. You typically catch this by comparing the agent's response to ground truth. Once you identify a hallucination, check the logs to see if the agent should have used a tool to look up the information but didn't.