Agents

Version: 9.1

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:

RequestResponse

<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:

RequestResponse

<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: If the ratio is 1, 8 agents are registered. If the ratio is 0.5, 4 agents are registered. If the ratio is 2, 16 agents are registered. 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`.

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:

If the ratio is 1, 8 agents are registered.
If the ratio is 0.5, 4 agents are registered.
If the ratio is 2, 16 agents are registered.

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.

Do you have some feedback for us?

If you have suggestions for improving this article,