GenAiPlugin | Metadata API Developer Guide

Parent Type

This type extends the Metadata metadata type and inherits its fullName field.

File Suffix and Directory Location

GenAiPlugin components have the suffix .genAiPlugin and are stored in the genAiPlugins folder.

Version

GenAiPlugin components are available in API version 62.0 and later.

Special Access Rules

GenAiPlugin is available only if Agents is enabled in your org.

Fields

Field Name	Description
aiPluginUtterances	Field Type AiPluginUtteranceDef[] Description A list of utterances that can be used to pick a topic during runtime.
canEscalate	Field Type boolean Description Indicates whether this topic is eligible for escalation to a rep.
description	Field Type string Description The description of the topic.
developerName	Field Type string Description Required. Represents the API name of the topic. This name must be unique across all custom and customized topics. Can contain only underscores and alphanumeric characters and must be unique in your org. It must begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores.
genAiFunctions	Field Type GenAiPluginFunctionDef[] Description A list of functions in the topic.
genAiPluginInstructions	Field Type GenAiPluginInstructionDef[] Description A list of instructions in the topic.
language	Field Type string Description Required. The language of the topic.
masterLabel	Field Type string Description Required. The master label for the topic.
plannerField	Field Type string Description Represents the topic’s parent planner.
pluginType	Field Type PluginType (enumeration of type string) Description Required. Values are: `Topic` `APICustomTopic`
scope	Field Type string Description A specific job description for a topic.

GenAiPluginFunctionDef

A function in the topic.

Field Name	Description
functionName	Field Type string Description Required. The API name of the function.

Usage

In Winter '26 orgs and later, use GenAiPlannerBundle to retrieve topics that are created within a particular agent. To retrieve topics in the asset library, use GenAiPlugin.

