Skip to main contentAgents are the core execution units of 2501: autonomous AI systems that perform operational tasks on your infrastructure. Each agent combines LLM-powered intelligence with programmatic access to your systems, enabling complex workflows, issue diagnosis, and infrastructure management through natural language instructions.
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
This dual-engine architecture separates execution from planning, improving accuracy and safety. Learn more in Engines.
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
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 management
Remote 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 Accounts 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 Accounts 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).
Troubleshooting
Agent Not Completing Tasks: Check context window usage and archive tasks if near limits. Verify credentials are correctly assigned and accessible. Review operational rules for conflicts. Ensure specialty provides adequate guidance. Consider upgrading engines for complex tasks.
Execution Errors: Validate remote access credentials for swarm execution. Check blacklist for inadvertently blocked commands. Review task history for failure patterns. Verify target system accessibility and permissions.
Unexpected Behavior: Review the agent’s specialty for conflicting guidance. Check for overly strict operational rules. Examine task history to understand decision-making. Test with simplified tasks to isolate the issue. Consider adjusting engine assignments.
For additional support, refer to the Prompting Guide for techniques to improve agent task understanding and execution. 
