Enable and use labels for your agent

What are labels?

Labels are tags or categories that you assign to documents and pages in your agent's knowledge base. They allow you to organize your content by topic, department, language, product line, or any other classification that suits your needs. When labels are enabled, you can filter which documents the agent uses to generate responses, ensuring users receive only the most relevant information for their context.

For example, if your knowledge base contains documentation in multiple languages, you can label documents by language (e.g., "English", "Spanish", "French") and then serve only the appropriate language content based on the user's selection.

👉 Learn more about deployment options and parameters

🚧

Note:

This is an enterprise-only feature and must be specifically enabled for your account. Contact your account manager or support team to request access.

What labels do

When you provide label parameters in your deployment options:

• The agent filters its knowledge base to include only documents with the specified labels.
• This ensures responses are based on relevant, contextually appropriate content.
• You can control whether to include unlabelled documents in the filtered results.
• Labels can help you segment content by language, department, product category, or any custom classification.

Common use cases for labels

• Multi-language documentation: Serve content only in the user's selected language by labelling documents with language tags.
• Department-specific knowledge: Filter content by department (Sales, Support, Engineering) to provide role-specific information.
• Product-specific documentation: When managing multiple products, show only relevant documentation for each product.
• Regional content: Organize content by region or location to serve geographically relevant information.

❗️

Note on label assignment: Before you can use labels for filtering, you must first assign labels to your documents through the API. Labels can be assigned both manually and automatically. For detailed instructions on how to create and assign labels to your documents, see the Labels API documentation.

Default availability

• Works on the following deployment types: API, Embed, Live Chat, Website Copilot, Instant Viewer, and Search Generative Experience (SGE).
• No additional setup beyond enabling the toggle and adding the parameters to your deployment code.
• Labels are evaluated at query time and do not permanently filter your knowledge base.
• Label data is used only during that request to preserve privacy—the agent does not store label selections.

How to enable and use labels

Step 1: Enable labels in deployment settings

1. Select the agent you want to update and click the Deploy Agent icon.

2. If your agent is private, click Make Public. If it's already public, continue to the next step.

3. Select your preferred deployment method, then click the Settings (gear) icon.

4. On the configuration page, turn on the Labels integration.

5. Click Save Settings to apply the changes.

Step 2: Add label parameters to your embed script

Open your web page template, locate the embed code, and add the label parameters to the embed snippet. Then save the template.

Parameters

• labels - A comma-separated list of label identifiers. You can use either label IDs (numeric) or label names (text).

  • Format: labels="label1,label2,label3" or labels="1,2,3"
  • Example with names: labels="English,Sales,ProductA"
  • Example with IDs: labels="101,102,103"

• labels_exclusive - Controls whether unlabelled documents are included (optional, boolean).

  • Format: labels_exclusive="true" or labels_exclusive="false"
  • When true: Only documents with matching labels are used (strict filtering)
  • When false or omitted: Documents with matching labels AND documents without any labels are used (permissive filtering)
  • Default: false

Example embed code with labels

<div id="customgpt_chat"></div>
<script src="https://cdn.customgpt.ai/js/embed.js"
defer
div_id="customgpt_chat"
p_id="123456"
p_key="abcdefgh"
labels="English,Sales"
labels_exclusive="true"></script>

🚧

Note:

Replace the values of p_id, p_key, and labels with your specific Agent ID, key, and desired label filters. In the above example, the agent will use only documents labelled with "English" or "Sales", and will exclude any unlabelled documents because labels_exclusive is set to true.

Understanding label filtering behavior

Exclusive filtering (labels_exclusive="true")

When you enable exclusive filtering, the agent will only use documents that have at least one of the specified labels. Documents without any labels will be excluded from the search.

Example scenario:

• Your knowledge base contains documents labelled "English", "Spanish", unlabelled documents, and documents with other labels.
• You set labels="English" and labels_exclusive="true".
• Result: Only documents labelled "English" will be used in responses. Spanish documents and unlabelled documents are excluded.

Permissive filtering (labels_exclusive="false" or omitted)

When exclusive filtering is disabled (the default), the agent will use documents with the specified labels plus any documents that have no labels at all.

Example scenario:

• Your knowledge base contains documents labelled "English", "Spanish", and unlabelled documents.
• You set labels="English" and labels_exclusive="false" (or simply omit the parameter).
• Result: Documents labelled "English" AND all unlabelled documents will be used in responses. Spanish documents are excluded.

Using labels with the API

Labels are also available when querying your agent via the Send Message API endpoint. Include the labels and labels_exclusive parameters in your API request to filter content programmatically.

For complete API documentation and examples, visit the Labels API reference.

Best practices

1. Plan your label taxonomy: Before assigning labels, create a consistent naming scheme that makes sense for your use case.

2. Use descriptive label names: Choose clear, descriptive names that make it easy to understand what content each label represents.

3. Consider using IDs for dynamic filtering: If you're dynamically changing labels based on user actions, label IDs may be more stable than names.

4. Test filtering behavior: Test both exclusive and permissive filtering to ensure you're getting the expected results.

5. Document your labels: Keep documentation of your label system so team members understand the labelling scheme.

6. Regularly review and update labels: As your knowledge base grows, review your labels to ensure they remain relevant and well-organized.

Related articles

• Enable and use CRM integration
• Deploy using an MCP server