When deploying topic or action metadata to a Summer '25 (version 64.0) org, retrieve the metadata using Metadata API version 64.0, even if your source org is Winter '26 or later (version 65.0). For Winter `26 and later, use Metadata API version 65.0 and later.

Declarative Metadata Sample Definition

The following is an example of a GenAiPlugin component.

1<GenAiPlugin xmlns="http://soap.sforce.com/2006/04/metadata" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
2    <description>Engages and interacts with the user about any request that could be CRM data related.
3      This could be tasks such as identify and summarize records, answer queries, aggregate data,
4      find and query objects, update records, or drafting and refining emails.</description>
5    <developerName>General_CRM_Customized</developerName>
6    <genAiFunctions>
7        <functionName>EmployeeCopilot__IdentifyObjectByName</functionName>
8    </genAiFunctions>
9    <genAiFunctions>
10        <functionName>EmployeeCopilot__IdentifyRecordByName</functionName>
11    </genAiFunctions>
12    <genAiFunctions>
13        <functionName>EmployeeCopilot__QueryRecords</functionName>
14    </genAiFunctions>
15    <genAiFunctions>
16        <functionName>EmployeeCopilot__QueryRecordsWithAggregate</functionName>
17    </genAiFunctions>
18    <genAiFunctions>
19        <functionName>EmployeeCopilot__GetActivitiesTimeline</functionName>
20    </genAiFunctions>
21    <genAiFunctions>
22        <functionName>EmployeeCopilot__GetActivityDetails</functionName>
23    </genAiFunctions>
24    <genAiFunctions>
25        <functionName>EmployeeCopilot__GetRecordDetails</functionName>
26    </genAiFunctions>
27    <genAiFunctions>
28        <functionName>EmployeeCopilot__DraftOrReviseEmail</functionName>
29    </genAiFunctions>
30    <genAiFunctions>
31        <functionName>EmployeeCopilot__UpdateRecordFields</functionName>
32    </genAiFunctions>
33    <genAiFunctions>
34        <functionName>EmployeeCopilot__WebSearch</functionName>
35    </genAiFunctions>
36    <genAiFunctions>
37        <functionName>EmployeeCopilot__AnswerQuestionsWithKnowledge</functionName>
38    </genAiFunctions>
39    <genAiPluginInstructions>
40        <description>There are multiple available data retrieval functions at your disposal.
41          You can use each one of them multiple times if needed. You should use functions
42          as many times as necessary until you have all the data required to fulfill the request of the user.
43          You can perform extra calls if you think you can get additional relevant information.</description>
44        <developerName>therearemu0</developerName>
45        <language xsi:nil="true"/>
46        <masterLabel>therearemu</masterLabel>
47    </genAiPluginInstructions>
48    <genAiPluginInstructions>
49        <description>Do not declare your intent i.e. &quot;I will now retrieve the data&quot; - Just fetch the data.</description>
50        <developerName>donotdecla1</developerName>
51        <language xsi:nil="true"/>
52        <masterLabel>donotdecla</masterLabel>
53    </genAiPluginInstructions>
54    <genAiPluginInstructions>
55        <description>Identify the object type (i.e., leads, opportunities, accounts) the user asks about.
56           If unclear, confirm with the user and make a suggestion based on the query context and history.</description>
57        <developerName>identifyth2</developerName>
58        <language xsi:nil="true"/>
59        <masterLabel>identifyth</masterLabel>
60    </genAiPluginInstructions>
61    <genAiPluginInstructions>
62        <description>When only the name of a record is mentioned in the user request, you MUST call the IdentifyRecordByName action
63          to get the necessary IDs.</description>
64        <developerName>whenonlyth3</developerName>
65        <language xsi:nil="true"/>
66        <masterLabel>whenonlyth</masterLabel>
67    </genAiPluginInstructions>
68    <genAiPluginInstructions>
69        <description>Always call QueryRecords &amp; QueryRecordsWithAggregate passing plain natural language english as input.
70          You must Include the record ID in the input if available.</description>
71        <developerName>alwayscall4</developerName>
72        <language xsi:nil="true"/>
73        <masterLabel>alwayscall</masterLabel>
74    </genAiPluginInstructions>
75    <genAiPluginInstructions>
76        <description>For accounts and contacts, combine the WebSearch action with the CRM data retrieval actions.
77           MUST maintain citations in the answer.</description>
78        <developerName>foraccount5</developerName>
79        <language xsi:nil="true"/>
80        <masterLabel>foraccount</masterLabel>
81    </genAiPluginInstructions>
82    <genAiPluginInstructions>
83        <description>When a user asks for a summary or overview of a record, use GetRecordDetails to get an overview
84          of the data of the record, then use other data retrieval actions as needed.</description>
85        <developerName>whenausera6</developerName>
86        <language xsi:nil="true"/>
87        <masterLabel>whenausera</masterLabel>
88    </genAiPluginInstructions>
89    <genAiPluginInstructions>
90        <description>When asked for a summary on multiple records, you must iterate over all record IDs and for each one,
91          call GetRecordDetails.</description>
92        <developerName>whenaskedf7</developerName>
93        <language xsi:nil="true"/>
94        <masterLabel>whenaskedf</masterLabel>
95    </genAiPluginInstructions>
96    <genAiPluginInstructions>
97        <description>If the user asks about activities you must call GetActivitiesTimeline.</description>
98        <developerName>iftheusera8</developerName>
99        <language xsi:nil="true"/>
100        <masterLabel>iftheusera</masterLabel>
101    </genAiPluginInstructions>
102    <genAiPluginInstructions>
103        <description>When providing the Activity Types for GetActivitiesTimeline, choose all the types that are relevant
104           to the user request. Examples - User Request 1 - &quot;What questions does John Doe have that need addressing?&quot;,
105           Activity Types - &quot;Call&quot;, &quot;Email&quot;.
106           User Request 2 - &quot;What are the next activities for John Doe?&quot;, Activity Types - &quot;Task&quot;, &quot;Event&quot;.</description>
107        <developerName>whenprovid9</developerName>
108        <language xsi:nil="true"/>
109        <masterLabel>whenprovid</masterLabel>
110    </genAiPluginInstructions>
111    <genAiPluginInstructions>
112        <description>When asked about recent activities, you should provide the answer, starting from the last 30 days
113          and ending on the current date, unless a specific date range is specified by the user.</description>
114        <developerName>whenaskeda10</developerName>
115        <language xsi:nil="true"/>
116        <masterLabel>whenaskeda</masterLabel>
117    </genAiPluginInstructions>
118    <genAiPluginInstructions>
119        <description>When you are asked about a single Call, Meeting, Email or any other single specific activity, call GetActivityDetails.</description>
120        <developerName>whenyouare11</developerName>
121        <language xsi:nil="true"/>
122        <masterLabel>whenyouare</masterLabel>
123    </genAiPluginInstructions>
124    <genAiPluginInstructions>
125        <description>Always use DraftOrReviseEmail when asked to generate a new email or revise a previously generated email.</description>
126        <developerName>alwaysused12</developerName>
127        <language xsi:nil="true"/>
128        <masterLabel>alwaysused</masterLabel>
129    </genAiPluginInstructions>
130    <genAiPluginInstructions>
131        <description>ExtractRecordFieldsAndValuesFromUserInput must be called prior to UpdateRecordFields.</description>
132        <developerName>extractrec13</developerName>
133        <language xsi:nil="true"/>
134        <masterLabel>extractrec</masterLabel>
135    </genAiPluginInstructions>
136    <genAiPluginInstructions>
137        <description>Avoid using structured lists, bullet points, or numbered lists. Instead, present the information in complete sentences
138          and paragraphs as if you were writing an article or a report.</description>
139        <developerName>avoidusing14</developerName>
140        <language xsi:nil="true"/>
141        <masterLabel>avoidusing</masterLabel>
142    </genAiPluginInstructions>
143    <genAiPluginInstructions>
144        <description>User questions which can be answered by knowledge articles or documents. These questions usually want information,
145          instructions or guidance, including but not limited to customer questions about company information, policies and frequently asked questions.</description>
146        <developerName>userquesti15</developerName>
147        <language xsi:nil="true"/>
148        <masterLabel>userquesti</masterLabel>
149    </genAiPluginInstructions>
150    <language>en_US</language>
151    <masterLabel>General CRM Customized</masterLabel>
152    <pluginType>Topic</pluginType>
153    <scope>Your job is to interact and answer questions for the user about anything Salesforce or CRM data related,
154      combining all data retrieval functions. i.e: QueryRecords(), GetRecordDetails(), GetActivitiesTimeline(), GetActivityDetails(), WebSearch()</scope>
155</GenAiPlugin>

The following is an example package.xml that references the previous definition.

1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3   <types>
4      <members>*</members>
5      <name>GenAiPlugin</name>
6   </types>
7   <version>62.0</version>
8</Package>

Wildcard Support in the Manifest File

This metadata type supports the wildcard character * (asterisk) in the package.xml manifest file. For information about using the manifest file, see Deploying and Retrieving Metadata with the Zip File.