Execution patterns for agents

You can trigger the Execute() method for agents in the following ways:

  • Scheduled intervals - All agents are executed on a regularly scheduled interval. This interval represents the time between the end of one execution and the start of the next execution. The interval is configured on the application.xml file for each agent type in an application. The default value is 60 minutes, which is also the minimum allowable value without a Workload Discovery endpoint. Agents with a Workload Discovery endpoint can have an interval of 1 minute. See Scheduled intervals.
  • Note: You can't adjust the interval for an agent through the UI. The interval must be configured in the application.xml file. See Scheduled intervals.

  • On-demand - Optionally, you can trigger an agent to execute on-demand through a call to the Agent Status Manager API. This process can reduce any delay caused by waiting for the next tick of the scheduled interval, particularly when responding to a user event such as a click. The Agent Status Manager API can be accessed through .NET or REST. See On-demand.

Note: Agents will experience an average start-up delay of 30 seconds regardless of how the agent is triggered to start processing. Workflows that require an immediate response should instead use the Kepler framework for synchronous processing, instead of the agent framework which is designed for asynchronous background jobs.

Regardless of how an agent is triggered for execution, scaling is respected for agents configured to scale. For configuration and other information, see Agent Scaling Guidelines

The Relativity.HostingBridge.SDK contains this API. For compatibility and package installation instructions, see Download the SDKs and NuGet packages.

Scheduled intervals

You can modify the application.xml file to set a value for the Agent execution interval. The interval is defined in seconds with the minimum interval defaulting to 60 seconds.

Use these steps to set the execution interval:

  1. Export the application. For more information, see Exporting applications on the RelativityOne Documentation site.
  2. Edit the application.xml file in the exported RAP for each AgentType. DefaultInterval in your application. The following example illustrates an interval set to 10 minutes on an agent with a Workload Discovery endpoint, that is 600 seconds. See Get started with scaling.

Note: Agents without a Workload Discovery endpoint have a minimum interval of 60 minutes.

        <AgentTypeName>Agent Type Name</AgentTypeName>
        <!--subsequent values in the  application.xml AgentType node are not applicable for RelativityOne -->


You can trigger an agent to execute on-demand through a call to the Agent Status Manager API accessed through .NET or REST.

Agent Status Manager (.NET)

Use the StartAgentAsync() method to execute a migrated agent. Pass this method the GUID for the agent that you want to execute.

This method is available on the IAgentStatusManagerService interface in the RelativityHostingBridge.Interfaces.HostingBridgeManager.<VersionNumber>.AgentStatusManager namespace.

Note: The <VersionNumber> variable in the namespace indicates the version number of the API. The version number uses the format uppercase V and an integer version number, such as V1 or V2 in .NET.

using (var agentStatusManager = _serviceFactory.CreateProxy<IAgentStatusManagerService>())
    await agentStatusManager.StartAgentAsync(_AGENT_GUID);

Agent Status Manager (REST)

To execute a migrated agent, send a POST request with a URL in the following format:

<host>/Relativity.REST/api/relativity-hosting-bridge/{versionNumber}/agents/{Agent GUID}/agent-jobs

Set the path parameters as follows:

  • {versionNumber} to the version of the API, such as v1.
  • {Agent GUID} to the GUID for the agent that you want to execute.

The body of the request is empty.

When the agent is successfully executed, the response contains the status code of 200.