How to call the Navigator API from Agentforce for smarter agreements

As AI agents become integral to everyday business practices, it’s going to be important that developers understand how to configure agents that can integrate business systems across different platforms. Integrations aren’t new to Docusign developers; many developers are already integrating Docusign and Salesforce through tools such as the Apex Toolkit and the Salesforce extension app. But with Salesforce’s Agentforce, these integrations can be brought to the next level. 

In my last blog post, I explained how to set up Salesforce authentication with JWT to access any Docusign API. In this post, I’m going to show you how you can build on top of that and use that authentication to call the Navigator API from inside Agentforce with a custom agent action. This will enable your agents to access data from the Navigator smart agreement repository, extracting key information about your contracts and taking your integration beyond eSignature.

Constructing the Apex class

Before you can configure an Agentforce agent to call the Navigator API, you’ll need to write an Apex class that makes the correct HTTP request. Because the method you’ll be defining in this class needs to include the InvocableMethod annotation in order to be called from Agentforce, the class needs to be an outer class, meaning that it can’t be nested within another class. The method itself should be a public static method. When adding the InvocableMethod annotation, be sure to include a helpful label and description, as those will be used by Agentforce to recognize your action later on. In this example, the agent is going to take the API account ID as an input, so the method needs to take that GUID as a parameter. Invocable methods can only take parameters in the form of a list, so you need to define an sObject as an inner class that represents the object that will be passed as that parameter. Invocable methods can also only return lists, so you need to do the same for the object that will be returned by the method. The code snippet below demonstrates how to begin to define the methods and inner classes used in this example.

public class NavigatorCallout {

  //This method calls the Docusign Navigator API
  @InvocableMethod (label='Get a single Navigator Agreement' description='Calls the Navigator API to get an agreement')
  public static List<NavigatorResponse> getAgreement(List<NavigatorRequest> navigatorRequests){

  }
    
  public class NavigatorRequest {
    @InvocableVariable
    public String accountId;
  }

  public class NavigatorResponse {
    @InvocableVariable
    public String data;
  }
}

Now that you’ve set up your class and method definitions, you can make an API call. To do this, create an HttpRequest object inside the invocable method that you defined previously. Then, use the setEndpoint and setHeader methods to define the header and endpoint for the request. In this case, you’ll call the Agreements: getAgreement endpoint to retrieve detailed information about a specific agreement. Because authentication has already been set up through named credentials (as explained in this blog post), you can simply use callout:{NAMED_CREDENTIAL_NAME} in place of the endpoint’s base path. This example demonstrates how to take the account ID from the parameter and hard-code the agreement ID into the request, but you could define any inputs and outputs of your choice. Finally, return the response from the API call in the data property of the inner class that you created previously.

When you’re all finished, your class will look something like this:

public class NavigatorCallout {
  //This method calls the Docusign Navigator API
  @InvocableMethod (label='Get a single Navigator Agreement' description='Calls the Navigator API to get an agreement')
  public static List<NavigatorResponse> getAgreement(List<NavigatorRequest> navigatorRequests){
    List<NavigatorResponse> responseList = new List<NavigatorResponse>();
    for (NavigatorRequest request : navigatorRequests) {
      // Create the HTTP request to call Docusign's API
      HttpRequest req = new HttpRequest();
      req.setEndpoint('callout:Navigator' + request.accountId + '/agreements/abd1472b-xxxx-xxxx-xxxx-29e834e14cee');
      req.setMethod('GET');
      req.setHeader('Content-Type', 'application/json');
      
      // Send the request
      Http http = new Http();
      HTTPResponse res = http.send(req);
      
      // Parse the JSON response
      NavigatorResponse response = new NavigatorResponse();
      Map<String, Object> jsonResponse = (Map<String, Object>)JSON.deserializeUntyped(res.getBody());
      Object dataObj = jsonResponse;
      response.data = dataObj != null ? JSON.serialize(dataObj) : '';
      System.debug(response);
      responseList.add(response);
      
      System.debug(responseList);
      System.debug(responseList[0].data);
    }
    return responseList;
  }
    
  public class NavigatorRequest {
    @InvocableVariable
    public String accountId;
  }

  public class NavigatorResponse {
    @InvocableVariable
    public String data;
  }
}

Configuring the agent

Once you have a working Apex class, you’re ready to turn that class into a custom action that can be performed by an AI agent. To do that, navigate in Salesforce Setup to Agentforce Assets and choose the Actions tab; then, select New Agent Action (figure 1).

Figure 1: Creating a new Agent Action

In the popup window (figure 2), specify the reference action type and category. Choose Apex for the type and Invocable Methods for the category. Then, select the Apex class that you just created in the search box labeled Reference Action by choosing the label that matches the label included in my InvocableMethod annotation in your Apex class. 

Figure 2: Create an Agent Action popup window

Next, configure the inputs and outputs for the action. The inputs and outputs that appear in figure 3 below were populated based on the parameters and returned objects of the Apex class that was created previously. All that you need to do here is fill out the text boxes with instructions for how the agent should handle these values. Be sure to check the boxes for Require input and Collect data from user under the accountId input so the agent knows to ask for that input in the conversation. You can also indicate that the agent should format the JSON response from the API call in a human-readable way and show that output in the conversation.

Figure 3: Configuring the inputs and outputs for the action

Next, add this action to a topic in my agent. This is where you can give the agent instructions on how to handle the action. In the Agentforce Builder, choose Topics in the left menu and select New to create a new topic (figure 4).

Figure 4: Creating a new topic

You’ll be prompted to input some instructions for the agent and add actions to the topic. Choose the action that you created previously and add it to the topic. When you’ve configured your topic, the details should look something like figure 5 below. These instructions are key to defining how the agent will use your action, so it’s important to be clear, adding instructions like “Always ask the user for an account ID.” This is also where you can get creative and instruct your agent on how to respond to different prompts from the user. 

Figure 5: Setting topic details

It’s important to remember that these instructions are nondeterministic, and you may need to experiment with different prompts and instructions to understand how the agent will actually behave. You can test out various prompts in the conversation preview in the Agentforce Builder. Figure 6 below demonstrates a sample conversation where the agent returns details about the user’s agreement using the Navigator API. When the user asks the agent to tell them more about the details of their agreement, the agent asks for an account ID, then uses the Apex class to make the API call. Per the instructions in the custom Apex action (see figure 3), the agent formats the information from the JSON response in a user-friendly way rather than returning raw JSON.

Figure 6: Sample conversation

This is just one example of how you can leverage Docusign APIs from within Agentforce. With the Docusign IAM platform, there are countless other possibilities. For example, you might ask the agent to trigger a workflow with the Maestro API, or to send an envelope with the Connected Fields API. Or you can integrate eSignature functionality into your agents with the help of the Apex Toolkit. AI agents are powerful tools that are even more powerful when they can operate across platforms. Integrating Docusign into Agentforce unlocks new potential for agents to do even more and create a seamless experience for your users.

Additional resources

• How to set up Salesforce authentication with JWT to access any Docusign API

• Configuring Salesforce for scalable and secure Docusign integrations

• Apex Toolkit overview

• Navigator API overview