Diagnostic Commands

📍 AgentMap → Deployment → Diagnostic Commands

AgentMap provides comprehensive diagnostic tools for system health monitoring, dependency validation, and troubleshooting. These commands leverage the sophisticated DependencyCheckerService and FeaturesRegistryService to provide enterprise-grade system validation and installation guidance.

System Diagnostics

The diagnose command performs comprehensive dependency validation and system health checking using AgentMap's enterprise-grade DependencyCheckerService and FeaturesRegistryService.

agentmap diagnose [OPTIONS]

Options

--config, -c: Path to custom config file

Core Functionality

The diagnose command provides:

LLM Provider Validation: Checks dependencies and registry status for OpenAI, Anthropic, and Google
Storage System Validation: Validates CSV, JSON, File, Vector, Firebase, and Blob storage dependencies
Registry Status Coordination: Shows feature enablement vs dependency availability
Inconsistency Detection: Identifies mismatches between registry and actual dependencies
Installation Guidance: Provides specific pip install commands for missing dependencies
Environment Information: Shows Python version, paths, and package versions

Example Usage

# Run comprehensive system diagnostics
agentmap diagnose

# Use specific configuration file
agentmap diagnose --config configs/production.yaml

Sample Output

AgentMap Dependency Diagnostics
=============================

LLM Dependencies:
LLM feature enabled: True
  Openai: ✅ Available [Registry: reg=True, val=True, avail=True]
  Anthropic: ❌ Not available (Missing: langchain_anthropic) [Registry: reg=True, val=False, avail=False]
  Google: ⚠️ Dependencies OK but provider not available (Registration issue) [Registry: reg=True, val=True, avail=False]

Storage Dependencies:
Storage feature enabled: True
  csv: ✅ Available [Registry: reg=True, val=True, avail=True]
  json: ✅ Available [Registry: reg=True, val=True, avail=True]
  file: ✅ Available [Registry: reg=True, val=True, avail=True]
  vector: ❌ Not available (Missing: chromadb) [Registry: reg=True, val=False, avail=False]
  firebase: ❌ Not available (Missing: firebase_admin) [Registry: reg=True, val=False, avail=False]
  blob: ❌ Not available (Missing: azure-storage-blob) [Registry: reg=True, val=False, avail=False]

Installation Suggestions:
  For Anthropic support: pip install agentmap[anthropic] or pip install anthropic
  For vector storage: pip install chromadb
  For Google support: pip install agentmap[google] or pip install google-generativeai langchain-google-genai

Environment Information:
  Python Version: 3.11.4 (main, Jun  7 2023, 10:13:09) [Clang 14.0.6]
  Python Path: /usr/local/bin/python
  Current Directory: /Users/dev/agentmap

Relevant Package Versions:
  openai: v1.12.0
  anthropic: Not installed
  google.generativeai: Not installed
  langchain: v0.1.11
  langchain_google_genai: Not installed
  chromadb: Not installed

Dependency Validation Architecture

The diagnostic system uses a sophisticated multi-layer validation approach:

1. Feature Policy Validation

Feature Enablement: Checks if LLM and Storage features are enabled
Policy Coordination: Coordinates feature flags with technical validation
Feature Registry: Maintains centralized feature availability status

2. Technical Dependency Checking

Package Validation: Validates specific package dependencies for each provider
Version Requirements: Checks minimum version requirements (e.g., openai>=1.0.0)
Import Testing: Attempts actual imports to verify package functionality
Missing Dependency Tracking: Provides specific lists of missing packages

3. Registry Status Coordination

Registration Status: Shows if providers are registered in the features registry
Validation Status: Indicates if providers have passed dependency validation
Availability Status: Shows final provider availability for use
Inconsistency Detection: Identifies mismatches between technical validation and registry status

4. Installation Guidance System

Bundle Installation: Suggests comprehensive bundle installs (e.g., agentmap[llm])
Individual Packages: Provides specific package installation commands
Provider-Specific: Tailored installation instructions for each LLM/storage provider
Dependency Resolution: Helps resolve complex dependency conflicts

Diagnostic Scenarios

Dependency Installation Issues

