Set up and deploy the Coveo Passage Retrieval API action

This is for:

Developer System Administrator

The Coveo Passage Retrieval API Agentforce action is optimized for Question and Answering (Q&A) use cases. It’s used to return contextual pieces of information (passages) from items indexed in your Coveo organization. By leveraging the Coveo Passage Retrieval (PR) API, this Coveo-powered Agentforce action enhances the accuracy and relevance of the responses generated by your Agentforce AI agents.

Sample action | Coveo for Agentforce

This article describes how to configure and use the Coveo Passage Retrieval API Agentforce action in your Salesforce organization. To do so, you must:

  1. Configure the Agentforce action

  2. Deploy the Agentforce action

Prerequisites

Before you start, make sure you’ve completed the following tasks:

Configure the Agentforce action

Configuring the Coveo Passage Retrieval API Agentforce action is a two-step process. It involves setting up the external credential and API key and creating a custom metadata configuration.

Set up the external credential and API key

  1. From the Salesforce Setup menu, in the Quick Find box, enter Named Credentials, and then select Named Credentials.

  2. Select the External Credentials tab, and then click Coveo Passage Retrieval API.

  3. On the page that opens, go to the Principals section.

  4. Find the entry for the PRAPI principal, click down to access the Actions menu, and then select Edit.

    Principal edit menu | Coveo for Agentforce

  5. On the Edit Principal page, under Authentication Parameter, click Add to create your authentication parameter.

    Important
    Important

    This step assumes that you’ve already created an API key using the Anonymous search template in the Coveo Administration Console (see Prerequisites). If you haven’t, you must complete this task before proceeding.

    We don’t recommend setting the search hub in the API key. Instead, set it when you create the custom metadata configuration.

    1. In the Name field, enter apikey.

    2. In the Value field, enter the API key that will be used to call the Coveo PR API.

    3. Click Save.

  6. To reopen the Edit Principal page, find the entry for the PRAPI principal, click down to access the Actions menu, and then select Edit.

  7. On the Edit Principal page, under Principal Access, right-click CoveoPRAPI_Named_Principal_Access, and then select Open Link in New Tab to open the permission set in a new tab.

    Edit principal panel | Coveo for Agentforce
    Tip
    Tip

    This permission set is included in the Coveo for Agentforce package to simplify granting access to users who will use the Coveo Passage Retrieval API Agentforce action through an Agentforce AI agent.

    Granting access to this external credential is therefore required for all users who will be using this Agentforce action. Otherwise, the Agentforce AI agent won’t be able to use the API key to call the Coveo PR API. For additional ways to set external credentials, see Enable User External Credentials.

  8. Under Permission Set for the Coveo Passage Retrieval Authorization Named Principal Access, click Manage Assignments to grant users permission to use the PR API key specified in step 5b.

    Manage Assignments button | Coveo for Agentforce

  9. The setup of the external credential and API key is now complete. You must now create a custom metadata configuration.

Create a custom metadata configuration

  1. From the Setup menu, in the Quick Find box, enter Custom Metadata Types, and then select Custom Metadata Types.

  2. On the page that opens, scroll to Coveo Passage Retrieval Configuration, and then click Manage Records.

  3. Click New to create a record. This record will serve as a configuration to call the PR API.

    Record configuration page | Coveo for Agentforce

    1. In the Label field, enter a descriptive name for your configuration (for example, General <PRODUCT|COMPANY> Questions).

      Where <PRODUCT|COMPANY> is the name of your product or company.

    2. By default, the Coveo Passage Retrieval Configuration Name field is automatically filled by Salesforce based on the information you entered in the Label field. Don’t modify this value.

      Tip
      Tip

      Take note of the configuration name. You’ll need to specify it when defining your topic instructions.

    3. Leave Query Filter field empty unless you have a good reason to specify an advanced query expression (aq). For more information, see Advanced field queries.

    4. In the SearchHub field, enter the search hub that you want to use to call the PR API, for example, PassageRetrievalAPI.

      Important
      Important

      If you already set a search hub value when you created the API key to call the Coveo PR API, make sure to specify the same value here to avoid any issues. See Set up the external credential and API key for details.

    5. Leave the Locale field empty.

    6. In the Number of passages field, keep the default value of 5. See Request payload for details about the number of passages returned by the Coveo PR API.

    7. Click Save to save your configuration.

Deploy the Agentforce action

To deploy the Coveo Passage Retrieval API Agentforce action, you must:

  1. Access your Agentforce AI agent

  2. Create a topic

  3. Assign the Agentforce action to your topic

Access your Agentforce AI agent

  1. From the Salesforce Setup menu, in the Quick Find box, enter Agentforce Agents, and then select Agentforce Agents.

  2. On the page that opens, find your Agentforce AI agent (for example, Einstein Copilot or Agentforce (Default)), click down to access the Actions menu, and then select Open in Builder.

    Important

    To avoid any issues, we don’t recommend using the Agentforce Service Agent at this time.

  3. If your Agentforce AI agent is currently active, click Deactivate in the upper-right corner of the Agent Builder.

    Tip
    Tip

    You must always deactivate your Agentforce AI agent to make changes to it.

