Set up and deploy Coveo-powered Agentforce actions

This is for:

Developer System Administrator

Coveo for Agentforce provides Coveo-powered Agentforce actions that you can use to extend the capabilities of your Agentforce AI agents in Salesforce. For example, the Coveo Passage Retrieval API Agentforce action can be 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 provides detailed instructions on how to set up and deploy the Coveo Passage Retrieval API Agentforce action in your Salesforce organization. To do so, you must:

  1. Install Coveo for Agentforce

  2. Configure the Agentforce action

  3. Deploy the Agentforce action

Prerequisites

Before you start, make sure you have:

Install Coveo for Agentforce

  1. Access the Coveo for Agentforce listing on the Salesforce AppExchange, and then click Get it Now.

    Tip
    Tip

    You can also use the download links available in the release notes to install Coveo for Agentforce.

  2. On the Let’s Get Started page, click Log In, and then provide your Salesforce administrator credentials, if not already done.

  3. On the Where do you want to install this package? page, click Install in Production or Install in Sandbox, as appropriate.

    Tip
    Tip

    We recommend the Install in Sandbox option when first trying the application.
    Install in Production or Sandbox screen | Coveo for Agentforce

  4. On the Confirm Installation Details page:

    1. Click the terms and conditions link to review the legal agreement.

    2. Select the I have read and agree to the terms and conditions checkbox.

    3. Click Confirm and Install.

  5. On the Install Coveo for Agentforce page, choose for whom you want to install the package, and then click Install.

    Installation screen | Coveo for Agentforce

  6. On the Approve Third-Party Access page, select the Yes, grant access to these third-party websites checkbox, and then click Continue.

    Third-party access screen | Coveo for Agentforce

The installation may take a few minutes to complete.

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 Actions menu to access the Actions menu, and then select Edit.

    Installation screen | 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.

    Keep in mind that setting the search hub in the API key isn’t recommended. To avoid any issues, we recommend setting it while creating the custom metadata configuration instead.

    1. In the Name field, enter apikey.

    2. In the Value field, enter <your_api_key>.

      Where <your_api_key> is the API key that will be used to call the Coveo PR API.

    3. Click Save.

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

    Edit principal page | Coveo for Agentforce
    Tip
    Tip

    This permission set is included in the Coveo for Agentforce package to simplify giving access to users who will be using 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.

  7. 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

  8. 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.

    PR API 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.

    7. Click Save to save your configuration.

Deploy the Agentforce action

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

  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 Agents, and then select Agents.

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

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

    Tip
    Tip

    You must always deactivate your 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 action menu, and then select New Topic.

  3. On the Create a Topic panel, 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. Make sure to 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 the 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 step10b.

      • 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?

Assign the Agentforce action to your topic

Once you’ve created your topic, you must assign the Coveo Passage Retrieval API Agentforce action to it.

  1. On the Topic Details panel of the topic you created in the previous section, select This Topic’s Actions.

    Topic details panel | Coveo for Agentforce

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

  3. 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. In the Reference Action field, select Invoke Coveo Passage Retrieval API.

    3. In the Agent Action Label field, rename the default Invoke Coveo Passage Retrieval API value 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.

    4. In the Agent Action API Name field, rename the default Invoke_Coveo_Passage_Retrieval_API value to Coveo_Passage_Retrieval_API.

    5. Click Next.

      The instructions for your action and each input and output are displayed.

    6. In the Outputs section, select the Show in conversation checkbox under Citations and Passages.

      Input and output instructions | Coveo for Agentforce

    7. Click Finish.

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

  5. 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.

That’s it! 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.