Scenario: Missing LLM provider dependencies

agentmap diagnose

Example Output:

LLM Dependencies:
  Anthropic: ❌ Not available (Missing: langchain_anthropic) [Registry: reg=True, val=False, avail=False]
  
Installation Suggestions:
  For Anthropic support: pip install agentmap[anthropic] or pip install anthropic

Resolution:

# Install using bundle (recommended)
pip install agentmap[anthropic]

# Or install specific package
pip install anthropic

# Verify installation
agentmap diagnose

Registry Inconsistency Detection

Scenario: Provider has dependencies but isn't available

agentmap diagnose

Example Output:

LLM Dependencies:
  Google: ⚠️ Dependencies OK but provider not available (Registration issue) [Registry: reg=True, val=True, avail=False]

Resolution: This indicates a registry synchronization issue. The dependency checker service will automatically resolve this on next validation cycle.

Storage System Validation

Scenario: Checking vector storage availability

agentmap diagnose

Example Output:

Storage Dependencies:
  vector: ❌ Not available (Missing: chromadb) [Registry: reg=True, val=False, avail=False]
  
Installation Suggestions:
  For vector storage: pip install chromadb

Resolution:

# Install vector storage dependencies
pip install chromadb

# Verify vector storage is now available
agentmap diagnose

Feature Enablement Issues

Scenario: Features disabled in configuration

agentmap diagnose

Example Output:

LLM Dependencies:
LLM feature enabled: False

Resolution: Check feature enablement in your configuration file:

# agentmap_config.yaml
llm:
  enabled: true  # Ensure this is set to true

Cache Management Commands

AgentMap provides sophisticated validation caching to improve performance. The cache management commands help maintain optimal system performance.

Validation Cache Commands

agentmap validate-cache [OPTIONS]

Options:

--clear: Clear all validation cache
--cleanup: Remove expired cache entries
--stats: Show cache statistics (default)
--file FILE_PATH: Clear cache for specific file only

Cache Statistics

# View cache statistics
agentmap validate-cache --stats

Example Output:

Validation Cache Statistics:
==============================
Total files: 45
Valid files: 42
Expired files: 2
Corrupted files: 1

💡 Run 'agentmap validate-cache --cleanup' to remove expired entries
⚠️  Found 1 corrupted cache files

Cache Management Operations

# Clean up expired cache entries
agentmap validate-cache --cleanup

# Clear all cache
agentmap validate-cache --clear

# Clear cache for specific file
agentmap validate-cache --clear --file workflow.csv

Graph Inspection Commands

The inspect-graph command provides detailed analysis of agent service configuration and graph structure.

Graph Inspection

agentmap inspect-graph GRAPH_NAME [OPTIONS]

Options:

--csv FILE_PATH: Path to CSV file
--config CONFIG_FILE: Path to custom config file
--node NODE_NAME: Inspect specific node only
--services/--no-services: Show service availability (default: true)
--protocols/--no-protocols: Show protocol implementations (default: true)
--config-details: Show detailed configuration
--resolution: Show agent resolution details

Graph Inspection Example

# Inspect entire graph
agentmap inspect-graph MyWorkflow

# Inspect specific node with detailed resolution info
agentmap inspect-graph MyWorkflow --node ProcessData --resolution

Example Output:

🔍 Inspecting Graph: MyWorkflow
==================================================

📊 Graph Overview:
   Resolved Name: MyWorkflow
   Total Nodes: 5
   Unique Agent Types: 3
   All Resolvable: ✅
   Resolution Rate: 100.0%

🤖 Node: ProcessData
   Agent Type: DataAnalyzer
   Description: Analyze data using LLM
   🔧 Resolution:
      Resolvable: ✅
      Source: Custom Agent
   📋 Services:
      llm: ✅
      storage: ✅
   🔌 Protocols:
      LLMCapableAgent: ✅
      StorageCapableAgent: ✅
   📝 Configuration:
      Input Fields: ['data', 'query']
      Output Field: analysis

✅ No issues found - all agents properly configured!

💡 Helpful Commands:
   agentmap diagnose                    # Check system dependencies
   agentmap inspect-graph MyWorkflow --config-details  # Show detailed config
   agentmap inspect-graph MyWorkflow --node NODE_NAME  # Inspect specific node

