Agent Manager API

In Relativity, agents are process managers and workers that run in the background to complete jobs scheduled in your environment. For general information, see Agents on the Relativity Documentation site.

The Agent Manager API exposes multiple operations that you can use to programmatically manage agents in your Relativity environment. It includes the following features:

Sample use cases for the Agent Manager service include:

You can also use the Agent Manager service through the REST API. For more information, see Agent Manager service.

Note: To implement your own custom agents, use the Agents API. For more information, see Build agents.

This page contains the following information:

Fundamentals for managing agents

Review the following information to learn about the methods, classes, and other entities used by the Agent Manager service.

Methods

In the Relativity Services API, the Relativity.Services.Interfaces.Agent namespace contains the IAgentManager interface that exposes the following methods:

Classes and enumerations

The Relativity.Services.Interfaces.Agent.Models namespace contains the following classes and enumerations used by the Agent Manager API:

Guidelines for the Agent Manager service

Review the following guidelines for working with the Agent Manager service.

Admin-level context

The methods on the Agent Manager API require that you pass an integer representing a workspace ID. You must pass -1 to indicate the admin-level context. This value is required as an argument for all methods on the Agent Manager API.

Validation and compatibility checks

Relativity has minimum and maximum limits on the number of agents in an environment, server, or resource pool. These limits vary by agent type. For general information, see Managing and setting Relativity agent quantity limitations on the RelativityOne Documentation site.

You can use the validation methods on the Agent Manager service to verify that a create, update, or delete operation doesn't violate these limits. Validation checks have the following behavior:

For more information, see Validate a create, update, or delete operation.

Additionally, an agent server may host only specific agent types. The Agent Manager service provides the GetAvailableAgentServersAsync() method that you can use to retrieve a list of servers compatible with an agent type. See Retrieve servers compatible with a specific agent type.

Sample workflow for adding agents

You can use the following sample workflow to add agents to your Relativity environment.

  1. Retrieve a list of agent types available in a Relativity environment. See Retrieve a list of agent types.
  2. Retrieve a list of agent servers that support the agent type to add. You can only create some types of agent on specific agent server types. See Retrieve servers compatible with a specific agent type
  3. Perform a validation check to verify that you can add the agent without breaking any limits set for it. Call the ValidateCreateInstanceLimitAsync() method before attempting to add the new agent. See Validate a create operation.
  4. Review the response from the validation check:

Monitor enabled agents

The following code sample illustrates how to monitor enabled agents. You call the AgentRestart() method by passing an instance of the IAgentManager proxy, and the Artifact ID of the agent that you want to monitor. For information about instantiating the proxy, see Connect to the Services API and Relativity API Helpers.

public async Task AgentRestart(Relativity.Services.Interfaces.Agent.IAgentManager manager, int agentArtifactID)
{
    //Read in agent.
    Relativity.Services.Interfaces.Agent.Models.AgentResponse agentResponse = await manager.ReadAsync(-1, agentArtifactID);
 
    if (!agentResponse.Enabled)
    {
        Relativity.Services.Interfaces.Agent.Models.AgentRequest enabledAgentRequest = new AgentRequest(agentResponse);
 
        enabledAgentRequest.Enabled = true;
 
        await manager.UpdateAsync(-1, agentArtifactID, enabledAgentRequest);
    }
}

Retrieve a list of agent types

Relativity supports a variety of agent types used for productions, OCR, Analytics, and other purposes. In addition, you can also implement custom agent types to meet the needs of your users. For more information, see Agents on the RelativityOne Documentation site.

The following code sample illustrates how to call the GetAgentTypesAsync() method by passing -1 to indicate the admin-level context.

Note: The AgentTypeResponse object contains a Guids property, which contains the GUIDs associated with the agent type. This information isn't available through REST.

