AiPluginUtteranceDef Metadata Type in SFDX

Architectural Overview#

In complex enterprise Agentforce implementations with 10+ topics (GenAiPlugin), two topics may have closely related boundaries—such as Order Status Inquiry versus Order Modification & Cancellation. While the topic’s classificationDescription is the primary semantic signal, the AiPluginUtteranceDef metadata type allows architects to bind explicit sample utterances to a topic.

These utterances serve as high-signal few-shot routing examples for the GenAiPlannerBundle reasoning engine, dramatically reducing topic misclassifications on domain-specific jargon or colloquial customer phrasing.

SFDX Directory & File Suffix#

Key Metadata Fields#

Declarative XML & package.xml Examples#

Sample .aiPluginUtteranceDef-meta.xml#

<?xml version="1.0" encoding="UTF-8"?>
<AiPluginUtteranceDef xmlns="http://soap.sforce.com/2006/04/metadata">
    <language>en_US</language>
    <masterLabel>Track Freight Pallet Utterance</masterLabel>
    <plugin>Order_Logistics_Tracking</plugin>
    <utterance>Where is my freight shipment pallet right now and what is the carrier BOL number?</utterance>
</AiPluginUtteranceDef>

Sample package.xml Manifest#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Order_Logistics_Tracking</members>
        <name>GenAiPlugin</name>
    </types>
    <types>
        <members>Track_Freight_Pallet_Utterance</members>
        <name>AiPluginUtteranceDef</name>
    </types>
    <version>68.0</version>
</Package>

SFDX CLI Retrieval & Deployment#

Retrieve and deploy AiPluginUtteranceDef components via the Salesforce CLI:

# Retrieve all AiPluginUtteranceDef records
sf project retrieve start --metadata "AiPluginUtteranceDef:*"

# Deploy a specific utterance definition alongside its parent GenAiPlugin
sf project deploy start --metadata "GenAiPlugin:Order_Logistics_Tracking" "AiPluginUtteranceDef:Track_Freight_Pallet_Utterance"

Senior Architect Best Practices & Gotchas#

• Curate Real Production Transcripts: Harvest real customer phrasing from Service Cloud Messaging transcripts where the agent previously hesitated or misrouted, sanitize any PII, and commit those phrases as AiPluginUtteranceDef records.
• Quality Over Quantity: Five to ten diverse, domain-specific utterances per GenAiPlugin outperform fifty repetitive variations of the same sentence.

Frequently asked questions

What is AiPluginUtteranceDef used for in Agentforce?

It stores curated example utterances associated with an Agentforce topic (GenAiPlugin), helping the reasoning engine accurately classify and route user requests to the right topic.

Where are AiPluginUtteranceDef files stored in an SFDX project?

They reside in the force-app/main/default/aiPluginUtteranceDefs directory with the .aiPluginUtteranceDef-meta.xml file suffix.

How do utterances in AiPluginUtteranceDef complement topic classification descriptions?

While classificationDescription explains the topic boundary in prose, AiPluginUtteranceDef provides concrete few-shot phrasing examples that disambiguate overlapping topics.

How do I retrieve AiPluginUtteranceDef metadata using Salesforce CLI?

Execute sf project retrieve start --metadata AiPluginUtteranceDef to retrieve all topic utterance definitions into your local SFDX project.