Programmatic Diagnostic Access

For automation and monitoring integration, AgentMap provides programmatic access to diagnostic information:

from agentmap.core.cli.diagnostic_commands import diagnose_command, cache_info_command

# Get structured diagnostic data
diagnostic_data = diagnose_command()
print(diagnostic_data['llm']['openai']['available'])  # True/False
print(diagnostic_data['installation_suggestions'])   # List of suggestions

# Get cache statistics
cache_data = cache_info_command()
print(cache_data['cache_statistics']['total_files'])  # Number

Production Monitoring Integration

The diagnostic commands can be integrated into production monitoring systems for automated health checking:

Automated Health Check Script

#!/bin/bash
# health_check.sh - Production health monitoring script

echo "Running AgentMap health check..."

# Run comprehensive diagnostics
agentmap diagnose > /tmp/agentmap_health.log 2>&1

# Check for critical failures
if grep -q "LLM feature enabled: False" /tmp/agentmap_health.log; then
    echo "CRITICAL: LLM feature disabled"
    exit 2
fi

# Check for missing dependencies
missing_deps=$(grep -c "Not available" /tmp/agentmap_health.log)
if [ "$missing_deps" -gt 5 ]; then
    echo "WARNING: Multiple dependencies missing ($missing_deps)"
    exit 1
fi

# Check cache health
agentmap validate-cache --stats | grep "Corrupted files: [1-9]" && {
    echo "WARNING: Corrupted cache files detected"
    agentmap validate-cache --cleanup
}

echo "AgentMap health check passed"
exit 0

Monitoring Integration Examples

Nagios/Icinga Integration:

# /etc/nagios/commands.cfg
define command {
    command_name    check_agentmap_health
    command_line    /usr/local/bin/agentmap_health_check.sh
}

Prometheus Monitoring:

# agentmap_exporter.py
from prometheus_client import Gauge, generate_latest
from agentmap.core.cli.diagnostic_commands import diagnose_command

# Create metrics
llm_providers_available = Gauge('agentmap_llm_providers_available', 'Number of available LLM providers')
storage_providers_available = Gauge('agentmap_storage_providers_available', 'Number of available storage providers')

def collect_metrics():
    data = diagnose_command()
    
    # Count available providers
    llm_available = sum(1 for provider in data['llm'].values() if provider['available'])
    storage_available = sum(1 for provider in data['storage'].values() if provider['available'])
    
    llm_providers_available.set(llm_available)
    storage_providers_available.set(storage_available)
    
    return generate_latest()

Best Practices for System Health

1. Regular Dependency Validation

Daily Monitoring: Run agentmap diagnose as part of daily operational procedures
Automated Scheduling: Set up cron jobs or scheduled tasks for regular health checks
Dependency Drift Detection: Monitor for changes in dependency availability over time

2. Pre-Deployment Validation

CI/CD Integration: Include agentmap diagnose in deployment pipelines
Environment Validation: Verify all dependencies in staging before production deployment
Registry Consistency: Ensure feature registry state matches actual system capabilities

3. Cache Management

Regular Cleanup: Schedule agentmap validate-cache --cleanup to remove expired entries
Performance Monitoring: Monitor cache hit rates and validation performance
Storage Management: Keep cache directories under 80% capacity

4. Dependency Management Strategy

Bundle Installations: Use agentmap[bundle] syntax for consistent dependency management
Version Pinning: Pin critical dependency versions in production environments
Incremental Updates: Test dependency updates in staging environments first

5. Monitoring and Alerting

Provider Availability: Alert on LLM or storage provider availability changes
Registry Inconsistencies: Monitor for mismatches between technical validation and registry status
Performance Degradation: Track validation cache performance and diagnostic command execution times

Troubleshooting Common Issues

Dependency Installation Problems

Issue: Package installation fails or dependencies not detected

# Check current status
agentmap diagnose

# Common solutions
pip install --upgrade pip setuptools wheel
pip install agentmap[llm,storage] --force-reinstall

