Agent migration checklist

As part of Relativity’s architecture modernization, agents in RelativityOne were migrated in Q1 2022 to run on RelativityOne’s modernized compute platform. This change makes agents more resilient and performant, but requires agents to meet requirements as described in this topic. If you have developed agents with unsupported behaviors, you should update those agents as soon as possible given that these are not supported behaviors. If you have developed agents with obsolete agent behaviors for RelativityOne, you should evaluate those agents’ use cases, and plan to migrate the functionality to use supported approaches instead.

  • The Local Debugger is a Visual Studio extension for locally debugging agents to aid faster development. It helps to validate that agents work outside of the agent server environment during migration to Kubernetes. For more information, see Local Debugger.
  • In the RelativityOne, the log extractor provides access to error logs for custom applications. It provides an easy way to obtain logs for troubleshooting your applications. We recommend using the log extractor to get visibility into your agent processes. For more information, see Log Extractor on the RelativityOne documentation site.

Unsupported Agent Behaviors

Even though non-standard behaviors are possible in the current infrastructure, these behaviors will not be supported once agents are migrated to RelativityOne’s modernized compute platform. You should refactor your agents so that they do not exhibit any of the behaviors listed in the table below.

Non-Standard Behavior


Creating App Domains

Creating your own App Domain in RelativityOne will exhibit undesired behavior. Agents should be redesigned to avoid the use of App Domains.

Threads and thread pools may be created; we will provide guidance on how to leverage cloud-native scalability in future documentation

Preventing AgentBase Execute from returning

Currently, each agent is a long-lived thread of work. This design worked correctly on VMs that are similarly long-lived, but isn't appropriate for RelativityOne’s modernized architecture. In the new infrastructure, we want agents to only be running while there is work to do.

Your agent must return from the Execute method once all work or tasks are completed. Using a loop to process a queue of work is acceptable if the loop and the Execute method are exited once no more work remains.

Exposing HTTP endpoints

Agents have historically had few limitations into what they could do, resulting in some agents self-hosting APIs in a separate process or thread in order to provide status on the agent’s work. Moving forward in RelativityOne, though, all access will be tightly controlled, meaning the agent and any threads or spawned processes will be inaccessible from the outside.

If you need an API, you should create a Kepler service and use the database or another shared data store to communicate information between your agent and your Kepler service.

Assuming statefulness

Agents may be preempted and restarted at any time. In practice, this happens infrequently, but you will need to ensure that your agent is resilient to these operations and that these operations will not result in any data integrity issues. Your agent must be able to recover from preemption in part of its workflow and process the remaining work correctly.

Agents must also be architected such that they do not rely on long-lived information stored in-memory or in scratch disk. Agents should use cloud storage solutions for anything but small, short-lived scratch space, as heavy usage of scratch space may cause performance issues.

Referencing files via non-FQDN paths

When interacting with files, referencing files via non-FQDN paths such as \\files\t02\.... will cease to function once agents are migrated to RelativityOne Compute.

All interactions with files on the fileshare must use fully qualified domain names (FQDN) paths to correctly locate the file.

Obsolete Agent Behavior in RelativityOne

Some functionality will be replaced or deprecated in the RelativityOne cloud-native infrastructure. This functionality will remain valid in Relativity Server, and will continue to exist in RelativityOne until new paradigms are available (scheduled for Quarter 4 2021). If your agents use any of the functionality described in the table below, you should expect to make changes to your agents to keep them operational in RelativityOne. We will provide specific guidance on how to achieve the same agent functionality in future documentation.

Obsolete Agent Functionality


Querying or modifying the Agent table

Historically, the Agent has provided metadata for every instance of a running Agent. Moving forward in RelativityOne, though, scalability will happen behind the scenes, and the Agent table will no longer be available. This means that agent IDs are no longer fixed as part of the context and that you cannot rely on any persistent metadata for a particular running instance of an agent.

If you require persistence between multiple stages of your business logic, you should create queues to manage the tasks.

Spinning off additional threads that outlive Execute

Agent processes may be destroyed once the Execute method of an Agent returns. Therefore, any threads outliving Execute will likely be interrupted before they can finish. Spinning off additional threads will work correctly, but they must rejoin the main thread before Execute returns. If you use threads, you must carefully manage their lifecycle.

If you are using threads in order to speed up performance, this may later be addressed through the native scaling provided by RelativityOne’s modernized infrastructure, but we recommend first migrating before optimizing on its scaling capabilities.

Use Resource Servers

Resource Servers are a Server-only concept that requires a Relativity Admin to manage where Agents run on in-tenant infrastructure. This concept will not exist in the modernized infrastructure.

Agents should be able to run outside of the concept of Resource Servers.

Use Resource Pools

Resource Pools are a Server-only concept that requires a Relativity Admin to manage how and where Agents run on in-tenant infrastructure. This concept will not exist in the modernized RelativityOne infrastructure. Agents should be able to run outside of the concept of Resource Pools.

If you must support both in-tenant and RelOne version of Relativity, you may have branching logic based on whether or not a Resource Pool is returned.

Have a run interval of less than 60 minutes

Agents leveraging the run interval to pick up work should be performing background jobs that do not require a rapid response; thus, we are updating the minimum run interval from 5 seconds to 1 minute interval if you have a Workload Discovery endpoint. Otherwise, the minimum interval is 60 minutes. See Get started with scaling.

If your agent can't wait for up to a one minute delay before starting to process work, your code should leverage the Agent Status Manager API. Calling this endpoint will immediately kick off your agent so that no delay is required. See Execution patterns for migrated agents.