---
title: Manage Coveo Search Agents
slug: q2qg1117
canonical_url: https://docs.coveo.com/en/q2qg1117/
collection: leverage-machine-learning
source_format: adoc
---
# Manage Coveo Search Agents

> **Important**
>
> Coveo Conversational Search is a paid product extension that enables the Coveo Search Agent.
> Contact [Coveo Sales](https://www.coveo.com/en/contact) or your Account Manager to add Coveo Conversational Search to your [organization](https://docs.coveo.com/en/185.md) license.

This article provides information on how to create a [Coveo Search Agent](https://docs.coveo.com/en/q2pe0294.md) to add conversational search to your Coveo-powered search interface.
It also explains how to [add custom behavior](#add-custom-behavior-to-your-search-agent) to your Search Agent to guide how it answers under specific conditions.

> **Tip**
>
> For complete implementation steps for the Coveo Search Agent, see [Search Agent implementation overview](https://docs.coveo.com/en/q32c7422.md).

> **Important**
>
> * A conversation is limited to 15 total turns, including the initial query.
> Up to 14 follow-up queries can be submitted after the initial query.
> Once the 15-turn limit is reached, a new conversation must be started by entering a new query in the main search box.
> 
> * A conversation remains active for up to 48 hours, after which no follow-up queries can be added.
> 
> * Each query is limited to 300 characters, whether it's the initial query or a follow-up query.
> Queries that exceed this limit are rejected.
> 
> * By default, an organization is limited to 5,000 Search Agent follow-up queries per day.
> This limit is adjustable.
> If your organization needs a higher limit, contact your Coveo Account Manager.

> **Tip**
>
> Use the [Conversation Inspector](https://docs.coveo.com/en/q5ea0141.md) to analyze the answers generated by your Search Agent.
> It provides visibility into every answer generated throughout a multi-turn conversation.
> You can also view the retrieved passages for each query, including when no answer was generated, making it easier to troubleshoot retrieval and answer-generation issues.

## Prerequisites

Before you can create a Coveo Search Agent, make sure you have the following:

* A [Passage Retrieval (CPR) model](https://docs.coveo.com/en/q32c7422.md#step-2-create-a-cpr-model) in your Coveo organization.

* The [required privileges](#required-privileges).

## Create a Search Agent

1. On the [**Agents**](https://platform.cloud.coveo.com/admin/#/orgid/ai-and-ml/agents/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/ai-and-ml/agents/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/ai-and-ml/agents/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/ai-and-ml/agents/)) page of the [Coveo Administration Console](https://docs.coveo.com/en/183.md), click **Add agent**.

1. On the **General** page, set the following:

** **Type** is preset to **Search Agent** (currently the only available agent type).

** **Name**: Enter a descriptive name for your Search Agent.

** **Description**: Optionally, enter a description that identifies the purpose and usage of your Search Agent.
This is for internal reference only.

1. Click **Next**.

1. On the **Configuration** page, set the following tool options:

* For the **Passage retrieval** tool:

** Select the [CPR](https://docs.coveo.com/en/oaie9196.md) [model](https://docs.coveo.com/en/1012.md) you want your Search Agent to use for passage retrieval.

** For **Items to consider**, set the maximum number of retrieved items you want the [CPR](https://docs.coveo.com/en/oaie9196.md) [model](https://docs.coveo.com/en/1012.md) to consider when retrieving the most relevant passages.

   [Passage Retrieval (CPR)](https://docs.coveo.com/en/oaie9196.md) uses [two stages of content retrieval](https://docs.coveo.com/en/oaie5277.md#relevant-content-retrieval).
   First-stage content retrieval identifies the most relevant items in the [index](https://docs.coveo.com/en/204.md), and second-stage content retrieval identifies the most relevant segments of text (passages) from those items.
   The most relevant passages will then be used to generate answers.

   If you find that answers are generated using text from low-relevance items, you can use the **Items to consider** option to set a custom value for the maximum number of items considered during second-stage content retrieval.
   For example, if you set the maximum number of items to 20, the CPR [model](https://docs.coveo.com/en/1012.md) retrieves the most relevant passages only from the 20 most relevant items identified during first-stage content retrieval.

   > **Important**
   >
   > The default setting of `40` provides good results in most use cases.
   > However, you can specify a custom value if you have a good understanding of the relevance hierarchy of the results returned during first-stage content retrieval.
   > If you set the value too low, there may not be enough relevant passages from which to generate an answer.

* For the **Answer generation** tool, the **Conversational AI** option is enabled by default because it provides the best user experience.
It should only be disabled for specific use cases requiring a non-conversational experience.
+
When enabled, the Search Agent adds a conversational search experience to your search interface.
This allows the Search Agent to handle follow-up questions and orchestrate multiple rounds of content retrieval and answer generation based on the ongoing conversation context.
+
When disabled, the Search Agent generates only one answer based on the initial user query, and doesn't allow users to ask follow-up questions.
This is a non-conversational experience, where the Search Agent doesn't maintain conversational context or perform multiple rounds of content retrieval and answer generation.
+
> **Note**
>
> The **Conversational AI** option is enabled by default because it provides the best user experience and should only be disabled for specific use cases requiring a non-conversational experience.

+
> **Important**
>
> * A conversation is limited to 15 total turns, including the initial query.
> Up to 14 follow-up queries can be submitted after the initial query.
> Once the 15-turn limit is reached, a new conversation must be started by entering a new query in the main search box.
> 
> * A conversation remains active for up to 48 hours, after which no follow-up queries can be added.
> 
> * Each query is limited to 300 characters, whether it's the initial query or a follow-up query.
> Queries that exceed this limit are rejected.
> 
> * By default, an organization is limited to 5,000 Search Agent follow-up queries per day.
> This limit is adjustable.
> If your organization needs a higher limit, contact your Coveo Account Manager.

1. Click **Add agent** to save your Search Agent.

1. Optionally, [add custom behavior](#add-custom-behavior-to-your-search-agent) to guide how your Search Agent answers under specific conditions.

## Add custom behavior to your Search Agent

You can customize how the Search Agent behaves when generating answers based on specific conditions.
To do this, add instructions to the Search Agent by defining structured pairs of conditions and corresponding behaviors.

Custom behaviors give you greater control over the Search Agent output and let you better align its actions with your business logic and requirements.
For example, you can use custom behavior to:

* adjust the answer's tone to better align with your company's voice and branding.

* route to different products or content.

* set the language the Search Agent uses when answering.

  > **Note**
  >
  > By default, the Search Agent attempts to generate answers in the same language as the query, but this behavior isn't guaranteed.
  > We highly recommend that you add custom behavior to specify the language to use when answering, and to define a fallback language.
  > For more information and example behaviors, see [Search Agent multilingual answers](https://docs.coveo.com/en/p5ne0024.md#search-agent-multilingual-answers).

* comply with industry regulations or legal requirements.

* add restrictions so that answers don't mention specific products or competitors, give financial advice, or show other sensitive information.

* detect and mitigate potential prompt injection attempts by defining adversarial hardening conditions and corresponding behaviors, such as ignoring malicious input or providing a safe response.

The custom behaviors don't alter the core prompt that's used by the Search Agent, but are treated as additional instructions based on specific conditions.

> **Important**
>
> Adding a custom behavior affects all answers generated by the Search Agent.
> While this can improve answers for certain [queries](https://docs.coveo.com/en/231.md), it may also cause inaccuracies, inconsistencies, or unintended results.
> 
> You're responsible for configuring, testing, and maintaining your custom behaviors to ensure compatibility with the [Coveo Platform](https://docs.coveo.com/en/186.md) and future updates.
> This includes providing role-specific guidance or exemplars for creating a custom behavior, and monitoring outputs at scale to detect issues.
> 
> Custom behaviors aren't covered by Coveo's automated tests, which are limited to the default base prompt.
> Because the base prompt is updated frequently, you should retest your custom behavior regularly.
> 
> Be aware of the following risks when adding a custom behavior:
> 
> * Semantic overload may produce inaccurate or harmful responses.
> 
> * No Coveo tools are provided to validate answer quality at scale.
> 
> * A custom behavior may introduce security risks, such as prompt injection.

To add custom behavior to your Search Agent

1. Access the **Knowledge Generative AI** section of the Swagger UI that's associated with your Coveo organization region ([US](https://platform.cloud.coveo.com/docs?urls.primaryName=Knowledge+Generative+AI) | [CA](https://platform-ca.cloud.coveo.com/docs?urls.primaryName=Knowledge+Generative+AI) | [EU](https://platform-eu.cloud.coveo.com/docs?urls.primaryName=Knowledge+Generative+AI) | [AU](https://platform-au.cloud.coveo.com/docs?urls.primaryName=Knowledge+Generative+AI)).

1. Click **Authorize** and authenticate using your Coveo organization account credentials.

1. In the Swagger UI, expand the **Agent Configuration API** section.

1. Use the **Update an agent** PATCH request to access the Search Agent's JSON code.

   ![Use Swagger UI to update the Search Agent | Coveo](https://docs.coveo.com/en/assets/images/leverage-machine-learning/search-agent-update-swagger.png)

.. Enter your Coveo [**organization ID**](https://docs.coveo.com/en/n1ce5273.md).

.. Enter the **Agent ID** of the Search Agent you want to configure.

   > **Tip**
   >
   > To get the Search Agent ID, on the [**Agents**](https://platform.cloud.coveo.com/admin/#/orgid/ai-and-ml/agents/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/ai-and-ml/agents/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/ai-and-ml/agents/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/ai-and-ml/agents/)) page of the [Coveo Administration Console](https://docs.coveo.com/en/183.md), click the Search Agent, and then click **View**.

.. Click **Execute**.
The JSON code for the Search Agent appears in the **Response body**.

1. Modify the JSON code to add your custom behaviors using the following `behaviors` property:

   --
   ```json
   {
   ...
   "behaviors": [
       {
         "obligation": "string",
         "conditions": ["array of strings"]
       }
   ]
   ...
   }
   ```

where:

* `obligation` is a plain-text natural language string describing what the Search Agent must do, avoid, say, prioritize, and so on.
It sets the behavior and requires no special syntax.
This field is required and can't be empty.

* `conditions` is an array of strings that set the conditions that trigger the behavior when met.
This field is required and can be empty.
If it's empty, the behavior will always apply.
When multiple conditions are specified, the behavior applies only when all conditions are satisfied using an AND operation.

> **Important**
>
> All obligations whose conditions are satisfied are evaluated and applied during answer generation.
> This can lead to potential conflicts or unpredictable results if there are multiple applicable obligations for a given query.
> Make sure the obligations don't conflict with each other, or account for potential conflicts in the `conditions` field to help the Search Agent resolve any potential behavioral conflicts.

> **Note**
>
> Search Agent behaviors have the following limits:
> 
> * Up to 15 behaviors (`obligation` and `conditions` sets) per Search Agent.
> 
> * Up to 300 characters per `obligation` and `conditions` fields.
> 
> * Up to 6000 characters for the entire set of `obligation` and `conditions` fields.

**Example**

The first behavior in the following example always applies, while the second behavior applies only when both of the specified conditions are met.
So in the case when the second behavior applies, the Search Agent must both avoid offering financial advice, opinions, and fictional content, and decline to answer and redirect the user to official resources.

```json
{
...
  "behaviors": [
    {
      "obligation": "Do not offer financial advice, opinions, or fictional content.",
      "conditions": []
    },
    {
      "obligation": "Politely decline to answer and redirect the user to official resources.",
      "conditions": [
        "When a topic falls outside approved customer scope.",
        "When a query contains language that violates content guidelines."
        ]
    }
  ]
...
}
```
--

1. In the Swagger UI, click **Execute** to apply the changes to the Search Agent.

## Required privileges

The following table indicates the privileges required for members to manage Coveo agents (see [Manage privileges](https://docs.coveo.com/en/3151.md) and [Privilege reference](https://docs.coveo.com/en/1707.md)).

| Action | Service | Domain | Required access level |
|---|---|---|---|
| View agent configurations | Machine Learning | Agent configuration | View |
| Organization | Organization | View |  |
| Create and manage agents | Organization | Organization | View |
| Machine Learning | Agent configuration | Edit |  |
| Models | View |  |  |