# Verify installation
python -c "import openai, anthropic; print('LLM dependencies OK')"

Registry Inconsistency Issues

Issue: Provider shows as having dependencies but unavailable

# Example output showing inconsistency
# Google: ⚠️ Dependencies OK but provider not available (Registration issue)

# Solution: Force registry refresh
python -c "from agentmap.di import initialize_di; c = initialize_di(); c.dependency_checker_service().validate_all_dependencies()"

Feature Enablement Problems

Issue: Features show as disabled despite correct configuration

# Check configuration format in agentmap_config.yaml
features:
  llm: true      # Ensure this is a boolean, not string
  storage: true  # Ensure this is a boolean, not string

Cache Performance Issues

Issue: Slow validation or corrupted cache

# Check cache health
agentmap validate-cache --stats

# Clean up if needed
agentmap validate-cache --cleanup  # Remove expired entries
agentmap validate-cache --clear    # Clear all cache if corrupted

Version Compatibility Problems

Issue: Package version conflicts

# Check installed versions
agentmap diagnose | grep "Package Versions"

# Fix version conflicts
pip install "openai>=1.0.0,<2.0.0" "langchain>=0.1.0,<0.2.0"

# Use bundle for compatibility
pip uninstall agentmap
pip install agentmap[llm,storage]  # Installs compatible versions

🔧 CLI Tools & Operations

CLI Commands Reference: Complete CLI command reference
Validation Commands: Workflow and configuration validation
Graph Inspector: Advanced graph analysis tools

📚 Configuration & Setup

Getting Started: Installation and initial setup
Dependency Management Guide: Comprehensive dependency management
Troubleshooting Guide: Step-by-step issue resolution

🏗️ Advanced Topics

System Health Monitoring: Production health monitoring
Configuration Reference: Complete configuration options
Service Architecture: Understanding the service layer

System Diagnostics​

Options​

Core Functionality​

Example Usage​

Sample Output​

Dependency Validation Architecture​

1. Feature Policy Validation​

2. Technical Dependency Checking​

3. Registry Status Coordination​

4. Installation Guidance System​

Diagnostic Scenarios​

Dependency Installation Issues​

Registry Inconsistency Detection​

Storage System Validation​

Feature Enablement Issues​

Cache Management Commands​

Validation Cache Commands​

Cache Statistics​

Cache Management Operations​

Graph Inspection Commands​

Graph Inspection​

Graph Inspection Example​

Programmatic Diagnostic Access​

Production Monitoring Integration​

Automated Health Check Script​

Monitoring Integration Examples​

Best Practices for System Health​

1. Regular Dependency Validation​

2. Pre-Deployment Validation​

3. Cache Management​

4. Dependency Management Strategy​

5. Monitoring and Alerting​

Troubleshooting Common Issues​

Dependency Installation Problems​

Registry Inconsistency Issues​

Feature Enablement Problems​

Cache Performance Issues​

Version Compatibility Problems​

Related Documentation​

🔧 CLI Tools & Operations​

📚 Configuration & Setup​

🏗️ Advanced Topics​

System Diagnostics

Options

Core Functionality

Example Usage

Sample Output

Dependency Validation Architecture

1. Feature Policy Validation

2. Technical Dependency Checking

3. Registry Status Coordination

4. Installation Guidance System

Diagnostic Scenarios

Dependency Installation Issues

Registry Inconsistency Detection

Storage System Validation

Feature Enablement Issues

Cache Management Commands

Validation Cache Commands

Cache Statistics

Cache Management Operations

Graph Inspection Commands

Graph Inspection

Graph Inspection Example

Programmatic Diagnostic Access

Production Monitoring Integration

Automated Health Check Script

Monitoring Integration Examples

Best Practices for System Health

1. Regular Dependency Validation

2. Pre-Deployment Validation

3. Cache Management

4. Dependency Management Strategy

5. Monitoring and Alerting

Troubleshooting Common Issues

Dependency Installation Problems

Registry Inconsistency Issues

Feature Enablement Problems

Cache Performance Issues

Version Compatibility Problems

Related Documentation

🔧 CLI Tools & Operations

📚 Configuration & Setup

🏗️ Advanced Topics