agent-pard0x/README.md

🤖 LangGraph Sysadmin Debugging Agent

A LangGraph-powered AI agent designed to assist system administrators in their daily debugging tasks by analyzing log files and executing shell commands with intelligent reasoning.

🛠️ Technology Stack

This is a LangGraph agent that combines:

• LangGraph: State-based AI agent framework for building conversational AI workflows
• ReAct (Reasoning and Acting): Langchain primitive to create ReAct agents
• OpenAI GPT-4o-mini: Large Language Model for intelligent reasoning and tool usage
• LangChain Tools:
  • ShellTool (prebuilt): Executes shell commands for system investigation
  • log_analyzer (custom tool): Structured log file analysis with pattern recognition
• Loghub Dataset: Comprehensive collection of real-world system logs as git submodule

🎯 Agent Goals

This agent helps sysadmins by:

• Log Analysis: Automatically detect error patterns, frequency anomalies, and timeline issues
• Shell Operations: Execute diagnostic commands (grep, awk, tail, ps, netstat, etc.)
• Pattern Recognition: Identify common system issues across different log types
• Interactive Debugging: Maintain conversation context for multi-step troubleshooting
• Knowledge Transfer: Demonstrate best practices for log analysis and system debugging

📊 Dataset

The agent uses the Loghub repository as a git submodule, providing access to:

• Distributed Systems: HDFS, Hadoop, Spark, Zookeeper, OpenStack
• Supercomputers: BGL, HPC, Thunderbird
• Operating Systems: Windows, Linux, Mac
• Mobile Systems: Android, HealthApp
• Server Applications: Apache, OpenSSH
• Standalone Software: Proxifier

🚀 Setup Instructions

Prerequisites

• Python 3.8+
• OpenAI API key
• Git

Installation

1. Clone the repository with submodules:

   git clone --recurse-submodules https://github.com/your-username/langgraph-pard0x.git
   cd langgraph-pard0x
   

2. Install dependencies:

   # Using uv (recommended)
   uv sync
   
   # Or using pip
   pip install -r requirements.txt
   

3. Set up OpenAI API key:

   export OPENAI_API_KEY='your-api-key-here'
   
   # Or create a .env file
   echo "OPENAI_API_KEY=your-api-key-here" > .env
   

4. Initialize the loghub submodule (if not cloned with --recurse-submodules):

   git submodule update --init --recursive
   

Running the Agent

python main.py

💡 Usage Examples

Multi-steps multi-tools debugging:

User: Where is the log file named Linux_2k.log on my system?
Agent: I'll search the file Linux_2k.log on your system and return its path.
[Executes shell tool to `find / -name "Linux_2k.log"]

User: Analyze this log file and tell me if there are any issues or anomalies on my system
Agent:
[Use log analysis tools on Linux_2k.log]

Specific Analysis Types

User: Get a frequency analysis of Apache error patterns
Agent: [Uses analyze_log_file with analysis_type="frequency" on Apache logs]

User: Show me timeline patterns in Hadoop logs
Agent: [Uses analyze_log_file with analysis_type="timeline" on Hadoop logs]

User: Give me a summary of the Windows event logs
Agent: [Uses analyze_log_file with analysis_type="summary" on Windows logs]

Combined Approach

User: Find all critical errors in the system and suggest fixes 
Agent: 
1. [Analyzes multiple log files for error patterns]
2. [Executes shell commands to gather system state]
3. [Provides structured analysis and recommendations]

🔧 Available Analysis Types

The custom log_analyzer tool supports:

• error_patterns: Detects error keywords (error, fail, exception, critical, fatal, denied, refused, timeout)
• frequency: Identifies most common log patterns by normalizing timestamps, IPs, and UUIDs
• timeline: Extracts and analyzes timestamp patterns for chronological debugging
• summary: Provides basic statistics and sample content overview

📁 Project Structure

langgraph-pard0x/
├── main.py              # Main LangGraph agent
├── log_analyzer.py      # Custom log analysis tool
├── loghub/             # Git submodule with log datasets
│   ├── Linux/
│   ├── Apache/
│   ├── OpenSSH/
│   └── ...
├── pyproject.toml      # Project dependencies
└── README.md          # This file

⚠️ Safety Note

This agent has shell access for diagnostic purposes. Use with caution and only in safe environments. The agent is designed to help with debugging, not to make system modifications.

Troubleshooting

"Please set your OPENAI_API_KEY environment variable"

• Make sure you've set your OpenAI API key using one of the methods above
• Verify your API key is valid and active

"Error initializing chatbot"

• Check your internet connection
• Verify your OpenAI API key has sufficient credits
• Make sure all dependencies are installed correctly

Loghub submodule not found

• Run git submodule update --init --recursive to initialize the submodule
• Ensure you have proper git access to the loghub repository

🤔 Open Questions

This project raises several interesting technical and architectural questions worth exploring:

Conversation History Management

• Should we pass all the conversation history to the LLM or not?

ReAct vs. Custom StateGraph

• When to use LangGraph's ReAct primitive vs. a custom StateGrap?
• see react_vs_custom.md for a detailed comparison

Tool Architecture Decisions

• When to use LangChain prebuilt tools and custom tools vs. MCP (Model Context Protocol) integrations?