GenAiPlugin Metadata Type Reference

The GenAiPlugin metadata type represents an Agentforce Topic—a modular capability domain composed of natural-language classification rules, behavioral guardrails (scope), step-by-step instructions (genAiPluginInstructions), and executable actions (GenAiFunction). Introduced in API version 60.0, GenAiPlugin is the core building block referenced by an agent’s GenAiPlannerBundle.

In Salesforce DX projects, topic definitions are stored in force-app/main/default/genAiPlugins/ with the .genAiPlugin-meta.xml suffix.

Why GenAiPlugin Design Determines Agent Accuracy#

In Agentforce’s ReAct (Reason + Act) architecture, the LLM does not evaluate every single action across your entire org on every turn. Instead:

1. Topic Classification (description): The planner reads the description of all GenAiPlugin topics attached to the agent and selects the best-matching topic.
2. Scoped Reasoning (scope + genAiPluginInstructions): Once inside the selected GenAiPlugin, the agent is restricted to the genAiFunctions listed in that plugin and follows its instructions to decide which action to call.

Key Metadata Fields#

Production-Grade XML Example#

Below is a GenAiPlugin (Order_Returns_And_Refunds.genAiPlugin-meta.xml) that defines a customer-facing order return topic with clear classification rules, instructions, and two custom Agent Actions:

<?xml version="1.0" encoding="UTF-8"?>
<GenAiPlugin xmlns="http://soap.sforce.com/2006/04/metadata">
    <canEscalate>true</canEscalate>
    <description>Handles customer inquiries about returning purchased items, checking return eligibility windows, generating return shipping labels, and checking refund statuses.</description>
    <developerName>Order_Returns_And_Refunds</developerName>
    <genAiFunctions>
        <functionName>Verify_Order_Return_Eligibility</functionName>
    </genAiFunctions>
    <genAiFunctions>
        <functionName>Create_Return_Authorization</functionName>
    </genAiFunctions>
    <genAiPluginInstructions>
        <description>Always call Verify_Order_Return_Eligibility using the customer's Order Number before promising a refund or creating a return authorization.</description>
        <developerName>Instruction_Verify_Eligibility_First</developerName>
        <masterLabel>Verify Eligibility First</masterLabel>
        <sortOrder>0</sortOrder>
    </genAiPluginInstructions>
    <genAiPluginInstructions>
        <description>If the order total exceeds $1,000 or the return window expired within the last 7 days, offer to escalate the conversation to a human support specialist.</description>
        <developerName>Instruction_High_Value_Escalation</developerName>
        <masterLabel>High Value Escalation</masterLabel>
        <sortOrder>1</sortOrder>
    </genAiPluginInstructions>
    <language>en_US</language>
    <masterLabel>Order Returns and Refunds</masterLabel>
    <pluginType>Topic</pluginType>
    <scope>Your job is only to verify order return eligibility and initiate return authorizations for verified orders. Never modify shipping addresses or process credit card chargebacks directly.</scope>
</GenAiPlugin>

Frequently asked questions

What does GenAiPlugin represent in Agentforce Builder?

In Agentforce Builder, a GenAiPlugin metadata component corresponds directly to an Agent Topic. It defines the classification description used to route user utterances, the scope boundaries, the topic instructions, and the allowed Agent Actions.

How does the Agentforce reasoning engine decide which GenAiPlugin to select?

The reasoning engine evaluates the description field (Classification Description in the UI) of each GenAiPlugin assigned to the agent's GenAiPlannerBundle against the user's message and conversation history.

What is the difference between description and scope on a GenAiPlugin?

The description field tells the planner when to route a user request into this topic. Once the topic is selected, the scope field defines the boundaries of what the agent is permitted to do while operating inside that topic.

How do I attach Agent Actions to a GenAiPlugin?

Add genAiFunctions entries to the GenAiPlugin XML, setting each functionName field to the developer name of a GenAiFunction metadata component.

What does the canEscalate field control on a GenAiPlugin?

When canEscalate is set to true, the agent is permitted to escalate the conversation to a human service representative when operating within that topic.