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 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 flex prompt template 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 action.

  2. Deploy the action.

Once you’ve completed these steps, you can test the action to confirm it’s working as expected.

Prerequisites

Important

The Agentforce interface evolves quickly, and updates are added regularly. Although we strive to keep this documentation current, you may encounter discrepancies between this content and the current state of the Agentforce interface.

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

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

    Important

    The PRAPI principal must not be deleted. It’s required for the authorization flow to work properly.
    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. Depending on your implementation, you’ll need to specify it when defining the topic instructions for your custom prompt template action or Apex action, and when creating your prompt template.

    3. Leave the Constant Query Filter field empty unless you have a good reason to specify a constant query expression (cq).

    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 action

To deploy the Coveo Passage Retrieval API action, you have the following options:

  • (Recommended) Create a custom prompt template action: Choose this option if you want greater flexibility and control over the action’s behavior.

  • (Out-of-the-box) Use the Apex action: Choose this option to set up the action quickly without extensive customization.

  • (Advanced use case) Create a custom Apex class to send custom context: Choose this option to either send additional context or case record context to the Coveo Passage Retrieval API.

    Note

    This option requires developer skills, including knowledge of Apex and the Coveo Platform.

To deploy the Coveo Passage Retrieval API action using a custom prompt template, you must:

  1. Create a prompt template.

  2. Access your Agentforce AI agent.

  3. Create a topic.

  4. Assign the Agentforce action to your topic.

Create a prompt template

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

  2. In the upper-right corner of the builder, click New Prompt Template.

  3. On the New Prompt Template page, specify the following information:

    Create a prompt template | Coveo for Agentforce

    1. From the Prompt Template Type dropdown menu, select Flex.

    2. In the Prompt Template Name field, enter a descriptive name for your prompt template (for example, Answer Questions With Coveo).

      The API Name field is automatically filled by Salesforce based on the information you entered in the Prompt Template Name field. Don’t modify this value.

    3. (Optional) In the Template Description field, provide a brief description of your prompt template (for example, Coveo Passage Retrieval API flex prompt template).

    4. Under Inputs, click Add, and then specify the following data sources:

      1. In the Name field, enter userInput as a descriptive name for the data source containing the user’s input.

        The API Name field is automatically filled by Salesforce based on the information you entered in the Name field. Don’t modify this value.

      2. From the Source Type dropdown menu, select Free Text, and then click Add.

        Tip

        Keep the Require when template runs checkbox selected for all data sources. This ensures that the prompt template action only runs when all required data sources are provided.

      3. In the next Name field, enter prapiConfig as a descriptive name for the data source containing the Coveo Passage Retrieval API configuration.

        The API Name field is automatically filled by Salesforce based on the information you entered in the Name field. Don’t modify this value.

      4. From the Source Type dropdown menu, select Free Text, and then click Add.

      5. In the next Name field, enter additionalContext as a descriptive name for the data source containing additional context to help the AI agent answer questions.

        The API Name field is automatically filled by Salesforce based on the information you entered in the Name field. Don’t modify this value.

      6. From the Source Type dropdown menu, select Free Text.

    5. Click Next to access the Prompt Builder.

  4. In the Prompt section, enter your prompt template instructions and specify related resources.

    Important

    Writing prompt template instructions is an iterative process. The information in this section isn’t exhaustive and only provides an example. Adjust the information to fit your specific use case. See Best Practices for Building Prompt Templates for guidelines and recommendations.
    Warning

    You must include the Apex:CoveoAgentforce__InvocablePassageRetrievalFlexTemplate Apex class in your prompt template instructions. This class invokes the Coveo Passage Retrieval API to retrieve relevant passages from items indexed in your Coveo organization.

    All source references such as {!$Input:userInput} and {!$Apex:<CLASS_NAME>} in the following example are links to resources, which must be specified by selecting Insert Resources in the Prompt section. They must not be pasted in the instructions.
    Example
    Context:
You're a service agent and knowledge expert supporting agents in answering customer questions accurately and efficiently.
Your role is to synthesize clear, factual answers based only on the retrieved document passages and cite all referenced materials.
Agents rely on your answer to assist users, but they validate and finalize the response.
A user just asked this question

