Understanding and Debugging Agent Behavior › Reading Agent Logs
AI Agent HandbookAll chapters Understanding and Debugging Agent Behavior › Reading Agent LogsOne section · Sections in this chapter2 / 10 ↓
When you look at your agent's logs, you're essentially reading a story of what happened during a request. Each log entry is a sentence in that story. Your job is to follow the narrative and spot where it goes off track.
Start by identifying the boundaries of a single request. Find the log entry where the user's query came in, then follow the entries until you see the final response. Everything between those two points shows you what the agent did to process that request.
2025-11-10 15:42:10 - assistant - INFO - User query: Schedule a meeting with Alice tomorrow at 2pm
2025-11-10 15:42:10 - assistant - INFO - Tool required: True
2025-11-10 15:42:10 - assistant - INFO - Selected tool: calendar
2025-11-10 15:42:11 - assistant - INFO - Calling calendar with: create_event(attendee='Alice', date='2025-11-11', time='14:00')
2025-11-10 15:42:11 - assistant - INFO - Calendar returned: Event created successfully
2025-11-10 15:42:11 - assistant - INFO - Assistant response: I've scheduled a meeting with Alice for tomorrow at 2pm.This log sequence tells a straightforward story. The agent received a scheduling request, recognized it needed the calendar tool, called the tool with the right parameters, got confirmation, and told the user it worked. Nothing went wrong here.
Now look at a case where something did go wrong:
2025-11-10 15:45:33 - assistant - INFO - User query: What's 15% of 240?
2025-11-10 15:45:33 - assistant - INFO - Tool required: False
2025-11-10 15:45:34 - assistant - INFO - Generating direct response (no tool)
2025-11-10 15:45:34 - assistant - INFO - Assistant response: Approximately 35.The agent gave the wrong answer (15% of 240 is 36, not 35). By reading the logs, you can see exactly what went wrong. The agent decided it didn't need a tool and tried to calculate the answer directly. It got close but made a small error. The fix is clear: improve the logic that decides when to use the calculator tool, so it recognizes percentage calculations as something that needs precise computation.