I’m working with the Llama_index Python framework to create an AI Agent and need to track what happens during execution. I want to see each step the agent takes when processing requests.
I first attempted using the verbose parameter but got no output:
from llama_index.core.agent.workflow import FunctionAgent
my_agent = FunctionAgent(
tools=[my_tool],
llm=language_model,
system_prompt="You are a helpful AI assistant",
verbose=True,
allow_parallel_tool_calls=True,
)
Then I tried implementing callback handlers for debugging:
from llama_index.core.callbacks import CallbackManager, LlamaDebugHandler
# Setup debug handler
debug_handler = LlamaDebugHandler()
callback_mgr = CallbackManager([debug_handler])
my_agent = FunctionAgent(
tools=[my_tool],
llm=language_model,
system_prompt="You are a helpful assistant that will help me answer questions",
callback_manager=callback_mgr,
allow_parallel_tool_calls=True,
)
Neither approach shows the agent’s execution steps. I’m using Llama_index version 0.12.31. What’s the correct way to enable step-by-step debugging for AI agents?
Workflow-based agents have a different debugging approach compared to standard ones. One effective method is to utilize streaming responses with step callbacks. Create a custom handler by inheriting from BaseCallbackHandler and overriding the on_event_start and on_event_end methods to capture transitions in the workflow.
Additionally, you can enable global debug mode by setting Settings.debug = True from llama_index.core before initializing your agent. I’ve found that combining this setting with Settings.callback_manager = callback_mgr works better than passing the callback manager directly in the agent’s constructor. The key takeaway is that workflow agents emit specific events rather than traditional verbose output, so focus on listening for those workflow-specific events.
Had the same problem. FunctionAgent ignores the verbose parameter - it’s different from other agent types. I switched to event-based tracing and it worked. Use the trace_event method with a custom callback to capture workflow steps. You can also set LLAMA_INDEX_DEBUG=1 as an environment variable before running your script. What really helped me was wrapping the agent’s chat method with manual logging - just a simple wrapper that prints before/after each call plus the reasoning steps. Newer versions dropped the verbose flag for workflow agents specifically.
FunctionAgent doesn’t use traditional verbose output - it handles debugging through its internal workflow system. I hit this same issue last year building a document processing agent.
You need to hook into the workflow events directly. Here’s what works:
from llama_index.core.workflow import Event
class DebugWorkflowHandler:
def __init__(self):
self.steps = []
def handle_event(self, event: Event):
print(f"Step: {event.msg_type} - {event.msg}")
self.steps.append(event)
# Create handler and attach it
debug_handler = DebugWorkflowHandler()
my_agent._workflow.add_event_handler(debug_handler.handle_event)
This also worked for me - check the workflow context after each run:
response = my_agent.chat("your query")
print(my_agent._workflow.ctx.data) # Shows internal state
The workflow context has all the intermediate steps and tool calls. Way more reliable than trying to force verbose output on an agent type that doesn’t support it.
BTW, if you just need quick debugging, ReActAgent still supports verbose properly.
set your logging level to debug first - most people skip this. add import logging; logging.basicConfig(level=logging.DEBUG) before creating your agent. also double-check you’re using the right handler - some versions need TokenCountingHandler instead of LlamaDebugHandler.
check your import first - use from llama_index.core import Settings then set Settings.llm_predictor_debug = True before creating the agent. also make sure your tool functions have proper docstrings - workflow agents need them for step visibility. this fixed it for me when callback handlers didn’t work.