Agents

An Agent is an autonomous software unit that runs on your infrastructure. Agents are the core of FixPanic's capabilities, enabling AI-powered diagnostics, monitoring, and incident response.

What is an Agent?

An agent is:

• Autonomous - Can operate independently on your servers
• AI-Powered - Understands natural language requests
• Sandboxed - Executes commands in a secure environment
• Connected - Maintains a persistent link to FixPanic

Agent Capabilities

System Diagnostics

Agents can investigate system state:

• Process monitoring (CPU, memory usage)
• Disk space and I/O analysis
• Network connectivity and traffic
• Service health and status

Log Analysis

Agents can analyze logs:

• Search for patterns and errors
• Correlate events across time
• Identify anomalies
• Summarize recent activity

Service Management

With approval, agents can:

• Check service status
• Restart services
• View container states
• Manage processes

Custom Commands

Agents can execute whitelisted commands:

• Run diagnostics scripts
• Execute health checks
• Gather metrics
• Perform routine maintenance

Agent Lifecycle

Agents go through distinct states:

State Transitions

Agent Architecture

Components

Each agent consists of:

Connection Model

Agents maintain a persistent TCP connection:

1. Registration - Agent identifies itself with credentials
2. Heartbeat - Every 30 seconds, confirms connectivity
3. Commands - Receive and execute requests
4. Responses - Stream results back to platform

MCP Shell Server

The Model Context Protocol (MCP) shell server provides:

• Tool interface for command execution
• Security validation before execution
• Resource management for processes
• Output capture for results

Agent Types

Different agents may have different capabilities:

Agent Communication

Protocol

Agents communicate using JSON over TCP:

{
  "type": "COMMAND",
  "agent_id": "agent_abc123",
  "request_id": "req_xyz789",
  "timestamp": "2024-01-15T10:30:00Z",
  "payload": {
    "command": "ps",
    "args": ["aux", "--sort=-%cpu"]
  }
}

Message Types

Security

All communication is:

• Authenticated - Using API keys
• Validated - Request ID correlation
• Timestamped - Replay attack prevention
• Logged - Complete audit trail

Resource Usage

Typical agent resource consumption:

When executing commands, usage temporarily increases based on the command.

Best Practices

Naming

Use clear, descriptive names:

• Include environment: prod-, staging-, dev-
• Include role: -web, -db, -worker
• Include location: -us-east, -eu-west

Example: prod-web-us-east-01

Monitoring

Keep agents healthy:

• Monitor connection status in dashboard
• Set up alerts for disconnections
• Review logs regularly
• Keep agents updated

Security

Protect your agents:

• Use unique API keys per cluster
• Rotate keys periodically
• Review audit logs
• Use minimal permissions

Troubleshooting Agents

Agent Not Connecting

1. Check network connectivity to socket.fixpanic.com:9000
2. Verify credentials in configuration
3. Check firewall rules
4. Review agent logs

Agent Slow to Respond

1. Check server resource utilization
2. Verify network latency
3. Review command complexity
4. Check for competing processes

Agent Keeps Disconnecting

1. Check network stability
2. Verify firewall isn't terminating idle connections
3. Review server logs for errors
4. Check for resource exhaustion

Next Steps

• Clusters - Learn how to organize agents into clusters.
• Security - Understand the security model protecting agents.
• Managing Agents - Manage agents through the dashboard.