###
{!$Input:userInput}
###

Use the following passages in order to answer the user question:
{!$Apex:CoveoAgentforce__InvocablePassageRetrievalFlex.Prompt} 1

To structure your response
Use only the provided passages to generate the answer. Do not invent or infer beyond what's present.
Write in concise, declarative English, using the active voice.
Include all used citations at the end as a numbered list.
    1 The Apex:CoveoAgentforce__InvocablePassageRetrievalFlex is a placeholder for the Coveo Passage Retrieval API response. It contains the passages and citations returned by the API. When a user asks a question, the Agentforce AI agent essentially receives input similar to the following: 
    Context:
You must answer the following question...

###
<QUESTION_ENTERED_BY_USER>
###

Use the following passages to answer the question:
{
  "passages": ["lorem ipsum", "dolor sit amet", "consectetur adipiscing elit"],
  "citations": ["https://www.lipsum.com/", "https://www.google.com", "https://www.coveo.com"]
}

To structure your response
Use only the provided passages to generate the answer...

  5. At the upper-left corner of the Prompt Builder, click Preview Settings (Prompt Builder Preview Settings icon | Coveo for Agentforce) to specify your prompt template settings.

    1. In the Inputs section, specify the following information:

      1. In the userInput field, enter a question to test your template, for example:

        What is Barca Skipper?

      2. In the prapiConfig field, enter the name of the PR API configuration. Make sure it matches the name of the custom metadata configuration you created in step 3b.

      3. In the additionalContext field, enter additional context to help the AI agent answer the question entered by the user, for example:

        {"product": "Barca Skipper"}

        The field value must be a valid JSON string of key-value pairs.

    2. In the Output section:

      1. Ensure the Generate Response option is enabled.

      2. From the Response Language dropdown menu, select English.

      3. Under On Preview, ensure the Expand Resolved Prompt and Expand Generated Response checkboxes are selected.

  6. Click Save & Preview to save your prompt template settings and preview the results. For subsequent changes, click Preview to see the updated results.

  7. Once you’re satisfied with the results, click Activate to enable your prompt template.

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, such as Einstein Copilot or Agentforce (Default), click down to access the Actions menu, and then select Open in Builder.

    Important

    You can’t use Coveo-powered Agentforce actions in a Service Agent at this time. Use a different agent type to leverage your Coveo-powered actions.

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

    Tip
    Tip

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

Create a topic

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

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

  3. (Optional) In the Create a Topic modal, specify the job you want this topic to perform.

    Tip

    You can skip this step and specify the job you want this topic to perform in the second step of the modal.

  4. Click Next.

  5. 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 Name field, enter a descriptive name for your topic (for example, Barca Product Support).

      By default, the API Name field is automatically filled by Salesforce based on the information you entered in the Name field.

    2. In the Classification Description field, provide a brief topic description (one to three sentences). Enter text similar to the following:

      Example
      When a user asks a question about Barca, a company that sells boats and related products, these questions can be to provide an answer to a support type of question or be general questions about boats and related products.

      The description should be clear and concise, providing enough context for the topic’s purpose. Agentforce uses this information to determine which topic to use when answering questions.

    3. In the Scope field, enter a job description for your topic. Enter text similar to the following:

      Example
      Your job is to answer the questions the user asks providing useful information about products or helping the user resolve an issue.