Create a topic

  1. In the Agent Builder, select Topics from the left tab.

  2. Click the New actions menu, select New Topic, and then click Next.

    Tip

    The first step of the Create a Topic modal is optional. You can skip this step and specify the job you want the topic to perform in the next step.

  3. In the second step of the modal, specify the following information:

    Create a topic page | Coveo for Agentforce
    Important
    Important

    Creating a topic is an iterative process. The information in this section isn’t exhaustive and is only meant to provide you with an example. You must adjust the information to fit your specific use case.

    1. In the Topic Label field, enter a descriptive name for your topic.

      Example
      Answer <YOUR_COMPANY|YOUR_PRODUCT> related questions

      Where <YOUR_COMPANY|YOUR_PRODUCT> is the name of your company or product.

    2. In the Classification Description field, enter text similar to the following:

      Example
      When a user asks a question about <YOUR_COMPANY|YOUR_PRODUCT> a <COMPANY|PRODUCT> that <COMPANY_DESCRIPTION|PRODUCT_DESCRIPTION>.
These questions can provide answers to support-related questions or general questions such as `<WHAT_CAN_PEOPLE_ASK_ABOUT>`.

      Where:

      • <YOUR_COMPANY|YOUR_PRODUCT> is the name of your company or product.

      • <COMPANY|PRODUCT> is the type of entity you’re providing information about.

      • <COMPANY_DESCRIPTION|PRODUCT_DESCRIPTION> is a brief description of your company or product.

      • <WHAT_CAN_PEOPLE_ASK_ABOUT> is a list of topics that users can ask about.

    3. In the Scope field, enter text similar to the following:

      Example
      Your job is to answer the user's questions by providing useful information about products or help the user resolve an issue.
Create a short to medium-size answer to the questions asked.

    4. In the Instructions fields, enter text similar to the following:

      Tip
      Tip

      We recommend following best practices for writing topic instructions.
      Examples

      • Instruction 1

        Always use the Coveo Passage Retrieval API action. Write an answer to the question that was asked using only the passages that are returned by the Coveo Passage Retrieval API.
Don't answer with any other information than the passages returned by the action.

      • Instruction 2

        Use the citations returned by the Coveo Passage Retrieval API action to display numbered URL links under your answer as the reference documents.

      • Instruction 3

        Always use the following as input for the Coveo Passage Retrieval API action:
{"prapiConfig": "<YOUR_PRAPI_CONFIG_NAME>"}

        Where <YOUR_PRAPI_CONFIG_NAME> is the name of the configuration you created in step 3b.

      • Instruction 4 (Guardrail)

        If the Coveo Passage Retrieval API action doesn't return a passage, don't attempt to answer the question.
Simply say that you couldn't find relevant information to answer the question.

    5. In the Example User Input fields, add examples of questions that users might ask.

      Example

      • Example User Input:

        What's error code 22?

      • Example User Input:

        What products does `<YOUR_COMPANY>` offer?

      • Example User Input:

        Which GPS is the best for sailing?

      • Example User Input:

        How do I update my maps on my GPS?

  4. Click Next and then Finish to create your topic.

Assign the Agentforce action to your topic

  1. On the Topics panel, select the topic you created.

  2. On the Topic Details panel, select This Topic’s Actions.

    Topic details panel | Coveo for Agentforce

  3. Click the New action menu, and then select Create New Action.

  4. On the Create an Agent Action page, specify the following information:

    Create an action page | Coveo for Agentforce

    1. From the Reference Action Type dropdown menu, select Apex.

    2. From the Reference Action Category dropdown menu, select Invocable Method.

    3. In the Reference Action field, select Invoke Coveo Passage Retrieval API.

    4. In the Agent Action Label field, change the default value from Invoke Coveo Passage Retrieval API to Coveo Passage Retrieval API.

      Tip
      Tip

      The name of the action you’re creating must match the name of the action you specified in the topic instructions.

    5. In the Agent Action API Name field, change the default value from Invoke_Coveo_Passage_Retrieval_API to Coveo_Passage_Retrieval_API.

    6. Click Next and then scroll to the Agent Action Configuration section. The instructions for your action and each input and output are displayed.

      Input and output instructions | Coveo for Agentforce

    7. Clear the Show loading text for this action checkbox.

    8. In the Outputs section:

      1. Select the Show in conversation checkbox under Citations and Passages.

      2. Select Rich Text from the Output Rendering dropdown menu under Citations and Passages.

    9. Click Finish.

  5. In the upper-right corner of the Agent Builder, click Activate to reactivate your AI agent.

  6. From the Agent Builder:

    1. Use the Conversation Preview to test your AI agent.

    2. Review the information displayed on the center test screen to verify that your AI agent is working as expected. For example, make sure your AI agent selects your new topic correctly, and that the generated response matches the passages returned by the Coveo Passage Retrieval API Agentforce action.

You’ve successfully set up and deployed the Coveo Passage Retrieval API Agentforce action. Your Agentforce AI agent is now ready to provide accurate and relevant responses to your users' questions.