What is an Agent?
A 2501 agent is an AI-powered operator capable of understanding context by analyzing tasks and interpreting system states, planning execution by breaking down complex operations into logical steps, taking action through commands and file modifications, adapting dynamically based on outputs and errors, and operating autonomously to complete multi-step tasks without constant intervention. Unlike traditional automation scripts, agents reason about their environment and make informed decisions rather than following rigid procedural logic.
Agent Architecture
Engine Pair
Every agent uses two LLMs in tandem:- Main Engine: Handles direct task execution, file manipulation, and command execution
- Secondary Engine: Manages orchestration, planning, validation, and oversight
Specialty Configuration
Agents are assigned a Specialty that provides domain-specific guidance and workflows, ranging from general-purpose (SYSOPS) to highly specialized configurations like TERRAFORM_SPECIALIST or AWS_CLI_EXPERT.
Operational Constraints
Agents operate within boundaries defined by Operational Rules (organization-wide mandatory procedures), Blacklists (prohibited commands), and Credentials (secure access to systems).Memory and Context
Agents maintain task history within their context window, allowing them to reference previous operations, build on prior work, and maintain continuity across related tasks. When context limits are approached, tasks can be archived to clear memory while preserving agent configuration.Execution Modes: Investigate vs Remediate
Agents support two execution modes that control what actions they can take:- Remediate (default): The agent diagnoses issues and applies fixes — commands, file changes, service restarts, etc.
- Investigate: Read-only analysis. The agent diagnoses and reports findings without making any changes to the target system.
| Level | How | Scope |
|---|---|---|
| Ticket | Tag with @2501:investigate or @2501:remediate in the ticket body or comments | Single ticket/job — defaults to remediate if no tag is present |
| Specialty | Pin to investigate-only in the specialty settings | All agents using that specialty — acts as a ceiling that overrides ticket requests |
@2501:investigation and @2501:remediation also work.
The specialty constraint is a ceiling: if a specialty is pinned to investigate_only, any agent using it will always run in read-only mode, even if the ticket is tagged @2501:remediate. When this happens, the resolution is flagged as partial rather than a failure. This lets you safely deploy large fleets of agents and selectively enable remediation by changing a single setting on the specialty.
Tickets and jobs running in Investigate mode show a visible Investigate badge in the Command Center.
Local vs Remote Execution
Local Execution
The agent runs directly on the machine where the 2501 CLI is installed. This provides direct filesystem and process access, executes commands with the CLI user’s permissions, and requires CLI installation on the target machine. Use cases: Developer workflows, local testing, workstation automation, single-server managementRemote Execution (Agent Swarm)
The agent runs in the 2501 agent swarm infrastructure and connects to target machines remotely. This executes tasks without installing the CLI on targets, centralizes agent management, supports fleet operations across multiple machines, requires appropriate remote access credentials, and enables agents to operate where CLI installation isn’t feasible. Use cases: Production fleet management, cloud infrastructure operations, systems where agent installation isn’t permitted, centralized IT automation The execution mode is transparent to the agent—it uses the same capabilities regardless of where it runs.
Agent Lifecycle
Creation
Agents are created through the Command Center UI (full-featured) or CLI (streamlined for quick deployment). During creation, configure agent name, assign to a host, select main and secondary engines, assign specialty, configure credentials, and choose execution mode.
Configuration
After creation, agents can be modified to change engine assignments, update specialty configurations, add or remove credentials, and adjust operational constraints.Task Execution
Agents receive tasks through natural language instructions. The secondary engine analyzes the request and gathers context. It creates an execution plan, then the main engine executes actions and validates results. The agent adapts as needed and reports completion or escalates issues.Memory Management
As agents work, their context window fills with task history. Manage memory by archiving completed tasks individually, clearing all memory for a fresh start, or selectively archiving unrelated tasks while preserving relevant context.Modification and Deletion
Agents can be edited or removed through the Command Center UI (full management) or CLI (limited management for active agents).
Agent Organization
Organization Scoping
Agents belong to specific organizations, with available specialties, operational rules, blacklisted commands, and accessible credentials. This scoping enables different teams or environments to maintain separate operational standards while sharing infrastructure.Agent Naming
Choose agent names that indicate purpose or responsibility (e.g.,aws-prod-manager, db-backup-agent), target environment (e.g., staging-deployer, prod-monitor), or specialty domain (e.g., terraform-provisioner, k8s-operator).