Tool Call Tracking

Real-time tool call tracking and display in PraisonAI CLI

The PraisonAI CLI automatically tracks and displays tool calls made by agents, providing visibility into what actions the AI is taking.

Overview

When you run a prompt, the CLI:

1. Loads 5 built-in tools by default
2. Tracks all tool calls made during execution
3. Displays a summary of tools used after completion

Default Tools

Every CLI prompt has access to these 5 built-in tools:

Tool	Description	Example Use
read_file	Read file contents	”Read README.md”
write_file	Write to files	”Create a hello.py file”
list_files	List directory contents	”List files here”
execute_command	Run shell commands	”Run ls -la”
internet_search	Search the web	”Search for Python tutorials”

Usage Examples

Basic Tool Tracking

# Agent automatically uses list_files
praisonai "List all files in current directory"

Output:

Tools used: list_files
- file1.py
- file2.py
- README.md
...

Multiple Tools

# Agent uses multiple tools to complete the task
praisonai "Read the README.md file and summarize it"

Output:

Tools used: list_files, read_file
This project is about...

Verbose Mode

For detailed tool call information, use verbose mode:

praisonai "List files" -v

Output:

╭─ Agent Info ─────────────────────────────────────────────────────────────────╮
│                                                                              │
│  👤 Agent: DirectAgent                                                       │
│  Role: Assistant                                                             │
│  Tools: read_file, write_file, list_files, execute_command, internet_search │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

╭───────── Tool Call ──────────╮
│ Calling function: list_files │
╰──────────────────────────────╯
Arguments: {'directory': '.'}
╭───────────────────────────────── Tool Call ──────────────────────────────────╮
│ Function list_files returned: [{"name": "file1.py", ...}]                    │
╰──────────────────────────────────────────────────────────────────────────────╯

Response generated in 2.5s
╭──────────────────────────────────── Task ────────────────────────────────────╮
│ List files                                                                   │
╰──────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────── Response ──────────────────────────────────╮
│ - file1.py                                                                   │
│ - file2.py                                                                   │
│ - README.md                                                                  │
╰──────────────────────────────────────────────────────────────────────────────╯

Adding Custom Tools

You can add additional tools using the --tools flag:

# Load tools from a Python file
praisonai "Analyze data" --tools my_tools.py

my_tools.py:

def analyze_csv(filepath: str) -> dict:
    """Analyze a CSV file and return statistics."""
    import pandas as pd
    df = pd.read_csv(filepath)
    return {
        "rows": len(df),
        "columns": list(df.columns),
        "summary": df.describe().to_dict()
    }

Callback System

The tool tracking uses a callback system that can be extended programmatically:

from praisonaiagents import register_display_callback

def my_tool_callback(message):
    """Custom callback for tool calls."""
    print(f"🔧 Tool activity: {message}")

# Register the callback
register_display_callback('tool_call', my_tool_callback)

Comparison: Default vs Verbose

Feature	Default Mode	Verbose Mode (-v)
Tool summary	✅ “Tools used: X, Y”	✅ Full panels
Arguments	❌ Hidden	✅ Shown
Return values	❌ Hidden	✅ Shown (truncated)
Agent info	❌ Hidden	✅ Full panel
Response time	❌ Hidden	✅ Shown

Best Practices

Use default mode for clean output in scripts and pipelines. Use verbose mode (-v) when debugging or learning what the agent is doing.

Tool calls are tracked via a callback system that has zero performance overhead when no callback is registered.

Related Features

Interactive Mode

Full interactive TUI with tool support

Tools Management

Discover and manage available tools

Cost Tracking

Track token usage and costs

Verbose Output

Detailed output options