salesforce-metadata-mcp 2.1.2 → 2.1.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTFORCE.md +287 -65
- package/CHANGELOG.md +101 -0
- package/dist/index.d.ts +0 -1
- package/dist/index.js +0 -0
- package/dist/index.js.map +1 -1
- package/dist/schemas/index.js +76 -27
- package/dist/services/deployment.js +99 -0
- package/dist/services/salesforce.js +401 -18
- package/dist/tools/agentforce.js +255 -43
- package/package.json +1 -1
package/AGENTFORCE.md
CHANGED
|
@@ -6,120 +6,342 @@ Complete guide for creating Agentforce agents with `salesforce-metadata-mcp`.
|
|
|
6
6
|
|
|
7
7
|
## Overview
|
|
8
8
|
|
|
9
|
-
Agentforce (Einstein Copilot) agents
|
|
9
|
+
Agentforce (Einstein Copilot) agents are built from these metadata types, which must be created in order:
|
|
10
10
|
|
|
11
|
-
1. **
|
|
12
|
-
2. **
|
|
13
|
-
3. **
|
|
11
|
+
1. **AutoLaunchedFlow** — the action's implementation; must be Active with `runInMode=SystemModeWithoutSharing`
|
|
12
|
+
2. **GenAiFunction** — wraps a flow as an agent action; includes LLM-facing JSON schemas
|
|
13
|
+
3. **GenAiPlugin** (Topic) — groups related actions; defines routing criteria and instructions
|
|
14
|
+
4. **GenAiPlannerBundle** — links topics to the agent's planning engine
|
|
15
|
+
5. **Bot** — the top-level agent referencing the planner bundle
|
|
16
|
+
6. Activate the Bot
|
|
17
|
+
|
|
18
|
+
> **Important:** The agent type (`EinsteinCopilot` for internal employees, `ExternalCopilot` for customer-facing) is **immutable** after creation — choose carefully.
|
|
14
19
|
|
|
15
20
|
---
|
|
16
21
|
|
|
17
|
-
## Step 1: Create the
|
|
22
|
+
## Step 1: Create the Flow
|
|
23
|
+
|
|
24
|
+
The flow must be an AutoLaunchedFlow with `runInMode=SystemModeWithoutSharing` and must be **Active**.
|
|
18
25
|
|
|
19
26
|
```
|
|
20
|
-
Create an
|
|
21
|
-
-
|
|
22
|
-
-
|
|
23
|
-
-
|
|
24
|
-
-
|
|
27
|
+
Create an AutoLaunchedFlow called Create_Account_Record that:
|
|
28
|
+
- Input variable: AccountName (String, isInput: true)
|
|
29
|
+
- Input variable: Industry (String, isInput: true, isRequired: false)
|
|
30
|
+
- Input variable: Phone (String, isInput: true, isRequired: false)
|
|
31
|
+
- CreateRecords element creating an Account with these fields
|
|
32
|
+
- Output variable: AccountId (String, isOutput: true) — set to the created record ID
|
|
25
33
|
```
|
|
26
34
|
|
|
27
|
-
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
## Step 2: Create Agent Actions (`sf_create_agent_action`)
|
|
38
|
+
|
|
39
|
+
Each action wraps one flow as a GenAiFunction. The tool automatically generates the required LLM-facing JSON schema files (`input/schema.json`, `output/schema.json`) — without these the LLM cannot invoke the action.
|
|
40
|
+
|
|
28
41
|
```json
|
|
29
42
|
{
|
|
30
|
-
"
|
|
31
|
-
"label": "
|
|
32
|
-
"
|
|
33
|
-
"
|
|
34
|
-
"
|
|
35
|
-
|
|
43
|
+
"actionName": "Create_Account",
|
|
44
|
+
"label": "Create Account",
|
|
45
|
+
"description": "Creates a new Account record with the provided company details",
|
|
46
|
+
"flowApiName": "Create_Account_Record",
|
|
47
|
+
"inputs": [
|
|
48
|
+
{
|
|
49
|
+
"name": "AccountName",
|
|
50
|
+
"label": "Account Name",
|
|
51
|
+
"description": "The name of the company or organization",
|
|
52
|
+
"type": "Text",
|
|
53
|
+
"required": true
|
|
54
|
+
},
|
|
55
|
+
{
|
|
56
|
+
"name": "Industry",
|
|
57
|
+
"label": "Industry",
|
|
58
|
+
"description": "The industry or business sector",
|
|
59
|
+
"type": "Text",
|
|
60
|
+
"required": false
|
|
61
|
+
},
|
|
62
|
+
{
|
|
63
|
+
"name": "Phone",
|
|
64
|
+
"label": "Phone",
|
|
65
|
+
"description": "The main phone number",
|
|
66
|
+
"type": "Text",
|
|
67
|
+
"required": false
|
|
68
|
+
}
|
|
69
|
+
],
|
|
70
|
+
"outputs": [
|
|
71
|
+
{
|
|
72
|
+
"name": "AccountId",
|
|
73
|
+
"label": "Account ID",
|
|
74
|
+
"description": "The Salesforce ID of the created Account record",
|
|
75
|
+
"type": "Text"
|
|
76
|
+
}
|
|
77
|
+
]
|
|
36
78
|
}
|
|
37
79
|
```
|
|
38
80
|
|
|
81
|
+
> **Type matching:** The `type` field must match the flow variable's data type:
|
|
82
|
+
> - Flow `Currency` field → use `"type": "Currency"` (maps to `lightning__numberType`)
|
|
83
|
+
> - Flow `Date` field → use `"type": "Date"` (maps to `lightning__dateType`)
|
|
84
|
+
> - Flow `Number` field → use `"type": "Number"`
|
|
85
|
+
> - Flow `String`/`Text` field → use `"type": "Text"` (default)
|
|
86
|
+
>
|
|
87
|
+
> Using `"type": "Text"` for a Currency/Number field causes the LLM to send a string value that the flow rejects.
|
|
88
|
+
|
|
39
89
|
---
|
|
40
90
|
|
|
41
|
-
## Step
|
|
91
|
+
## Step 3: Create Topics (`sf_create_agent_topic`)
|
|
42
92
|
|
|
43
|
-
Topics
|
|
93
|
+
Topics define the agent's areas of expertise. Create topics **after** actions — topics reference action API names.
|
|
44
94
|
|
|
95
|
+
```json
|
|
96
|
+
{
|
|
97
|
+
"topicName": "Account_Management",
|
|
98
|
+
"label": "Account Management",
|
|
99
|
+
"description": "Handle requests to create, update, or look up Account records in Salesforce CRM",
|
|
100
|
+
"scope": "This topic covers creating new company/account records, updating existing accounts, and looking up account information",
|
|
101
|
+
"instructions": [
|
|
102
|
+
"Collect the required company name from the user",
|
|
103
|
+
"Ask for optional details: industry, phone, website",
|
|
104
|
+
"Use the Create Account action to create the record",
|
|
105
|
+
"Confirm success by sharing the record ID with the user"
|
|
106
|
+
],
|
|
107
|
+
"actions": ["Create_Account"]
|
|
108
|
+
}
|
|
45
109
|
```
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
## Step 4: Create Planner Bundle (`sf_create_agent_planner`)
|
|
114
|
+
|
|
115
|
+
The planner bundle is the **critical link** between the Bot and its topics. Without it, the agent has 0 visible topics and cannot route any requests.
|
|
116
|
+
|
|
117
|
+
Create the planner **after** all topics exist.
|
|
118
|
+
|
|
119
|
+
```json
|
|
120
|
+
{
|
|
121
|
+
"plannerName": "CRM_Agent_Planner",
|
|
122
|
+
"label": "CRM Agent Planner",
|
|
123
|
+
"description": "Routes user requests to the appropriate CRM action topics",
|
|
124
|
+
"topicNames": ["Account_Management", "Lead_Management", "Opportunity_Management"]
|
|
125
|
+
}
|
|
51
126
|
```
|
|
52
127
|
|
|
53
128
|
---
|
|
54
129
|
|
|
55
|
-
## Step
|
|
130
|
+
## Step 5: Create Agent (`sf_create_agent`)
|
|
131
|
+
|
|
132
|
+
Create the Bot referencing the planner bundle name.
|
|
133
|
+
|
|
134
|
+
```json
|
|
135
|
+
{
|
|
136
|
+
"agentName": "CRM_Record_Creator",
|
|
137
|
+
"label": "CRM Record Creator",
|
|
138
|
+
"description": "Creates and manages CRM records based on user requests",
|
|
139
|
+
"type": "EinsteinCopilot",
|
|
140
|
+
"plannerName": "CRM_Agent_Planner"
|
|
141
|
+
}
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Agent types:
|
|
145
|
+
- `EinsteinCopilot` — internal employee-facing agent (shown in Lightning sidebar)
|
|
146
|
+
- `ExternalCopilot` — customer-facing Agentforce Service Agent (for Experience Cloud / messaging)
|
|
147
|
+
|
|
148
|
+
---
|
|
56
149
|
|
|
57
|
-
|
|
150
|
+
## Step 6: Activate the Agent (`sf_activate_agent`)
|
|
58
151
|
|
|
152
|
+
```json
|
|
153
|
+
{
|
|
154
|
+
"agentApiName": "CRM_Record_Creator"
|
|
155
|
+
}
|
|
59
156
|
```
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
157
|
+
|
|
158
|
+
---
|
|
159
|
+
|
|
160
|
+
## Deactivating for Changes
|
|
161
|
+
|
|
162
|
+
You must deactivate an agent before modifying its topics, actions, or planner:
|
|
163
|
+
|
|
164
|
+
```json
|
|
165
|
+
{ "agentApiName": "CRM_Record_Creator" }
|
|
64
166
|
```
|
|
65
167
|
|
|
168
|
+
After making changes, re-activate with `sf_activate_agent`.
|
|
169
|
+
|
|
170
|
+
> **Note:** `sf_update_agent_topic` handles deactivate/reactivate automatically.
|
|
171
|
+
|
|
66
172
|
---
|
|
67
173
|
|
|
68
|
-
##
|
|
174
|
+
## Listing and Inspecting Agents
|
|
175
|
+
|
|
176
|
+
### List all agents (`sf_list_agents`)
|
|
177
|
+
|
|
178
|
+
No parameters required. Returns all agents with status:
|
|
69
179
|
|
|
70
180
|
```
|
|
71
|
-
|
|
72
|
-
- Type: Flow
|
|
73
|
-
- Reference: Get_Account_Orders
|
|
74
|
-
- Description: Retrieves all orders for a given account
|
|
75
|
-
- Map input: accountId → {!Agent.Topic.Entities.accountId}
|
|
181
|
+
sf_list_agents → { agents: [{ apiName, label, status, lastModifiedDate }] }
|
|
76
182
|
```
|
|
77
183
|
|
|
184
|
+
### Get full agent config (`sf_get_agent`)
|
|
185
|
+
|
|
186
|
+
```json
|
|
187
|
+
{ "agentApiName": "CRM_Record_Creator" }
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
Returns activation status, all topics (GenAiPlugin), actions (GenAiFunction), and planner bundles (GenAiPlannerBundle) in the org.
|
|
191
|
+
|
|
78
192
|
---
|
|
79
193
|
|
|
80
|
-
##
|
|
194
|
+
## Updating Topics and Actions
|
|
81
195
|
|
|
82
|
-
|
|
196
|
+
### Update a topic in-place (`sf_update_agent_topic`)
|
|
83
197
|
|
|
198
|
+
Automatically deactivates the agent, updates the GenAiPlugin, then reactivates:
|
|
199
|
+
|
|
200
|
+
```json
|
|
201
|
+
{
|
|
202
|
+
"agentApiName": "CRM_Record_Creator",
|
|
203
|
+
"topicName": "Account_Management",
|
|
204
|
+
"label": "Account Management",
|
|
205
|
+
"description": "Handle requests to create, update, or find Account records",
|
|
206
|
+
"scope": "Creating, updating, or looking up company/account information",
|
|
207
|
+
"instructions": ["Ask for company name", "Collect optional fields", "Call the appropriate action", "Confirm success"],
|
|
208
|
+
"actions": ["Create_Account", "Update_Account"],
|
|
209
|
+
"escalationEnabled": false
|
|
210
|
+
}
|
|
84
211
|
```
|
|
85
|
-
1. Create an Agentforce agent called SupportAgent with:
|
|
86
|
-
- Persona: "A friendly and efficient customer support representative"
|
|
87
|
-
- Tone: Formal
|
|
88
|
-
- Company: Acme Corp
|
|
89
212
|
|
|
90
|
-
|
|
91
|
-
- Description: Handles customer support cases, status inquiries, and escalations
|
|
92
|
-
- Scope: Questions about case status, creating new cases, escalating urgent issues
|
|
213
|
+
### Update an action (`sf_update_agent_action`)
|
|
93
214
|
|
|
94
|
-
|
|
95
|
-
- Input variables: subject (String), description (String), contactId (String)
|
|
96
|
-
- A CreateRecords element creating a Case with these fields
|
|
97
|
-
- Output variable: caseId (String)
|
|
215
|
+
Redeploys the GenAiFunction bundle with new schema files:
|
|
98
216
|
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
217
|
+
```json
|
|
218
|
+
{
|
|
219
|
+
"actionName": "Create_Account",
|
|
220
|
+
"label": "Create Account",
|
|
221
|
+
"description": "Creates a new Account record with company name, industry, phone, and website",
|
|
222
|
+
"invocationTargetType": "Flow",
|
|
223
|
+
"flowApiName": "Create_Account_Record_v2",
|
|
224
|
+
"inputs": [
|
|
225
|
+
{ "name": "AccountName", "label": "Account Name", "type": "Text", "required": true },
|
|
226
|
+
{ "name": "AnnualRevenue", "label": "Annual Revenue", "type": "Currency", "required": false }
|
|
227
|
+
],
|
|
228
|
+
"outputs": [
|
|
229
|
+
{ "name": "AccountId", "label": "Account ID", "type": "Text" }
|
|
230
|
+
]
|
|
231
|
+
}
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
### Apex-backed actions
|
|
235
|
+
|
|
236
|
+
Set `invocationTargetType: "ApexClass"` and provide `apexClassName` instead of `flowApiName`:
|
|
237
|
+
|
|
238
|
+
```json
|
|
239
|
+
{
|
|
240
|
+
"actionName": "Search_Knowledge",
|
|
241
|
+
"label": "Search Knowledge Base",
|
|
242
|
+
"description": "Searches the knowledge base for articles matching the query",
|
|
243
|
+
"invocationTargetType": "ApexClass",
|
|
244
|
+
"apexClassName": "KnowledgeSearchAction",
|
|
245
|
+
"inputs": [{ "name": "searchQuery", "label": "Search Query", "type": "Text", "required": true }],
|
|
246
|
+
"outputs": [{ "name": "articleBody", "label": "Article Body", "type": "TextArea" }]
|
|
247
|
+
}
|
|
103
248
|
```
|
|
104
249
|
|
|
105
250
|
---
|
|
106
251
|
|
|
107
|
-
##
|
|
252
|
+
## Deleting Agents (`sf_delete_agent`)
|
|
108
253
|
|
|
109
|
-
|
|
254
|
+
```json
|
|
255
|
+
{
|
|
256
|
+
"agentApiName": "CRM_Record_Creator",
|
|
257
|
+
"deleteTopics": true,
|
|
258
|
+
"deleteActions": true
|
|
259
|
+
}
|
|
260
|
+
```
|
|
110
261
|
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
262
|
+
- `deleteTopics: true` — also deletes the agent's GenAiPlugin topics (discovered via the planner bundle)
|
|
263
|
+
- `deleteActions: true` — also deletes the GenAiFunction actions referenced by those topics
|
|
264
|
+
- Without flags, only the Bot and GenAiPlannerBundle are deleted
|
|
114
265
|
|
|
115
|
-
|
|
266
|
+
**WARNING:** Deleted topics and actions affect all agents that reference them.
|
|
116
267
|
|
|
117
268
|
---
|
|
118
269
|
|
|
119
|
-
##
|
|
270
|
+
## Testing Agents (`sf_test_agent`)
|
|
271
|
+
|
|
272
|
+
Send a test message without opening the Salesforce UI:
|
|
273
|
+
|
|
274
|
+
```json
|
|
275
|
+
{
|
|
276
|
+
"agentApiName": "CRM_Record_Creator",
|
|
277
|
+
"message": "Create an account called Acme Corp in the Technology industry"
|
|
278
|
+
}
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
Returns:
|
|
282
|
+
- `response` — the agent's reply text
|
|
283
|
+
- `sessionId` — the session created (for follow-up messages)
|
|
284
|
+
- `success` — whether the full API round-trip succeeded
|
|
285
|
+
|
|
286
|
+
The agent must be **Active** before testing.
|
|
287
|
+
|
|
288
|
+
---
|
|
289
|
+
|
|
290
|
+
## End-to-End Example
|
|
291
|
+
|
|
292
|
+
Full prompt sequence to create a CRM Record Creator agent:
|
|
293
|
+
|
|
294
|
+
```
|
|
295
|
+
1. Create AutoLaunchedFlow "Create_Account_Record":
|
|
296
|
+
- Input: AccountName (String, required), Industry (String), Phone (String)
|
|
297
|
+
- CreateRecords element → Account with those fields
|
|
298
|
+
- Output: AccountId (String)
|
|
299
|
+
|
|
300
|
+
2. Create agent action "Create_Account":
|
|
301
|
+
- flowApiName: Create_Account_Record
|
|
302
|
+
- inputs: AccountName (Text, required), Industry (Text), Phone (Text)
|
|
303
|
+
- outputs: AccountId (Text)
|
|
304
|
+
|
|
305
|
+
3. Create agent topic "Account_Management":
|
|
306
|
+
- description: "Handle requests to create Account records"
|
|
307
|
+
- scope: "Creating new company or organization accounts in Salesforce"
|
|
308
|
+
- instructions: ["Ask for company name", "Collect optional fields", "Call Create Account action", "Confirm the record ID"]
|
|
309
|
+
- actions: ["Create_Account"]
|
|
310
|
+
|
|
311
|
+
4. Create planner "CRM_Agent_Planner":
|
|
312
|
+
- topicNames: ["Account_Management"]
|
|
313
|
+
|
|
314
|
+
5. Create agent "CRM_Record_Creator":
|
|
315
|
+
- type: EinsteinCopilot
|
|
316
|
+
- plannerName: CRM_Agent_Planner
|
|
317
|
+
|
|
318
|
+
6. Activate "CRM_Record_Creator"
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
---
|
|
322
|
+
|
|
323
|
+
## Debugging
|
|
324
|
+
|
|
325
|
+
If the agent routes correctly but never invokes actions (agent says "I can't do that right now"):
|
|
326
|
+
|
|
327
|
+
1. **Check schema files exist** — Retrieve the GenAiFunction from your org. If you see `The Input LightningTypeBundle schema for action 'X' could not be found`, the schema files are missing. Use `sf_create_agent_action` to redeploy (it now generates schema files automatically).
|
|
328
|
+
|
|
329
|
+
2. **Check type mapping** — If the action is invoked but the flow fails with "field in incorrect format", the `type` in your action inputs doesn't match the flow variable type. A Currency flow variable needs `"type": "Currency"`, not `"type": "Text"`.
|
|
330
|
+
|
|
331
|
+
3. **Use `sf_get_agent_logs`** — Queries ConversationDefinitionEventLog automatically:
|
|
332
|
+
```json
|
|
333
|
+
{ "agentApiName": "CRM_Record_Creator", "limit": 50, "hoursBack": 2 }
|
|
334
|
+
```
|
|
335
|
+
Or run SOQL manually:
|
|
336
|
+
```sql
|
|
337
|
+
SELECT EventLabel, EventTarget, EventDetails
|
|
338
|
+
FROM ConversationDefinitionEventLog
|
|
339
|
+
WHERE LogDate = TODAY
|
|
340
|
+
ORDER BY EventDate DESC
|
|
341
|
+
LIMIT 50
|
|
342
|
+
```
|
|
343
|
+
Look for `TopicClassificationSuccess` (routing worked) vs `ActionExecuted` (action ran).
|
|
344
|
+
|
|
345
|
+
4. **Verify planner exists** — If `TopicClassificationSuccess` never appears, the GenAiPlannerBundle may be missing. Use `sf_create_agent_planner` to create it.
|
|
120
346
|
|
|
121
|
-
|
|
122
|
-
- **Use clear action descriptions** — help the agent know when to invoke each action
|
|
123
|
-
- **Start with Flows** — they're easiest to create and debug
|
|
124
|
-
- **Test with narrow prompts first** — gradually expand scope
|
|
125
|
-
- **Use variables consistently** — name them meaningfully for better AI reasoning
|
|
347
|
+
5. **Use `sf_test_agent`** — Send a test message programmatically and inspect the response without opening the Salesforce UI.
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,106 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [2.1.4] - 2026-05-28
|
|
4
|
+
|
|
5
|
+
### New Tools — Agentforce CRUD & Debugging
|
|
6
|
+
|
|
7
|
+
#### Read
|
|
8
|
+
- `sf_get_agent` — Retrieve full agent configuration from org including activation status, all topics (GenAiPlugin), actions (GenAiFunction), and planner bundles (GenAiPlannerBundle)
|
|
9
|
+
- `sf_list_agents` — List all Agentforce agents in the org with name, label, activation status, and last modified date
|
|
10
|
+
|
|
11
|
+
#### Update
|
|
12
|
+
- `sf_update_agent_topic` — Update an existing GenAiPlugin topic in-place. Automatically deactivates the agent before the update and reactivates it after. All provided fields replace existing values.
|
|
13
|
+
- `sf_update_agent_action` — Update an existing GenAiFunction and regenerate its LLM-facing schema files via zip deploy. All provided fields replace existing values.
|
|
14
|
+
|
|
15
|
+
#### Delete
|
|
16
|
+
- `sf_delete_agent` — Cleanly delete a Bot + its GenAiPlannerBundle + optionally its GenAiPlugin topics + GenAiFunction actions. Discovers related components by traversing Bot → planner → topics → actions. Deactivates first to avoid dependency errors.
|
|
17
|
+
|
|
18
|
+
#### Test & Debug
|
|
19
|
+
- `sf_test_agent` — Send a test message to an agent via the Einstein Agent API (bootstrap → create session → send message → return response text). Full end-to-end test without opening the Salesforce UI.
|
|
20
|
+
- `sf_get_agent_logs` — Query ConversationDefinitionEventLog for agent debug info. Shows TopicClassificationSuccess, ActionExecuted, and error events. Includes summary counts and structured log entries. Filter by agent name, limit, and hours-back window.
|
|
21
|
+
|
|
22
|
+
### Enhanced Existing Tools
|
|
23
|
+
|
|
24
|
+
#### `sf_create_agent`
|
|
25
|
+
- Added `systemPrompt` optional param — custom system prompt injected into every conversation
|
|
26
|
+
- Added `openingMessage` optional param — welcome message shown when users first open the agent
|
|
27
|
+
|
|
28
|
+
#### `sf_create_agent_action` / `sf_update_agent_action`
|
|
29
|
+
- Added `invocationTargetType` param (`"Flow"` | `"ApexClass"`, default `"Flow"`) — support for Apex class actions in addition to AutoLaunchedFlows
|
|
30
|
+
- Added `apexClassName` optional param — Apex class API name for ApexClass-backed actions
|
|
31
|
+
- `flowApiName` is now optional (required only when `invocationTargetType` is `"Flow"`)
|
|
32
|
+
|
|
33
|
+
#### `sf_create_agent_topic` / `sf_update_agent_topic`
|
|
34
|
+
- Added `escalationEnabled` optional boolean — sets `canEscalate` on the GenAiPlugin (allows human agent escalation)
|
|
35
|
+
- Added `fallbackTopic` optional string — API name of a fallback GenAiPlugin topic
|
|
36
|
+
|
|
37
|
+
#### `sf_create_agent_planner`
|
|
38
|
+
- Added `dataLibraryName` optional param — API name of a Data Library (Knowledge Base) for Knowledge-grounded agents
|
|
39
|
+
|
|
40
|
+
### New SOAP Helpers (internal)
|
|
41
|
+
- `readMetadataItem(type, fullName)` — SOAP readMetadata for a single component
|
|
42
|
+
- `listMetadataType(type)` — SOAP listMetadata for all components of a type
|
|
43
|
+
- `deleteMetadataItems(type, fullNames[])` — SOAP deleteMetadata for one or more components
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## [2.1.3] - 2026-05-28
|
|
48
|
+
|
|
49
|
+
### Bug Fixes — Agentforce Action Invocation
|
|
50
|
+
|
|
51
|
+
This release fixes critical bugs that prevented Agentforce agents from invoking actions. Agents would correctly route to topics (TopicClassificationSuccess) but never call actions (no ActionExecuted events).
|
|
52
|
+
|
|
53
|
+
#### Root Cause: Missing GenAiFunction Schema Files
|
|
54
|
+
|
|
55
|
+
`sf_create_agent_action` was deploying GenAiFunction metadata without the required `input/schema.json` and `output/schema.json` bundle files. The Agentforce LLM runtime needs these JSON schemas to construct the tool call specification sent to the LLM. Without them, the LLM cannot invoke actions — it replies with messages like "I can't do that directly right now."
|
|
56
|
+
|
|
57
|
+
**Fix:** `sf_create_agent_action` now deploys a complete zip bundle containing:
|
|
58
|
+
- `genAiFunctions/<Name>/<Name>.genAiFunction-meta.xml`
|
|
59
|
+
- `genAiFunctions/<Name>/input/schema.json` — LLM-facing input parameter schema
|
|
60
|
+
- `genAiFunctions/<Name>/output/schema.json` — LLM-facing output parameter schema
|
|
61
|
+
|
|
62
|
+
Schema files use the correct Salesforce LightningTypeBundle format with `lightning:type`, `lightning:isPII`, `copilotAction:isUserInput`, `copilotAction:isDisplayable`, and `copilotAction:isUsedByPlanner` fields.
|
|
63
|
+
|
|
64
|
+
#### Flow Variable Type Mismatch Fixed
|
|
65
|
+
|
|
66
|
+
Flow variables of type `Currency`, `Number`, `Date`, and `DateTime` must use matching `lightning__numberType` or `lightning__dateType` in the schema, not `lightning__textType`. Using text type caused the LLM to send string values like `"5000"` which Flow rejected with "Amount field provided in incorrect format."
|
|
67
|
+
|
|
68
|
+
**Fix:** Added a `type` field to action parameters (`Text`, `Number`, `Currency`, `Boolean`, `Date`, `DateTime`, `TextArea`) that maps correctly to the corresponding `lightning:type` in the schema.
|
|
69
|
+
|
|
70
|
+
#### `sf_create_agent_topic` Was Creating Wrong Metadata Type
|
|
71
|
+
|
|
72
|
+
The tool was deploying `BotVersion` XML instead of `GenAiPlugin` XML.
|
|
73
|
+
|
|
74
|
+
**Fix:** Replaced `buildBotVersionXml` with `buildGenAiPluginXml` that produces correct `GenAiPlugin` metadata with `pluginType`, `scope`, `canEscalate`, step-by-step `genAiPluginInstructions`, and `genAiFunctions` references.
|
|
75
|
+
|
|
76
|
+
#### Added Missing Tools
|
|
77
|
+
|
|
78
|
+
- `sf_create_agent_planner` — Creates a `GenAiPlannerBundle` that links topics to the agent. This is the critical link between the Bot and its topics. Without it, the agent has 0 visible topics and cannot route any requests. Was missing entirely from v2.0.0.
|
|
79
|
+
- `sf_activate_agent` — Activates an agent via REST API after configuration changes.
|
|
80
|
+
- `sf_deactivate_agent` — Deactivates an agent (required before modifying topics/actions).
|
|
81
|
+
|
|
82
|
+
#### API Version Updated
|
|
83
|
+
|
|
84
|
+
Updated from `62.0` to `66.0` (current Salesforce API version for Agentforce metadata).
|
|
85
|
+
|
|
86
|
+
#### Schema Corrections (`sf_create_agent`)
|
|
87
|
+
|
|
88
|
+
- Removed invalid fields: `persona`, `tone`, `instructions`, `company` (not part of Bot metadata)
|
|
89
|
+
- Fixed `type` enum from `["Default", "EinsteinCopilot"]` to `["EinsteinCopilot", "ExternalCopilot"]`
|
|
90
|
+
- Added `agentTemplate: AiCopilot__AgentforceAgent` to Bot XML (required for proper action invocation wiring)
|
|
91
|
+
|
|
92
|
+
#### Correct Creation Order Now Enforced
|
|
93
|
+
|
|
94
|
+
The tool descriptions now document and enforce the correct metadata creation order:
|
|
95
|
+
1. Create Flows (`sf_create_flow`) — AutoLaunchedFlows with `runInMode=SystemModeWithoutSharing`
|
|
96
|
+
2. Create Actions (`sf_create_agent_action`) — GenAiFunction + schema files
|
|
97
|
+
3. Create Topics (`sf_create_agent_topic`) — GenAiPlugin referencing actions
|
|
98
|
+
4. Create Planner (`sf_create_agent_planner`) — GenAiPlannerBundle linking all topics
|
|
99
|
+
5. Create Agent (`sf_create_agent`) — Bot referencing the planner
|
|
100
|
+
6. Activate Agent (`sf_activate_agent`)
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
3
104
|
## [2.0.0] - 2026-05-22
|
|
4
105
|
|
|
5
106
|
### Major Release — 60+ Tools
|
package/dist/index.d.ts
CHANGED
package/dist/index.js
CHANGED
|
File without changes
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|