Managing Agents

An Agent in OpsSquad.ai is a cloud-based AI entity that works as part of a squad. Agents can investigate issues, execute commands through linked nodes, and respond to incidents using AI-powered intelligence.

Agent Lifecycle

Agents go through several states during their lifecycle:

Viewing Agents

Navigate to the Agents page to see all your agents in a tabular view.

Agent List Columns

Filtering Agents

Use the filter options to narrow down your view:

• Search: Filter by agent name or ID
• Status Filter: Show only Active, Linked, Unlinked, or Inactive agents
• Squad Filter: View agents from a specific squad
• Node Filter: View agents by their linked node status

Agent Actions

Individual Actions

Click the actions menu (three dots) on any agent row:

Warning: Delete is irreversible! This action removes the agent and all its data permanently.

Bulk Actions

Select multiple agents using the checkboxes on the left:

• Bulk Link - Link multiple agents to nodes
• Bulk Unlink - Disconnect multiple agents from nodes
• Bulk Pause - Pause all selected agents
• Bulk Resume - Resume all selected agents
• Bulk Delete - Remove all selected agents

Agent Details Page

Click on an agent name to access its detail page:

Overview Tab

• Status: Current state with health indicator
• Squad: Parent squad with link
• Linked Node: Which node (if any) the agent is linked to
• Node Status: Online/Offline status of linked node
• Last Activity: When the agent last executed a command
• Connection: Real-time connection status to linked node

Logs Tab

View command execution logs from the linked node:

[2024-01-15 10:23:45] INFO  Agent linked to node_abc123
[2024-01-15 10:23:46] INFO  Received chat request: check CPU usage
[2024-01-15 10:23:47] INFO  Executing command on node: top -bn1
[2024-01-15 10:23:48] INFO  Command completed successfully

Log Controls:

• Follow: Auto-scroll as new logs arrive
• Filter: Search within logs
• Download: Export logs as a file
• Time Range: Filter by date and time

Node Info Tab

Details about the linked node (if linked):

• Node name and ID
• Server hostname and IP
• Node status (online/offline)
• Last heartbeat time
• Node software version

Configuration Tab

View and edit agent configuration:

• Agent name and description
• System prompt and behavior
• Squad assignment
• Capability settings

Creating and Linking an Agent

Agents are cloud-based AI entities that you create in the dashboard and then link to deployed nodes.

Step 1: Create the Agent

1. Navigate to the Agents page
2. Click "Create Agent"
3. Configure the agent:
   • Name: Descriptive identifier
   • Squad: Select parent squad
   • Description: Agent's purpose and responsibilities
   • System Prompt: AI behavior instructions (optional)
4. Click "Create Agent"

The agent is now created but not yet linked to a node.

Step 2: Deploy a Node (if needed)

If you don't have a node deployed yet:

1. Navigate to Nodes page
2. Click "Create Node"
3. Get the Node ID and Token
4. On your server, install the CLI and deploy:

   curl -fsSL https://install.opssquad.ai/install.sh | bash
   opssquad node install --node-id="your-id" --token="your-token"

5. The node will appear online in your dashboard

Step 3: Link Agent to Node

1. Go back to the Agents page
2. Click on your agent
3. Click "Link to Node"
4. Select an online node from the dropdown
5. Confirm the linking

The agent is now active and can execute commands through the linked node!

Agent Configuration

Agent Behavior

Configure how the agent operates:

System Prompt

The system prompt defines the agent's personality and focus:

You are a database monitoring agent. Your primary focus is monitoring
PostgreSQL performance, analyzing slow queries, and detecting connection
issues. When investigating problems, always check query performance first.

Capabilities

Enable or disable specific capabilities:

• System Diagnostics - CPU, memory, disk analysis
• Log Analysis - Search and analyze log files
• Service Management - Start, stop, restart services
• Network Diagnostics - Connectivity and traffic analysis
• Custom Scripts - Execute user-defined diagnostic scripts

Troubleshooting Agents

Agent Not Executing Commands

If an agent isn't executing commands:

1. Check if agent is linked - Go to agent details and verify it's linked to a node
2. Check node status - Verify the linked node is online
3. Check node connectivity - Ensure the node can reach socket.opssquad.ai:9000
4. Review logs - Check the Logs tab for error messages

Common causes:

• Agent is not linked to any node
• Linked node is offline
• Network connectivity issues between node and platform
• Node authentication token expired

Agent Shows as Unlinked

If an agent appears as Unlinked when it should be linked:

1. Click on the agent
2. Click "Link to Node"
3. Select an online node from the dropdown
4. Confirm the linking

Linked Node is Offline

If your agent's linked node shows as offline:

1. SSH into the server running the node
2. Check node status locally:

   opssquad node status
   opssquad node logs

3. Restart the node if needed:

   opssquad node restart

4. Check network connectivity:

   opssquad node validate

Need to Reassign Agent to Different Node

1. Go to agent details
2. Click "Unlink Node"
3. Click "Link to Node"
4. Select a different online node
5. Confirm the linking

Best Practices

Naming Conventions

Use descriptive names that include:

• Agent purpose (Database Monitor, Web Server Guardian)
• Environment (Production, Staging, Development)
• Specialization (PostgreSQL Agent, Nginx Monitor)

Examples:

• Production Database Monitor
• Staging API Agent
• Dev Security Audit Agent

Squad Organization

• Group agents by environment (Production Squad, Staging Squad)
• Or by function (DevOps Squad, Security Squad)
• Create specialized squads for different teams or purposes

Node Linking

• Link agents to nodes that match their purpose
• One agent links to one node at a time
• Unlink and relink to reassign agents as infrastructure changes
• Monitor node status to ensure agents can execute commands

Security

• Review command execution logs regularly
• Use unique tokens per node
• Rotate node tokens periodically
• Configure auto-approval carefully for sensitive commands
• Review agent activity logs for security audits

Next Steps

• Managing Squads - Learn how to organize agents into squads.
• Chat Interface - Interact with your agents using natural language.
• Billing - Understand credit consumption and billing.