---
title: "Agents"
slug: "agents"
abstract: ""
---
# Agents

Agents are responsible for processing work within the Cortex Processing Engine (Processing Engine). Each agent represents a thread, and can be configured to run in parallel. The Processing Engine ships with several default agents, including a task agent polls the Cortex Processing Engine Tasks database at regular intervals and calls workers to perform those tasks.

As a developer, you can:

- Configure existing agents - for example, you can change how the task agent scales.
- Create a custom agent.

## Agent base classes

All agents implement `IAgent`. In addition, there are two base classes available:

- `BaseAgent` provides basic functionality and services. Agents that inherit `BaseAgent` do not run at regular intervals, but might start when the engine starts and sleep until an event occurs.
- `RecurringAgent` inherits `BaseAgent`. Agents that inherit `RecurringAgent` run at regular, configurable intervals. Most default agents inherit `RecurringAgent`.

## Agent configuration options

Agents are configured registered in the <engine-root>\\\\App_Data\\\\Config\\\\Sitecore/Processing/sc.Processing.Engine.Services.xml configuration file. There are two ways to configure an agent:

- Simple configuration registers a single agent.
- Parallel agents configuration allows you to register multiple agents manually or relative to the number of cores available.

Agents that inherit `BaseAgent` run once on startup. Agents that inherit `RecurringAgent` run at configurable intervals.

## Simple agent configuration

The following example demonstrates how to register a single task cleanup agent (`TaskCleanupAgent`). The task cleanup agent inherits `RecurringAgent` and expects a `SleepPeriod` configuration setting that determines how often the agent should run:

```xml
<Settings>
  <Sitecore>
    <Processing>
      <Services>
        <TaskCleanupAgent>
            <Type>Sitecore.Processing.Engine.Agents.TaskCleanupAgent, Sitecore.Processing.Engine</Type>
            <As>Sitecore.Processing.Engine.Abstractions.IAgent, Sitecore.Processing.Engine.Abstractions</As>
            <LifeTime>Transient</LifeTime>
            <Options>
                <!-- The period which the agent sleeps before running again. -->
                <SleepPeriod>0.`00:00`:14.000</SleepPeriod>
            </Options>
        </TaskCleanupAgent>
      </Services>
    </Processing>
  </Sitecore>
</Settings>
```
> [!note]
> An agent that does not inherit `RecurringAgent` does not require the `SleepPeriod` setting.

## Parallel agents configuration

The following example demonstrates how to register a multiple agents, using `TaskAgent` as an example:

```xml
<Settings>
  <Sitecore>
    <Processing>
      <Services>
        <TaskAgents>  <!-- Name of agent -->
            <Type>Sitecore.Processing.Engine.Agents.ParallelAgentsConfiguration, Sitecore.Processing.Engine</Type>
            <As>Sitecore.XConnect.DependencyInjection.Abstractions.IXConnectServicesConfiguration, Sitecore.XConnect.DependencyInjection</As>
            <LifeTime>Transient</LifeTime>
            <Options>
            <!-- The fixed number of agents to register. These are in addition to the agents registered by the AgentCoreRatio option. -->
            <AgentFixedCount>0</AgentFixedCount>
            <!-- The ratio of the count of agents to CPU cores to register. These are in addition to the agents registered by the AgentFixedCount option. -->
            <AgentCoreRatio>0.75</AgentCoreRatio>
            <!-- The configuration for the agents to register. -->
            <AgentConfiguration>
                <Type>Sitecore.Processing.Engine.Agents.TaskAgent, Sitecore.Processing.Engine</Type>
                <As>Sitecore.Processing.Engine.Abstractions.IAgent, Sitecore.Processing.Engine.Abstractions</As>
                <LifeTime>Transient</LifeTime>
                <Options>
                <!-- The period which the agent sleeps before running again. -->
                <SleepPeriod>0.`00:00`:14.000</SleepPeriod>
                <!-- The name of the machine on which the agent is running. -->
                <MachineName>${MachineName}</MachineName>
                </Options>
            </AgentConfiguration>
            </Options>
        </TaskAgents>
      </Services>
    </Processing>
  </Sitecore>
</Settings>
```

The following settings are specific to `ParallelAgentsConfiguration`:

| Setting | Description |
| --- | --- |
| `AgentFixedCount` | Defines an absolute number of agents to register. Fixed agents are registered in addition to agents registered by `AgentCoreRatio`. |
| `AgentCoreRatio` | Defines the number of agents to register as a ratio of `AgentCoreRatio` to available cores on the host machine. In the context of an 8 core machine:<br><br><ul><li>If the ratio is 1, 8 agents are registered.</li><li>If the ratio is 0.5, 4 agents are registered.</li><li>If the ratio is 2, 16 agents are registered.</li></ul><br><br>If you scale up the host machine by adding more cores, the number of agents will scale automatically. Agents are registered in addition to agents registered by `AgentFixedCount`. |