Build your first agent

This tutorial illustrates how to create a simple agent that raises the message: Hello World! The current time is: <time>. It describes how to write the source code for this agent by completing these tasks:

  • Adding references to your Visual Studio project.
  • Inheriting from the agent base class.
  • Overriding the Execute() method with your business logic and performing other key development tasks.
  • Adding the compiled .dll files for the agent to Relativity and view the messages that the agent raises.

This page contains the following information:

Before you begin

Complete the following tasks to before you begin implementing an agent:

Build an agent

Follow these steps to build a simple agent in Visual Studio:

  1. Open Visual Studio.
  2. Create a new Class Library project called Relativity.BasicSamples.

    dialog to create new class library

  3. In the Solution Explorer, right-click on the Relativity.BasicSamples project.
  4. Click Add > New Item.
  5. Create a new class in the project called BasicAgent.

    dialog to create a new class

  6. To add references to the project, right-click on References in the Solution Explorer.
  7. Click Add Reference. You need to add references to the .dll files that contain the Relativity classes and interfaces used to build your agent.

    Add Reference menu option

  8. Click Browse and select kCura.Agent.dll in your SDK installation directory. If you used the default installation path, you can find the .dll file in this folder:

    ...\Program Files\kCura Corporation\Relativity SDK\Agents\Client

  9. Click Browse and select Relativity.API.dll in your SDK installation directory. If you used the default installation path, you can find the .dll file in this folder:

    ...\Program Files\kCura Corporation\Relativity SDK\Relativity API\Lib

  10. Click Browse and select kCura.Relativity.Client.dll in your SDK installation directory. If you used the default installation path, you can find the .dll file in this folder:

    ...\Program Files\kCura Corporation\Relativity SDK\Services API\Client

  11. In the BasicAgent class, add the code to inherit from the kCura.Agent.AgentBase class.

    code for inheriting from agent base class

  12. Right-click on kCura.Agent.AgentBase, and select Implement Abstract Class from the menu.

    Implement Abstract Class menu option

  13. Override the Name property and enter the name that you want returned for the agent. Only the WinForm debugging tool uses this property to identify the agent.

    code for overriding Name property

  14. Add the following code to implement the Execute() method. You must override the Execute() method inherited from the base class. The current method raises the message: Hello World! The time is: <time>. In the Relativity UI, you set an interval that specifies when this method is called. See step 28.

    code for overriding Execute() method

  15. Add a class attribute which determines the name of the agent displayed in Relativity.

    code for setting Name attribute

  16. To create a GUID for the agent, click Tools > Create GUID.

    Create GUID menu option

  17. Select the 5. [Guid("xxxxxxx-xxxx...xxxx")], and then click Copy.

    Create GUID dialog

  18. Paste the new GUID attribute above the class name in the code. You may need to type the System.Runtime.InteropServices namespace in your code, and than paste in the GUID.

    code for setting GUID attribute

    Your code for this simple agent should be similar to the following sample. However, the GUID for the agent is unique because you generated through the Create GUID tool.

    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Text;
    using System.Threading.Tasks;
    namespace Relativity.BasicSamples
          [kCura.Agent.CustomAttributes.Name("Basic Sample Agent")]
          class BasicAgent : kCura.Agent.AgentBase
                public override void Execute()
                      String currentTimeStr = DateTime.Now.ToLongTimeString();
                      RaiseMessage("Hello World! The current time is: " + currentTimeStr, 1);
                public override string Name
                            return "Basic Agent Sample";
  19. To compile your agent source code, click Build > Build Solution. After your agent assembly builds successfully, you can upload it to Relativity.

    Note: On the Build tab for your project properties, ensure that you select Active (x64) in the Platform field. Relativity libraries require this setting.

    Build Solution menu option

  20. Open the Relativity instance used for development.

    Note: You can create a new workspace or use an existing one when you deploy your agent.

  21. Navigate to the Resource File tab, and click New Resource File.
  22. In the Resource File field, click Choose File to navigate to select Relativity.BasicSamples.dll from the directory where you built the project.
  23. In the Application field, click ellipsis button to select Default as the application. This action links your agent assembly to the default application. In general, you link your assemblies to a custom application that you are developing.

    dialog to add new resource files

  24. Click Save. You now have a new agent type available for use as an agent in Relativity. To run the agent, you need to add it to an agent server.
  25. Click the Agents tab, and then click the New Agent button.
  26. In the Agent Type field, click ellipsis button to select the Basic Sample Agent that you created.
  27. In the Agent Server field, click ellipsis button to select the agent server. Your agent runs on this server.
  28. Set the Run Interval to 5.
  29. Click Log All Messages to view all messages that the agent raises in Relativity.

    dialog to add new agent

    Because you created your agent in Relativity, the agent server detects that you have assigned a new agent to it. It loads the necessary assemblies required to trigger the Execute() method on your agent.

  30. To view your agent execution, click the Agents tab and locate your new agent.
  31. Hello World! The current time is: <time>

    message rasied by the sample agent