agent-pard0x/SSH_TOOL_INTEGRATION.md

SSH Tool Integration

This document explains how to use the new SSH tool alongside the existing Shell tool in both the simple-react-agent and multi-agent-supervisor approaches.

Overview

We now have two complementary tools for system administration:

• ShellTool: Execute commands on the local machine
• SSHTool: Execute commands on remote servers via SSH

Both tools follow the same pattern as the original LangChain ShellTool, maintaining persistent connections for efficiency.

Installation

First, install the required dependency:

uv add paramiko

Usage Examples

Simple React Agent

from simple_react_agent.custom_tools import ShellTool, SSHTool, print_poem
from langchain.chat_models import init_chat_model
from langgraph.prebuilt import create_react_agent

# Create tools
shell_tool = ShellTool(ask_human_input=True)
ssh_tool = SSHTool(
    host="your-server.com",
    username="admin",
    key_filename="~/.ssh/id_rsa",
    ask_human_input=True
)

# Create agent
llm = init_chat_model("openai:gpt-4o-mini")
agent = create_react_agent(llm, [shell_tool, ssh_tool, print_poem])

Multi-Agent Supervisor

from multi_agent_supervisor.custom_tools import ShellTool, SSHTool, print_poem
from multi_agent_supervisor.agents import create_os_detector_worker

# Enhanced tools for all agents
tools = [
    ShellTool(),
    SSHTool(host="server1.com", username="admin", key_filename="~/.ssh/key"),
    print_poem
]

# Create agents with both local and remote capabilities
os_detector = create_os_detector_worker(llm=llm, tools=tools)

SSH Tool Configuration

Authentication Methods

SSH Key Authentication (Recommended)

ssh_tool = SSHTool(
    host="server.example.com",
    username="admin",
    key_filename="~/.ssh/id_rsa",  # Path to private key
    port=22,  # Default SSH port
    timeout=30.0,  # Connection timeout
    ask_human_input=True  # Ask for confirmation before executing
)

Password Authentication

ssh_tool = SSHTool(
    host="192.168.1.100",
    username="user",
    password="secure_password",
    port=22
)

Security Features

1. Human Confirmation: Set ask_human_input=True to require user confirmation
2. Connection Timeout: Configurable timeout for connection attempts
3. Warning Messages: Automatic warnings about security risks
4. Persistent Connections: Single SSH connection reused for multiple commands

Tool Integration Patterns

Local + Remote System Analysis

# Check local system
local_result = shell_tool.run(commands=["df -h", "free -m"])

# Check remote system
remote_result = ssh_tool.run(commands=["df -h", "free -m"])

# Compare results for comprehensive analysis

Multi-Server Management

# Create multiple SSH tools for different servers
web_server = SSHTool(host="web1.com", username="admin", key_filename="~/.ssh/web_key")
db_server = SSHTool(host="db1.com", username="admin", key_filename="~/.ssh/db_key")

# Agents can now manage multiple remote systems
tools = [ShellTool(), web_server, db_server, print_poem]

Safety Considerations

1. Start with Read-Only Commands: Always begin diagnostics with non-destructive commands
2. Use Human Confirmation: Enable ask_human_input=True for production systems
3. Secure Key Management: Store SSH keys securely, use proper file permissions
4. Network Security: Ensure SSH connections are over secure networks
5. Audit Logging: Monitor SSH command execution for security compliance

Example Use Cases

System Monitoring

• Compare disk usage across local and remote systems
• Monitor performance metrics on multiple servers
• Analyze logs from distributed systems

Troubleshooting

• Investigate network connectivity between local and remote systems
• Debug application issues across server tiers
• Perform maintenance tasks on remote infrastructure

Infrastructure Management

• Deploy configuration changes to multiple servers
• Collect system information for inventory management
• Perform bulk operations across server farms

File Structure

project/
├── simple-react-agent/
│   └── custom_tools/
│       ├── __init__.py          # Exports ShellTool, SSHTool, print_poem
│       ├── ssh_tool.py          # SSH tool implementation
│       ├── shell_tool_wrapper.py # Shell tool wrapper
│       └── poem_tool.py         # Existing poem tool
└── multi-agent-supervisor/
    └── custom_tools/
        ├── __init__.py          # Exports ShellTool, SSHTool, print_poem
        ├── ssh_tool.py          # SSH tool implementation
        ├── shell_tool_wrapper.py # Shell tool wrapper
        └── poem_tool.py         # Existing poem tool

Next Steps

1. Configure SSH access to your target servers
2. Test SSH connectivity manually before using the tool
3. Start with read-only commands to validate functionality
4. Integrate SSH tools into your existing agent workflows
5. Monitor and log SSH tool usage for security compliance

Troubleshooting

Common Issues

1. Connection Refused: Check if SSH service is running on target server
2. Authentication Failed: Verify username, password, or SSH key
3. Timeout Errors: Increase timeout value or check network connectivity
4. Permission Denied: Ensure proper file permissions on SSH keys (600)

Debug Commands

# Test SSH connectivity
ssh_tool.run(commands="echo 'SSH connection successful'")

# Check SSH configuration
ssh_tool.run(commands="ssh -V")  # SSH version
ssh_tool.run(commands="whoami")  # Current user