You will create a medium to short answer to the questions asked.
Ensure responses are well-structured and formatted correctly to provide clarity and usefulness to the user.

    4. In the Instruction field, instruct Agentforce to use your custom prompt template action to retrieve passages as follows:

      Example
      Always use the "<COVEO_PRAPI_PROMPT_TEMPLATE>" action and answer with the output of the action only.

      Where <COVEO_PRAPI_PROMPT_TEMPLATE> is the name of the custom prompt template action you created in step 3b. For more information, see Create a custom prompt template action (Recommended).

      Tip

      Follow Best Practices for Topic Instructions.

      1. Click Add Instructions, and then enter text similar to the following:

        If the "<COVEO_PRAPI_POMPT_TEMPATE>" action does not provide you with passages, do not attempt to answer the question and simply say that you couldn't find any relevant document to answer the question.

      2. Click Add Instructions, and then enter text similar to the following:

        You should always use the following for the Input to the "<COVEO_PRAPI_PROMPT_TEMPLATE>" action {"prapiConfig": "<YOUR_PRAPI_CONFIG_NAME>"}

        Where <YOUR_PRAPI_CONFIG_NAME> is the name of the configuration you created in step 3b. For more information, see Create a custom metadata configuration.

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

      Tip

      This section is only available if you’re using the Agentforce (Default) agent. If you’re using a custom agent, you can skip this step.
      Examples
      What is Barca Skipper?
      How to update maps?

  6. Click Next.

  7. Skip the Select the actions you want to include in your topic step.

  8. Click Finish to create your topic.

    Tip

    If a Topic Overlap Detected warning appears, review your topics to ensure they’re distinct. Make any necessary adjustments to avoid overlap.

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. To add your custom prompt template action to the topic, 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 agent action modal | Coveo for Agentforce

    1. From the Reference Action Type dropdown menu, select Prompt Template.

    2. From the Reference Action field, select the prompt template you created (for example, Answer Questions With Coveo).

      The Agent Action Label and Agent Action API Name fields are automatically filled by Salesforce.

    3. Click Next and scroll to the Agent Action Configuration section.

      Agent action configuration panel | Coveo for Agentforce

    4. In the Agent Action Instructions field, enter a description for your custom action.

      Example
      Retrieve relevant passages from the documentation to answer user questions.

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

    6. Under the Inputs section:

      1. Provide instructions for the userInput input.

        Example
        The question from the user.

      2. Provide instructions for the prapiConfig input.

        Example
        The API name of the configuration to use.

      3. Provide instructions for the additionalContext input.

        Example
        Additional context to retrieve relevant documents.

    7. Under the Output section:

      1. Under Data Type, select the Show in conversation checkbox.

      2. From the Output Rendering dropdown menu, select Rich Text.

    8. Click Finish to create your action. The This Topic’s Actions tab now displays your custom action.

      PRAPI prompt template action | Coveo for Agentforce
      Tip

      If you don’t see your custom action in the list, refresh the page.

  5. Click Activate in the upper-right corner of the builder to enable your AI agent.

  6. Test your custom prompt template action to confirm it’s working as expected.

You’ve successfully set up and deployed the Coveo Passage Retrieval API action using a custom prompt template. Your Agentforce AI agent is now able to retrieve relevant passages from the items indexed in your Coveo organization to answer user questions.

Use the Apex action

To deploy the Coveo Passage Retrieval API action using the default Apex 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, such as Einstein Copilot or Agentforce (Default), click down to access the Actions menu, and then select Open in Builder.

    Important

    You can’t use Coveo-powered Agentforce actions in a Service Agent at this time. Use a different agent type to leverage your Coveo-powered actions.

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

    Tip
    Tip

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

Create a topic

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

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

  3. (Optional) In the Create a Topic modal, specify the job you want this topic to perform.

    Tip

    You can skip this step and specify the job you want this topic to perform in the second step of the modal.

  4. Click Next.

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

      By default, the API Name field is automatically filled by Salesforce based on the information you entered in the Name field.

    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

      Follow Best Practices for 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?

  6. 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 Coveo Passage Retrieval API Apex.

      The Agent Action Label and Agent Action API Name fields are automatically filled by Salesforce based on the action you selected in the Reference Action field.

      Tip
      Tip

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

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

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

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

    7. Click Finish.

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

  6. Test your action to confirm it’s working as expected.

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

Test the action

  1. Launch the Agentforce Builder.

  2. Enter a question related to your topic in the Conversation Preview panel on the right side of the screen.

  3. Review the information displayed on the Plan Canvas (center screen) to verify expected behavior.

    1. Confirm your AI agent selects the correct topic.

    2. Confirm the generated response matches the passages returned by the Coveo Passage Retrieval API action.