public static async Task GetAgentTypes_Async()
{
    int workspaceId = -1;

    using (Services.Interfaces.Agent.IAgentManager agentManager = serviceFactory.CreateProxy<Services.Interfaces.Agent.IAgentManager>())
    {
        try
        {
            List<AgentTypeResponse> response = await agentManager.GetAgentTypesAsync(workspaceId);
            foreach (AgentTypeResponse agentType in response)
            {
                string info = string.Format("Read agent type {0} with Artifact ID {1}", agentType.Name, agentType.ArtifactID);
                Console.Write(info);
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        }
    }
}

Retrieve a list of agent servers

You can retrieve a list of all agent servers in a Relativity environment. However, if you want information about servers where you can add a specific agent type, see Retrieve servers compatible with a specific agent type.

The following code sample illustrates how to call the GetAgentServersAsync() method by passing -1 to indicate the admin-level context.

public static async Task GetAgentServers_Async()
{
    int workspaceId = -1;

    using (Services.Interfaces.Agent.IAgentManager agentManager = serviceFactory.CreateProxy<Services.Interfaces.Agent.IAgentManager>())
    {
        try
        {
            List<AgentServerResponse> response = await agentManager.GetAgentServersAsync(workspaceId);
            foreach (AgentServerResponse agentServer in response)
            {
                string info = string.Format("Read agent server {0} with Artifact ID {1}", agentServer.Name, agentServer.ArtifactID);
                Console.Write(info);
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        }
    }
}

Retrieve servers compatible with a specific agent type

You can retrieve a list of servers compatible with a specific agent type that you want to add to Relativity. However, if you want a list of all agent servers in your environment, see Retrieve a list of agent servers.

The following code sample illustrates how to call the GetAvailableAgentServersAsync() method by passing -1 to indicate the admin-level context.

public static async Task GetAvailableAgentServers_Async()
{
    int workspaceId = -1;
    int agentTypeId = 1015253;

    using (Services.Interfaces.Agent.IAgentManager agentManager = serviceFactory.CreateProxy<Services.Interfaces.Agent.IAgentManager>())
    {
        try
        {
            List<AgentServerResponse> response = await agentManager.GetAgentServersAsync(workspaceId, agentTypeId);
            foreach (AgentServerResponse agentServer in response)
            {
                string info = string.Format("Read agent server {0} with Artifact ID {1}", agentServer.Name, agentServer.ArtifactID);
                Console.Write(info);
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        }
    }
}

Create an agent

Before creating an agent, you need to identify the agent type and a compatible server, and perform a validation check. For more information, see Sample workflow for adding agents.

The following code sample illustrates how to use the CreateAsync() method to add a single agent. It passes -1 to indicate the admin-level context, and the Artifact ID of the agent type and the server.

Note: The CreateAsync() method is overloaded, so you can also use it to add multiple agents in a single call by passing integer specifying the number of agents to create.

public static async Task Create_Async()
{
    int workspaceId = -1;
    int agentTypeId = 1015253;
    int agentServerId = 1016892;

    AgentRequest request = new AgentRequest
    {
        Enabled = true,
        Interval = 10,
        Keywords = "keywords",
        Notes = "notes",
        LoggingLevel = 1,
        AgentType = new Securable<ObjectIdentifier>(new ObjectIdentifier { ArtifactID = agentTypeId }),
        AgentServer = new Securable<ObjectIdentifier>(new ObjectIdentifier { ArtifactID = agentServerId })
    };

    using (Services.Interfaces.Agent.IAgentManager agentManager = serviceFactory.CreateProxy<Services.Interfaces.Agent.IAgentManager>())
    {
        try
        {
            int newAgentArtifactId = await agentManager.CreateAsync(workspaceId, request);
            string info = string.Format("Created agent with Artifact ID {0}", newAgentArtifactId);
            Console.Write(info);
        }
        catch (Exception ex)
        {
            Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        }
    }
}

Retrieve metadata for an agent

Use the overloaded ReadAsync() method to retrieve basic metadata for an agent or extended metadata, which includes information about the operations that you have permissions to perform on this agent.

The following code sample illustrates how to call the ReadAsync() method by passing -1 to indicate the admin-level context, and the Artifact ID of the agent. If you want to return additional information, use the overloaded method by passing Boolean values set to true for additional metadata and permissions.

public static async Task Read_Async()
{
    int workspaceId = -1;
    int agentArtifactId = 1016911;

    using (Services.Interfaces.Agent.IAgentManager agentManager = serviceFactory.CreateProxy<Services.Interfaces.Agent.IAgentManager>())
    {
        try
        {
            AgentResponse response = await agentManager.ReadAsync(workspaceId, agentArtifactId);
            string info = string.Format("Read agent {0} with Artifact ID {1}", response.Name, response.ArtifactID);
            Console.Write(info);
        }
        catch (Exception ex)
        {
            Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        }
    }
}

Update the properties of an agent

Use the UpdateAsync() method to modify the properties of an agent. The following code samples illustrates how to call this method by passing -1 to indicate the admin-level context, the Artifact ID of the agent, and an AgentRequest object.

Additionally, you can also restrict the update of an agent to the date that it was last modified by passing the value of LastModifiedOn property as an argument to the overloaded UpdateAsync() method.

public static async Task Update_Async()
{
    int workspaceId = -1;
    int agentArtifactId = 1016911;
    int agentTypeId = 1015253;
    int agentServerId = 1016892;

    AgentRequest request = new AgentRequest
    {
        Enabled = true,
        Interval = 5,
        Keywords = "updated keywords",
        Notes = "updated notes",
        LoggingLevel = 5,
        AgentType = new Securable<ObjectIdentifier>(new ObjectIdentifier { ArtifactID = agentTypeId }),
        AgentServer = new Securable<ObjectIdentifier>(new ObjectIdentifier { ArtifactID = agentServerId })
    };

    using (Services.Interfaces.Agent.IAgentManager agentManager = serviceFactory.CreateProxy<Services.Interfaces.Agent.IAgentManager>())
    {
        try
        {
            await agentManager.UpdateAsync(workspaceId, agentArtifactId, request);
        }
        catch (Exception ex)
        {
            Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        }
    }
}

Delete an agent

You can programmatically remove an agent from Relativity after it has finished executing, or you can remove it immediately by forcefully deleting it. When you forcefully delete an agent, the system doesn't wait for it to finish executing. In general, use a force delete when an agent has become unresponsive.

Pass the Artifact IDs of the workspace and agent to the overloaded DeleteAsync() when you want to remove the agent after it finishes executing as illustrated in the following code sample. To remove the agent immediately, pass the Artifact IDs of the workspace and agent, and a Boolean value of true to the method.

public static async Task Delete_Async()
{
    int workspaceId = -1;
    int agentArtifactId = 1016911;

    using (Services.Interfaces.Agent.IAgentManager agentManager = serviceFactory.CreateProxy<Services.Interfaces.Agent.IAgentManager>())
    {
        try
        {
            await agentManager.DeleteAsync(workspaceId, agentArtifactId);
        }
        catch (Exception ex)
        {
            Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        }
    }
}

Validate a create, update, or delete operation

Before you attempt to add, update, or delete an agent, you can perform a check to verify the success of the operation. For general information, see Validation and compatibility checks.

Review the following information about agent validation:

Validate a create operation

Use the ValidateCreateInstanceLimitAsync() method to check whether the addition of a new agent exceeds the maximum number allowed.

public static async Task ValidateCreateInstanceLimit_Async()
{
    int workspaceId = -1;
    int agentTypeId = 1015253;
    int agentServerId = 1016892;
    int agentsToCreate = 2;

    AgentRequest request = new AgentRequest
    {
        Enabled = true,
        Interval = 10,
        Keywords = "keywords",
        Notes = "notes",
        LoggingLevel = 1,
        AgentType = new Securable<ObjectIdentifier>(new ObjectIdentifier { ArtifactID = agentTypeId }),
        AgentServer = new Securable<ObjectIdentifier>(new ObjectIdentifier { ArtifactID = agentServerId })
    };

    using (Services.Interfaces.Agent.IAgentManager agentManager = serviceFactory.CreateProxy<Services.Interfaces.Agent.IAgentManager>())
    {
        try
        {
            List<AgentInstanceLimitResult> result = await agentManager.ValidateCreateInstanceLimitAsync(workspaceId, request, agentsToCreate);
            foreach (AgentInstanceLimitResult instanceLimit in result)
            {
                string info = string.Format("Create limit broken: {0}", instanceLimit.Limit.ToString());
                Console.Write(info);
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        }
    }
}

Validate an update operation

Use the ValidateUpdateInstanceLimitAsync() method to check whether the updating the number of agents exceeds the maximum number allowed.

public static async Task ValidateUpdateInstanceLimit_Async()
{
    int workspaceId = -1;
    int agentArtifactId = 1016911;
    int agentTypeId = 1015253;
    int agentServerId = 1016892;

    AgentRequest request = new AgentRequest
    {
        Enabled = true,
        Interval = 5,
        Keywords = "updated keywords",
        Notes = "updated notes",
        LoggingLevel = 5,
        AgentType = new Securable<ObjectIdentifier>(new ObjectIdentifier { ArtifactID = agentTypeId }),
        AgentServer = new Securable<ObjectIdentifier>(new ObjectIdentifier { ArtifactID = agentServerId })
    };

    using (Services.Interfaces.Agent.IAgentManager agentManager = serviceFactory.CreateProxy<Services.Interfaces.Agent.IAgentManager>())
    {
        try
        {
            List<AgentInstanceLimitResult> result = await agentManager.ValidateUpdateInstanceLimitAsync(workspaceId, agentArtifactId, request);
            foreach (AgentInstanceLimitResult instanceLimit in result)
            {
                string info = string.Format("Update limit broken: {0}", instanceLimit.Limit.ToString());
                Console.Write(info);
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        }
    }
}

Validate a delete operation

Use the ValidateDeleteInstanceLimitAsync method to check whether the removal of an agent violates the minimum number of agents required.

public static async Task ValidateDeleteInstanceLimit_Async()
{
    int workspaceId = -1;
    int agentArtifactId = 1016911;

    using (Services.Interfaces.Agent.IAgentManager agentManager = serviceFactory.CreateProxy<Services.Interfaces.Agent.IAgentManager>())
    {
        try
        {
            List<AgentInstanceLimitResult> result = await agentManager.ValidateDeleteInstanceLimitAsync(workspaceId, agentArtifactId);
            foreach (AgentInstanceLimitResult instanceLimit in result)
            {
                string info = string.Format("Delete limit broken: {0}", instanceLimit.Limit.ToString());
                Console.Write(info);
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        }
    }
}

Failed validation responses

When a validation check fails, the response varies depending on the reason for the failure. The AgentInstanceLimit enumeration contains constants that identify the reason for a failed validation check:

For more information, see the AgentInstanceLimit enumeration in the Relativity.Services.Interfaces.Agent.Models namespace in the Relativity API reference.

Community Updates

Aero Developer FAQ Evolving the Platform Most recent release notes
Learn more Learn more Learn more

Additional Resources

   
Access Third-Party Tools with GitHub     Create .NET Apps Faster with NuGet
Visit github     visit nuget