> ## Documentation Index
> Fetch the complete documentation index at: https://docs.2501.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> The LLMs autonomously browsing your systems

Agents 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.

The Agents list shows each agent's Host or Central and its plugins under its name. The first plugin appears by name, with a count of additional plugins. Hover to see them all. The list also shows the status, specialty, main and secondary engines, and creation and update dates.

Filter the list by the Hosts' technologies, applications or tags. Click a row to open the agent.

## Agent Architecture

### Engine Pair

Every agent uses two LLMs in tandem:

* **Main Engine**: Handles direct task execution, file manipulation, and command execution
* **Secondary Engine**: Checks the work - validating each proposed action against the host's rules and the incident, and reviewing interactive commands

This dual-engine architecture separates doing from checking, improving accuracy and safety. The agent that acts is not the one that decides whether the action is allowed. Learn more in [Engines](https://docs.2501.ai/0.20/understand/engine-agents.md).

### Specialty Configuration

Agents are assigned a [Specialty](https://docs.2501.ai/0.20/configure/specialties.md) 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](https://docs.2501.ai/0.20/configure/operational-rules.md) (organization-wide mandatory procedures), [Blacklists](https://docs.2501.ai/0.20/configure/blacklist.md) (prohibited commands), and [Credentials](https://docs.2501.ai/0.20/configure/credentials.md) (secure access to systems).

### Credential Access Control

Each agent has an explicit **credential allowlist** - a list of credentials it may reference by name during task execution. Configure the list from the agent create or edit form. Only credentials on the allowlist are advertised to the agent; secret values are never exposed. Named credential placeholders in commands (e.g. `{{secret:my-api-key}}`) resolve only when the referenced credential appears on the agent's allowlist. An empty allowlist means no named credentials are available to the agent.

### 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: Plan and Auto

An execution mode decides if a person approves the changes of an agent before 2501 makes them. Each agent is in one of two modes:

* **Auto**: The agent diagnoses issues and applies fixes without approval: commands, file changes, service restarts, etc. Operational rules, blacklists and access restrictions still apply.
* **Plan**: The agent only reads. Its tasks diagnose and report, and every command that would change the system is blocked. When a change is needed, the job posts a **plan** of the changes, and 2501 makes them only after a person approves it.

The mode is decided at three levels:

| Level | How | Scope |
| - | - | - |
| **Organization** | An Admin sets Plan or Auto for the [organization](https://docs.2501.ai/0.20/core-concepts/organizations.md). A new organization starts in Plan. | Every agent whose specialty has no override |
| **Specialty** | An Admin overrides the organization with Plan or Auto in the [specialty](https://docs.2501.ai/0.20/configure/specialties.md) settings | All agents using that specialty |
| **Job** | A ticket command `@2501:plan` or `@2501:auto`, the New Job form, the job page, or a [job schedule](https://docs.2501.ai/0.20/core-concepts/job-schedules.md) | All agents of that job |

The mode of a task depends on the mode of the job and the mode of its agent:

| Mode of the job | Agent in Auto | Agent in Plan |
| - | - | - |
| None (default) | Makes its changes at once | Only reads. Its changes wait in a plan |
| Plan (`@2501:plan`) | Only reads | Only reads |
| Auto (`@2501:auto`) | Makes its changes at once | Makes its changes at once, with no approval |

If several mode commands appear in the description and comments, the last one that counts wins, and a later comment without one does not clear it. `@2501:auto` counts only when an Admin allows it for the organization. Otherwise 2501 says so in the ticket and ignores the command. The commands of earlier versions still work: `@2501:investigate` is `@2501:plan`, and `@2501:remediate` is `@2501:auto`. A new mode takes effect at the next task boundary: the running task keeps its mode, including after recovery, and pending tasks are canceled and replanned.

A job stops after its first turn that reads through an agent in Plan. When a change is still needed, the job posts a plan with every change that is left, in the ticket and on the job page, and waits. A person approves it with `@2501:approve-plan` or **Approve plan**, or asks for changes with a `@2501` comment or **Request changes**. See [Jobs: Plans](https://docs.2501.ai/0.20/core-concepts/jobs.md#plans).

The mode belongs to the agent, not to the host: a host with an agent in Plan and an agent in Auto can change through the agent in Auto. To protect a host, give all of its agents a specialty in Plan.

A task that you create outside a job takes the mode of its agent. The New Task form shows that mode, and whether the specialty or the organization sets it. To change it, change the mode of the specialty.

In the Command Center, a read-only task shows a **Read-only** badge, and a job whose mode was forced shows a **Plan** or **Auto** badge in the jobs list. In the v1 API, a read-only task has `read_only: true`, and keeps the deprecated `execution_mode: "investigate"`.

## Agent Lifecycle

### Creation

Agents are created in Command Center or through the [API](https://docs.2501.ai/0.20/api/overview.md). In Command Center, **Agents > Create Agent** opens a dedicated creation page. Assign a [host](https://docs.2501.ai/0.20/core-concepts/hosts.md), select main and secondary engines, choose a specialty, assign plugins, and configure connection credentials.

![Create an agent](https://mintcdn.com/2501/Nw-5R3i4HUHiTxUb/images/agent_form_next.png?fit=max\&auto=format\&n=Nw-5R3i4HUHiTxUb\&q=85\&s=249f8f462d21746c9a5f0c9cb727524c)

### Configuration

After creation, select an agent from the inventory to open its detail page. From there you can change its identity and engine assignments, configure host authentication, control the credentials available during tasks, and assign plugins. The same page shows recent tasks with live statuses and provides task creation and archival actions.

### Task Execution

Agents receive tasks through natural language instructions. The main engine gathers context, plans the approach, and works through it one action at a time; the secondary engine checks each proposed action before it runs. The agent adapts as it learns from output, verifies its own change before reporting it done, 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 or using **Archive Tasks** on the agent's page to clear the agent's task memory. **Archive Tasks** archives the finished tasks of finished jobs: the tasks of a job that is still running stay in memory until the job ends. An archived task leaves the agent's memory and the task lists, but stays in its job's plan and history.

### Modification and Deletion

Agents can be edited or removed in Command Center or through the [API](https://docs.2501.ai/0.20/api/overview.md).

![Edit an agent](https://mintcdn.com/2501/Nw-5R3i4HUHiTxUb/images/agent_edit_next.png?fit=max\&auto=format\&n=Nw-5R3i4HUHiTxUb\&q=85\&s=a4f3b88f24838c60856a8bb52c8c70d6)

## Agent Organization

### Organization Scoping

Agents belong to specific [organizations](https://docs.2501.ai/0.20/core-concepts/organizations.md), 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`).

## Testing Connectivity

You can verify connectivity to the assigned host directly from the Command Center. Open the agent and use **Test connection** in the **Host authentication** section. This checks that the agent can reach its host using the configured protocol (SSH or WinRM) and credentials.

## 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 - use the **Test connection** action to quickly verify connectivity. Check the 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.