salesforce-metadata-mcp 2.1.2 → 2.1.3

package/AGENTFORCE.md

@@ -6,120 +6,218 @@ Complete guide for creating Agentforce agents with `salesforce-metadata-mcp`.
 
 ## Overview
 
-Agentforce (Einstein Copilot) agents consist of three components:
+Agentforce (Einstein Copilot) agents are built from these metadata types, which must be created in order:
 
-1. **Agent** — The top-level AI assistant with a persona and instructions
-2. **Topics** — Areas of expertise (what types of requests the agent handles)
-3. **Actions** — Concrete steps the agent takes (powered by Flows, Apex, or Prompt Templates)
+1. **AutoLaunchedFlow** — the action's implementation; must be Active with `runInMode=SystemModeWithoutSharing`
+2. **GenAiFunction** — wraps a flow as an agent action; includes LLM-facing JSON schemas
+3. **GenAiPlugin** (Topic) — groups related actions; defines routing criteria and instructions
+4. **GenAiPlannerBundle** — links topics to the agent's planning engine
+5. **Bot** — the top-level agent referencing the planner bundle
+6. Activate the Bot
+
+> **Important:** The agent type (`EinsteinCopilot` for internal employees, `ExternalCopilot` for customer-facing) is **immutable** after creation — choose carefully.
 
 ---
 
-## Step 1: Create the Agent
+## Step 1: Create the Flow
+
+The flow must be an AutoLaunchedFlow with `runInMode=SystemModeWithoutSharing` and must be **Active**.
 
 ```
-Create an Agentforce agent called SalesAssistant:
-- Label: Sales Assistant
-- Persona: A knowledgeable sales expert who helps reps close more deals
-- Tone: Professional
-- Instructions: Always check opportunity stage before recommending next steps. Be concise.
+Create an AutoLaunchedFlow called Create_Account_Record that:
+- Input variable: AccountName (String, isInput: true)
+- Input variable: Industry (String, isInput: true, isRequired: false)
+- Input variable: Phone (String, isInput: true, isRequired: false)
+- CreateRecords element creating an Account with these fields
+- Output variable: AccountId (String, isOutput: true) — set to the created record ID
 ```
 
-This calls `sf_create_agent` with:
+---
+
+## Step 2: Create Agent Actions (`sf_create_agent_action`)
+
+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.
+
 ```json
 {
-  "agentName": "SalesAssistant",
-  "label": "Sales Assistant",
-  "type": "EinsteinCopilot",
-  "persona": "A knowledgeable sales expert who helps reps close more deals",
-  "tone": "Neutral",
-  "instructions": "Always check opportunity stage before recommending next steps. Be concise."
+  "actionName": "Create_Account",
+  "label": "Create Account",
+  "description": "Creates a new Account record with the provided company details",
+  "flowApiName": "Create_Account_Record",
+  "inputs": [
+    {
+      "name": "AccountName",
+      "label": "Account Name",
+      "description": "The name of the company or organization",
+      "type": "Text",
+      "required": true
+    },
+    {
+      "name": "Industry",
+      "label": "Industry",
+      "description": "The industry or business sector",
+      "type": "Text",
+      "required": false
+    },
+    {
+      "name": "Phone",
+      "label": "Phone",
+      "description": "The main phone number",
+      "type": "Text",
+      "required": false
+    }
+  ],
+  "outputs": [
+    {
+      "name": "AccountId",
+      "label": "Account ID",
+      "description": "The Salesforce ID of the created Account record",
+      "type": "Text"
+    }
+  ]
 }
 ```
 
+> **Type matching:** The `type` field must match the flow variable's data type:
+> - Flow `Currency` field → use `"type": "Currency"` (maps to `lightning__numberType`)
+> - Flow `Date` field → use `"type": "Date"` (maps to `lightning__dateType`)
+> - Flow `Number` field → use `"type": "Number"`
+> - Flow `String`/`Text` field → use `"type": "Text"` (default)
+>
+> Using `"type": "Text"` for a Currency/Number field causes the LLM to send a string value that the flow rejects.
+
 ---
 
-## Step 2: Create Topics
+## Step 3: Create Topics (`sf_create_agent_topic`)
 
-Topics tell the agent what kinds of user requests it can handle.
+Topics define the agent's areas of expertise. Create topics **after** actions — topics reference action API names.
 
-```
-Add a topic called OrderManagement to the SalesAssistant agent:
-- Label: Order Management
-- Description: Handles all questions about customer orders, quotes, and order status
-- Scope: User questions about creating orders, checking order status, updating order quantities
-- Instructions: 1. Identify the order or account. 2. Check current status. 3. Take appropriate action.
+```json
+{
+  "topicName": "Account_Management",
+  "label": "Account Management",
+  "description": "Handle requests to create, update, or look up Account records in Salesforce CRM",
+  "scope": "This topic covers creating new company/account records, updating existing accounts, and looking up account information",
+  "instructions": [
+    "Collect the required company name from the user",
+    "Ask for optional details: industry, phone, website",
+    "Use the Create Account action to create the record",
+    "Confirm success by sharing the record ID with the user"
+  ],
+  "actions": ["Create_Account"]
+}
 ```
 
 ---
 
-## Step 3: Create a Flow for the Action
+## Step 4: Create Planner Bundle (`sf_create_agent_planner`)
+
+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.
 
-First, create the Flow that the agent will invoke:
+Create the planner **after** all topics exist.
 
+```json
+{
+  "plannerName": "CRM_Agent_Planner",
+  "label": "CRM Agent Planner",
+  "description": "Routes user requests to the appropriate CRM action topics",
+  "topicNames": ["Account_Management", "Lead_Management", "Opportunity_Management"]
+}
 ```
-Create an AutoLaunchedFlow called Get_Account_Orders that:
-- Takes an input variable accountId (String, isInput: true)
-- Queries related Order__c records using GetRecords
-- Returns them in an output variable orders (SObject collection, isOutput: true)
+
+---
+
+## Step 5: Create Agent (`sf_create_agent`)
+
+Create the Bot referencing the planner bundle name.
+
+```json
+{
+  "agentName": "CRM_Record_Creator",
+  "label": "CRM Record Creator",
+  "description": "Creates and manages CRM records based on user requests",
+  "type": "EinsteinCopilot",
+  "plannerName": "CRM_Agent_Planner"
+}
 ```
 
+Agent types:
+- `EinsteinCopilot` — internal employee-facing agent (shown in Lightning sidebar)
+- `ExternalCopilot` — customer-facing Agentforce Service Agent (for Experience Cloud / messaging)
+
 ---
 
-## Step 4: Link the Flow as an Agent Action
+## Step 6: Activate the Agent (`sf_activate_agent`)
 
+```json
+{
+  "agentApiName": "CRM_Record_Creator"
+}
 ```
-Create an agent action called GetOrders for the SalesAssistant agent's OrderManagement topic:
-- Type: Flow
-- Reference: Get_Account_Orders
-- Description: Retrieves all orders for a given account
-- Map input: accountId → {!Agent.Topic.Entities.accountId}
+
+---
+
+## Deactivating for Changes
+
+You must deactivate an agent before modifying its topics, actions, or planner:
+
+```json
+{ "agentApiName": "CRM_Record_Creator" }
 ```
 
+After making changes, re-activate with `sf_activate_agent`.
+
 ---
 
 ## End-to-End Example
 
-Full conversation to create a support agent:
+Full prompt sequence to create a CRM Record Creator agent:
 
 ```
-1. Create an Agentforce agent called SupportAgent with:
-   - Persona: "A friendly and efficient customer support representative"
-   - Tone: Formal
-   - Company: Acme Corp
-
-2. Add a topic CaseManagement to SupportAgent:
-   - Description: Handles customer support cases, status inquiries, and escalations
-   - Scope: Questions about case status, creating new cases, escalating urgent issues
-
-3. Create an AutoLaunchedFlow called Create_Support_Case with:
-   - Input variables: subject (String), description (String), contactId (String)
-   - A CreateRecords element creating a Case with these fields
-   - Output variable: caseId (String)
-
-4. Create an agent action CreateCase for SupportAgent.CaseManagement:
-   - Type: Flow
-   - Reference: Create_Support_Case
-   - Description: Creates a new support case for the customer
+1. Create AutoLaunchedFlow "Create_Account_Record":
+   - Input: AccountName (String, required), Industry (String), Phone (String)
+   - CreateRecords element → Account with those fields
+   - Output: AccountId (String)
+
+2. Create agent action "Create_Account":
+   - flowApiName: Create_Account_Record
+   - inputs: AccountName (Text, required), Industry (Text), Phone (Text)
+   - outputs: AccountId (Text)
+
+3. Create agent topic "Account_Management":
+   - description: "Handle requests to create Account records"
+   - scope: "Creating new company or organization accounts in Salesforce"
+   - instructions: ["Ask for company name", "Collect optional fields", "Call Create Account action", "Confirm the record ID"]
+   - actions: ["Create_Account"]
+
+4. Create planner "CRM_Agent_Planner":
+   - topicNames: ["Account_Management"]
+
+5. Create agent "CRM_Record_Creator":
+   - type: EinsteinCopilot
+   - plannerName: CRM_Agent_Planner
+
+6. Activate "CRM_Record_Creator"
 ```
 
 ---
 
-## Testing Your Agent
+## Debugging
 
-After creating all components:
+If the agent routes correctly but never invokes actions (agent says "I can't do that right now"):
 
-1. **Activate the agent** in Setup → Einstein Copilot → Your Agent → Activate
-2. **Open Copilot** in any Salesforce page (the lightning bolt icon)
-3. **Test a prompt:** "Show me all orders for Acme Corp"
+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).
 
-The agent should route to the OrderManagement topic and invoke the GetOrders action.
-
----
+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"`.
 
-## Tips
+3. **Check ConversationDefinitionEventLog** — Run SOQL:
+   ```sql
+   SELECT EventLabel, EventTarget, EventDetails
+   FROM ConversationDefinitionEventLog
+   WHERE LogDate = TODAY
+   ORDER BY EventDate DESC
+   LIMIT 50
+   ```
+   Look for `TopicClassificationSuccess` (routing worked) vs `ActionExecuted` (action ran).
 
-- **Be specific in topic descriptions** — the AI uses them to route requests
-- **Use clear action descriptions** — help the agent know when to invoke each action
-- **Start with Flows** — they're easiest to create and debug
-- **Test with narrow prompts first** — gradually expand scope
-- **Use variables consistently** — name them meaningfully for better AI reasoning
+4. **Verify planner exists** — If `TopicClassificationSuccess` never appears, the GenAiPlannerBundle may be missing. Use `sf_create_agent_planner` to create it.

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Changelog
 
+## [2.1.3] - 2026-05-28
+
+### Bug Fixes — Agentforce Action Invocation
+
+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).
+
+#### Root Cause: Missing GenAiFunction Schema Files
+
+`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."
+
+**Fix:** `sf_create_agent_action` now deploys a complete zip bundle containing:
+- `genAiFunctions/<Name>/<Name>.genAiFunction-meta.xml`
+- `genAiFunctions/<Name>/input/schema.json` — LLM-facing input parameter schema
+- `genAiFunctions/<Name>/output/schema.json` — LLM-facing output parameter schema
+
+Schema files use the correct Salesforce LightningTypeBundle format with `lightning:type`, `lightning:isPII`, `copilotAction:isUserInput`, `copilotAction:isDisplayable`, and `copilotAction:isUsedByPlanner` fields.
+
+#### Flow Variable Type Mismatch Fixed
+
+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."
+
+**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.
+
+#### `sf_create_agent_topic` Was Creating Wrong Metadata Type
+
+The tool was deploying `BotVersion` XML instead of `GenAiPlugin` XML.
+
+**Fix:** Replaced `buildBotVersionXml` with `buildGenAiPluginXml` that produces correct `GenAiPlugin` metadata with `pluginType`, `scope`, `canEscalate`, step-by-step `genAiPluginInstructions`, and `genAiFunctions` references.
+
+#### Added Missing Tools
+
+- `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.
+- `sf_activate_agent` — Activates an agent via REST API after configuration changes.
+- `sf_deactivate_agent` — Deactivates an agent (required before modifying topics/actions).
+
+#### API Version Updated
+
+Updated from `62.0` to `66.0` (current Salesforce API version for Agentforce metadata).
+
+#### Schema Corrections (`sf_create_agent`)
+
+- Removed invalid fields: `persona`, `tone`, `instructions`, `company` (not part of Bot metadata)
+- Fixed `type` enum from `["Default", "EinsteinCopilot"]` to `["EinsteinCopilot", "ExternalCopilot"]`
+- Added `agentTemplate: AiCopilot__AgentforceAgent` to Bot XML (required for proper action invocation wiring)
+
+#### Correct Creation Order Now Enforced
+
+The tool descriptions now document and enforce the correct metadata creation order:
+1. Create Flows (`sf_create_flow`) — AutoLaunchedFlows with `runInMode=SystemModeWithoutSharing`
+2. Create Actions (`sf_create_agent_action`) — GenAiFunction + schema files
+3. Create Topics (`sf_create_agent_topic`) — GenAiPlugin referencing actions
+4. Create Planner (`sf_create_agent_planner`) — GenAiPlannerBundle linking all topics
+5. Create Agent (`sf_create_agent`) — Bot referencing the planner
+6. Activate Agent (`sf_activate_agent`)
+
+---
+
 ## [2.0.0] - 2026-05-22
 
 ### Major Release — 60+ Tools

package/dist/index.d.ts

@@ -1,3 +1,2 @@
-#!/usr/bin/env node
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/schemas/index.js

@@ -858,37 +858,39 @@ export const CreateExperiencePageSchema = z.object({
 }).strict();
 // ─── AGENTFORCE ───────────────────────────────────────────────────────────────
 export const CreateAgentSchema = z.object({
-    agentName: z.string().min(1).max(80).regex(/^[A-Za-z][A-Za-z0-9_]*$/).describe("Agent API name, e.g. 'SupportAgent'"),
-    label: z.string().min(1).max(255).describe("Agent display name"),
-    description: z.string().max(1000).optional().describe("Agent description shown to users"),
-    type: z.enum(["Default", "EinsteinCopilot"]).default("EinsteinCopilot").describe("Agent type"),
-    company: z.string().max(255).optional().describe("Company name for the agent's context"),
-    persona: z.string().max(5000).optional().describe("Agent persona description, e.g. 'A helpful customer service representative'"),
-    tone: z.enum(["Formal", "Neutral", "Casual"]).default("Neutral").describe("Communication tone"),
-    instructions: z.string().max(10000).optional().describe("System-level instructions for the agent"),
+    agentName: z.string().min(1).max(80).regex(/^[A-Za-z][A-Za-z0-9_]*$/).describe("Agent API name, e.g. 'CRM_Record_Creator'. IMMUTABLE after creation."),
+    label: z.string().min(1).max(255).describe("Agent display label, e.g. 'CRM Record Creator'"),
+    description: z.string().max(1000).optional().describe("Agent description"),
+    type: z.enum(["EinsteinCopilot", "ExternalCopilot"]).default("EinsteinCopilot").describe("Bot type: 'EinsteinCopilot' for internal employee agents (shown in Lightning sidebar), 'ExternalCopilot' for customer-facing Agentforce Service Agents. CANNOT be changed after creation."),
 }).strict();
 export const CreateAgentTopicSchema = z.object({
-    agentName: z.string().min(1).max(80).describe("Parent agent API name"),
-    topicName: z.string().min(1).max(80).regex(/^[A-Za-z][A-Za-z0-9_]*$/).describe("Topic API name, e.g. 'OrderManagement'"),
-    label: z.string().min(1).max(255).describe("Topic label"),
-    description: z.string().min(1).max(5000).describe("What this topic covers"),
-    scope: z.string().min(1).max(5000).describe("Scope of this topic — what kind of requests it handles"),
-    instructions: z.string().max(10000).optional().describe("Step-by-step instructions for handling this topic"),
-    actions: z.array(z.string().max(80)).optional().describe("Action API names to associate with this topic"),
-}).strict();
+    topicName: z.string().min(1).max(80).regex(/^[A-Za-z][A-Za-z0-9_]*$/).describe("Topic API name, e.g. 'Create_Account_Topic'. Used as the GenAiPlugin developer name."),
+    label: z.string().min(1).max(255).describe("Topic display label, e.g. 'Create Account Topic'"),
+    description: z.string().min(1).max(5000).describe("Routing description — the LLM uses this to decide which topic handles a user request. Be specific, e.g. 'Use this topic when the user wants to create, add, or make a new Account or company record'"),
+    scope: z.string().min(1).max(5000).describe("What this topic covers in detail, e.g. 'Create new Account records with company name, industry, phone, and website'"),
+    instructions: z.array(z.string().max(2000)).optional().describe("Ordered step-by-step instructions for the agent, e.g. ['Ask the user for the account name', 'Call the Create Account action', 'Confirm success to the user']"),
+    actions: z.array(z.string().max(80)).optional().describe("Action API names (GenAiFunction developer names) to associate, e.g. ['Create_Account']. Create actions first with sf_create_agent_action."),
+}).strict();
+const AgentParamSchema = z.object({
+    name: z.string().max(80).describe("Parameter API name matching the flow variable name, e.g. 'AccountName'"),
+    label: z.string().max(255).describe("Human-readable label, e.g. 'Account Name'"),
+    description: z.string().max(1000).optional().describe("Description shown to the LLM, e.g. 'The name of the company or organization'"),
+    type: z.enum(["Text", "Number", "Currency", "Boolean", "Date", "DateTime", "TextArea"]).default("Text").describe("Data type — must match the flow variable type: 'Currency'/'Number' for numeric fields, 'Date' for date fields, 'Boolean' for checkboxes, 'Text' for everything else"),
+    required: z.boolean().default(true).describe("Whether this input is required"),
+});
 export const CreateAgentActionSchema = z.object({
-    agentName: z.string().min(1).max(80).describe("Parent agent API name"),
-    topicName: z.string().min(1).max(80).describe("Parent topic API name"),
-    actionName: z.string().min(1).max(80).regex(/^[A-Za-z][A-Za-z0-9_]*$/).describe("Action API name"),
-    label: z.string().min(1).max(255).describe("Action label"),
-    description: z.string().min(1).max(5000).describe("What this action does"),
-    type: z.enum(["Flow", "ApexClass", "PromptTemplate", "DataCategoryGroup", "ExternalService"])
-        .describe("Action type"),
-    reference: z.string().min(1).max(255).describe("API name of the Flow, Apex class, or Prompt Template to invoke"),
-    inputs: z.array(z.object({
-        name: z.string().max(255).describe("Input parameter name"),
-        value: z.string().max(1000).describe("Value or reference, e.g. '{!Agent.Topic.Entities.accountName}'"),
-    })).optional().describe("Input parameter mappings"),
+    actionName: z.string().min(1).max(80).regex(/^[A-Za-z][A-Za-z0-9_]*$/).describe("Action API name (GenAiFunction developer name), e.g. 'Create_Account'. Used to reference this action from topics."),
+    label: z.string().min(1).max(255).describe("Action display label, e.g. 'Create Account'"),
+    description: z.string().min(1).max(5000).describe("What this action does — the LLM uses this to decide when to invoke it. Be specific, e.g. 'Creates a new Account record in Salesforce with the given company name, industry, phone, and website'"),
+    flowApiName: z.string().min(1).max(255).describe("API name of the AutoLaunchedFlow to invoke, e.g. 'Create_Account_Record'. The flow must be Active and have runInMode=SystemModeWithoutSharing."),
+    inputs: z.array(AgentParamSchema).optional().describe("Flow input variables. Each input becomes a parameter the LLM collects from the user. Type MUST match the flow variable's data type."),
+    outputs: z.array(AgentParamSchema.omit({ required: true })).optional().describe("Flow output variables returned to the agent after execution, e.g. the created record ID"),
+}).strict();
+export const CreateAgentPlannerSchema = z.object({
+    plannerName: z.string().min(1).max(80).regex(/^[A-Za-z][A-Za-z0-9_]*$/).describe("Planner API name, e.g. 'CRM_Creator_Planner'. NOTE: Names are permanently reserved even after deletion — use a unique name."),
+    label: z.string().min(1).max(255).describe("Planner display label, e.g. 'CRM Creator Planner'"),
+    description: z.string().max(1000).optional().describe("Planner description"),
+    topicNames: z.array(z.string().min(1).max(80)).min(1).describe("Topic API names (GenAiPlugin developer names) to include, e.g. ['Create_Account_Topic', 'Create_Lead_Topic']. Topics must already exist."),
 }).strict();
 // ─── MCP SERVER MANAGEMENT ───────────────────────────────────────────────────
 export const CreateMcpServerSchema = z.object({

package/dist/services/deployment.js

@@ -64,6 +64,102 @@ export async function buildStaticResourceZip(resourceName, content, contentType,
     const buffer = await zip.generateAsync({ type: "nodebuffer" });
     return buffer.toString("base64");
 }
+export async function buildGenAiActionZip(params, apiVersion) {
+    const zip = new JSZip();
+    const functionName = params.actionName;
+    const packageXml = buildPackageXml([{ name: "GenAiFunction", members: [functionName] }], apiVersion);
+    zip.file("package.xml", packageXml);
+    // Build mappingAttributes XML
+    const inputsXml = (params.inputs ?? []).map(inp => `
+    <mappingAttributes>
+        <description>${escapeXml(inp.description ?? inp.label)}</description>
+        <label>${escapeXml(inp.label)}</label>
+        <name>${escapeXml(inp.name)}</name>
+        <parameterName>${escapeXml(inp.name)}</parameterName>
+        <parameterType>input</parameterType>
+    </mappingAttributes>`).join("\n");
+    const outputsXml = (params.outputs ?? []).map(out => `
+    <mappingAttributes>
+        <description>${escapeXml(out.description ?? out.label)}</description>
+        <label>${escapeXml(out.label)}</label>
+        <name>${escapeXml(out.name)}</name>
+        <parameterName>${escapeXml(out.name)}</parameterName>
+        <parameterType>output</parameterType>
+    </mappingAttributes>`).join("\n");
+    const functionXml = `<?xml version="1.0" encoding="UTF-8"?>
+<GenAiFunction xmlns="http://soap.sforce.com/2006/04/metadata">
+    <description>${escapeXml(params.description)}</description>
+    <invocationTarget>${escapeXml(params.flowApiName)}</invocationTarget>
+    <invocationTargetType>flow</invocationTargetType>
+    <isConfirmationRequired>false</isConfirmationRequired>
+    <masterLabel>${escapeXml(params.label)}</masterLabel>
+    ${inputsXml}
+    ${outputsXml}
+</GenAiFunction>`;
+    zip.file(`genAiFunctions/${functionName}/${functionName}.genAiFunction-meta.xml`, functionXml);
+    // Build input schema JSON
+    const inputSchemaProps = {};
+    const requiredInputs = [];
+    for (const inp of (params.inputs ?? [])) {
+        inputSchemaProps[inp.name] = {
+            "title": inp.label,
+            "description": inp.description ?? inp.label,
+            "lightning:type": lightningTypeFor(inp.type ?? "Text"),
+            "lightning:isPII": false,
+            "copilotAction:isUserInput": true
+        };
+        if (inp.required !== false) {
+            requiredInputs.push(inp.name);
+        }
+    }
+    const inputSchema = {
+        "required": requiredInputs.length > 0 ? requiredInputs : undefined,
+        "unevaluatedProperties": false,
+        "properties": inputSchemaProps,
+        "lightning:type": "lightning__objectType"
+    };
+    if (!inputSchema.required) {
+        delete inputSchema.required;
+    }
+    zip.file(`genAiFunctions/${functionName}/input/schema.json`, JSON.stringify(inputSchema, null, 2));
+    // Build output schema JSON
+    const outputSchemaProps = {};
+    for (const out of (params.outputs ?? [])) {
+        outputSchemaProps[out.name] = {
+            "title": out.label,
+            "description": out.description ?? out.label,
+            "lightning:type": lightningTypeFor(out.type ?? "Text"),
+            "lightning:isPII": false,
+            "copilotAction:isDisplayable": true,
+            "copilotAction:isUsedByPlanner": true
+        };
+    }
+    const outputSchema = {
+        "unevaluatedProperties": false,
+        "properties": outputSchemaProps,
+        "lightning:type": "lightning__objectType"
+    };
+    zip.file(`genAiFunctions/${functionName}/output/schema.json`, JSON.stringify(outputSchema, null, 2));
+    const buffer = await zip.generateAsync({ type: "nodebuffer" });
+    return buffer.toString("base64");
+}
+function escapeXml(s) {
+    return String(s ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+function lightningTypeFor(sfType) {
+    const t = sfType.toLowerCase();
+    if (t === "currency" || t === "number" || t === "double" || t === "integer" || t === "percent")
+        return "lightning__numberType";
+    if (t === "boolean" || t === "checkbox")
+        return "lightning__booleanType";
+    if (t === "date")
+        return "lightning__dateType";
+    if (t === "datetime")
+        return "lightning__dateTimeType";
+    if (t === "textarea" || t === "longtextarea" || t === "richtext")
+        return "lightning__textAreaType";
+    return "lightning__textType";
+}
 export async function buildGenericDeployZip(components, apiVersion) {
     const zip = new JSZip();
     const typeMap = new Map();

package/dist/services/salesforce.js

@@ -1,5 +1,5 @@
 import { execSync } from "child_process";
-export const API_VERSION = "62.0";
+export const API_VERSION = "66.0";
 // ─── Token cache ──────────────────────────────────────────────────────────────
 let cachedToken = null;
 const TOKEN_TTL_MS = 55 * 60 * 1000;
@@ -1212,26 +1212,50 @@ function buildBotXml(params) {
     <met:fullName>${x(params.agentName)}</met:fullName>
     <met:label>${x(params.label)}</met:label>
     ${params.description ? `<met:description>${x(params.description)}</met:description>` : ""}
-    <met:type>${x(params.type)}</met:type>
-    <met:status>Active</met:status>
-    ${params.company ? `<met:company>${x(params.company)}</met:company>` : ""}
-    ${params.persona ? `<met:persona>${x(params.persona)}</met:persona>` : ""}
-    <met:tone>${x(params.tone)}</met:tone>
-    ${params.instructions ? `<met:systemPrompt>${x(params.instructions)}</met:systemPrompt>` : ""}
+    <met:agentTemplate>AiCopilot__AgentforceAgent</met:agentTemplate>
+    <met:agentType>EinsteinServiceAgent</met:agentType>
+    <met:botSource>None</met:botSource>
+    <met:logPrivateConversationData>false</met:logPrivateConversationData>
+    <met:richContentEnabled>true</met:richContentEnabled>
+    <met:sessionTimeout>0</met:sessionTimeout>
+    <met:type>${x(params.type ?? "EinsteinCopilot")}</met:type>
   </met:metadata>`;
 }
-function buildBotVersionXml(params) {
-    const actionsXml = (params.actions ?? []).map(a => `
-    <met:botActions>
-      <met:botActionName>${x(a)}</met:botActionName>
-    </met:botActions>`).join("\n");
-    return `<met:metadata xsi:type="met:BotVersion" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
-    <met:fullName>${x(params.agentName)}.${x(params.topicName)}</met:fullName>
-    <met:label>${x(params.label)}</met:label>
+function buildGenAiPluginXml(params) {
+    const instructionsXml = (params.instructions ?? []).map((instr, i) => `
+    <met:genAiPluginInstructions>
+      <met:description>${x(instr)}</met:description>
+      <met:developerName>instruction_${i}</met:developerName>
+      <met:masterLabel>instruction_${i}</met:masterLabel>
+      <met:sortOrder>${i}</met:sortOrder>
+    </met:genAiPluginInstructions>`).join("\n");
+    const functionsXml = (params.actions ?? []).map(a => `
+    <met:genAiFunctions>
+      <met:functionName>${x(a)}</met:functionName>
+    </met:genAiFunctions>`).join("\n");
+    return `<met:metadata xsi:type="met:GenAiPlugin" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+    <met:fullName>${x(params.topicName)}</met:fullName>
+    <met:masterLabel>${x(params.label)}</met:masterLabel>
     <met:description>${x(params.description)}</met:description>
     <met:scope>${x(params.scope)}</met:scope>
-    ${params.instructions ? `<met:instructions>${x(params.instructions)}</met:instructions>` : ""}
-    ${actionsXml}
+    <met:pluginType>Topic</met:pluginType>
+    <met:canEscalate>false</met:canEscalate>
+    <met:language>en_US</met:language>
+    ${instructionsXml}
+    ${functionsXml}
+  </met:metadata>`;
+}
+function buildGenAiPlannerBundleXml(params) {
+    const pluginsXml = params.topicNames.map(t => `
+    <met:genAiPlugins>
+      <met:genAiPluginName>${x(t)}</met:genAiPluginName>
+    </met:genAiPlugins>`).join("\n");
+    return `<met:metadata xsi:type="met:GenAiPlannerBundle" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+    <met:fullName>${x(params.plannerName)}</met:fullName>
+    <met:masterLabel>${x(params.label)}</met:masterLabel>
+    ${params.description ? `<met:description>${x(params.description)}</met:description>` : ""}
+    <met:plannerType>AiCopilot__ReAct</met:plannerType>
+    ${pluginsXml}
   </met:metadata>`;
 }
 function buildMatchingRuleXml(params) {
@@ -1474,6 +1498,33 @@ export async function createAgent(auth, params) {
     return upsertMetadata(auth, buildBotXml(params));
 }
 export async function createAgentTopic(auth, params) {
-    return upsertMetadata(auth, buildBotVersionXml(params));
+    return upsertMetadata(auth, buildGenAiPluginXml(params));
+}
+export async function createAgentPlanner(auth, params) {
+    return upsertMetadata(auth, buildGenAiPlannerBundleXml(params));
+}
+export async function activateAgent(auth, agentApiName) {
+    try {
+        const resp = await fetchWithTimeout(`${auth.instanceUrl}/services/data/v${API_VERSION}/connect/einstein/copilot/${agentApiName}/activate`, { method: "POST", headers: { "Authorization": `Bearer ${auth.accessToken}`, "Content-Type": "application/json" } }, 30_000);
+        if (resp.ok)
+            return { success: true, message: `Agent '${agentApiName}' activated successfully.` };
+        const body = await resp.text().catch(() => "");
+        return { success: false, message: `Activation failed (HTTP ${resp.status}): ${body}` };
+    }
+    catch (err) {
+        return { success: false, message: sanitizeError(err instanceof Error ? err.message : String(err)) };
+    }
+}
+export async function deactivateAgent(auth, agentApiName) {
+    try {
+        const resp = await fetchWithTimeout(`${auth.instanceUrl}/services/data/v${API_VERSION}/connect/einstein/copilot/${agentApiName}/deactivate`, { method: "POST", headers: { "Authorization": `Bearer ${auth.accessToken}`, "Content-Type": "application/json" } }, 30_000);
+        if (resp.ok)
+            return { success: true, message: `Agent '${agentApiName}' deactivated successfully.` };
+        const body = await resp.text().catch(() => "");
+        return { success: false, message: `Deactivation failed (HTTP ${resp.status}): ${body}` };
+    }
+    catch (err) {
+        return { success: false, message: sanitizeError(err instanceof Error ? err.message : String(err)) };
+    }
 }
 //# sourceMappingURL=salesforce.js.map

package/dist/tools/agentforce.js

@@ -1,10 +1,21 @@
-import { CreateAgentSchema, CreateAgentTopicSchema, CreateAgentActionSchema } from "../schemas/index.js";
-import { getAuth, createAgent, createAgentTopic } from "../services/salesforce.js";
+import { CreateAgentSchema, CreateAgentTopicSchema, CreateAgentActionSchema, CreateAgentPlannerSchema } from "../schemas/index.js";
+import { getAuth, createAgent, createAgentTopic, createAgentPlanner, activateAgent, deactivateAgent, API_VERSION } from "../services/salesforce.js";
+import { buildGenAiActionZip, deployZip, pollDeployStatus } from "../services/deployment.js";
 import { resultContent } from "./utils.js";
 export function registerAgentforceTools(server) {
     server.registerTool("sf_create_agent", {
         title: "Create Agentforce Agent",
-        description: `Creates an Agentforce Agent (Einstein Copilot) in Salesforce using the Bot metadata type. An agent is an AI assistant that can understand natural language, reason about user intent, and take actions using topics and linked flows/actions. Specify the agent's persona, tone, and system-level instructions to shape its behavior and communication style.`,
+        description: `Creates an Agentforce Agent (Einstein Copilot / Service Agent) in Salesforce using the Bot metadata type.
+
+IMPORTANT: Follow this exact creation order for a fully working agent:
+1. Create flows (sf_create_flow) — the AutoLaunchedFlows that perform actions
+2. Create agent actions (sf_create_agent_action) — link each flow as a GenAiFunction
+3. Create agent topics (sf_create_agent_topic) — create GenAiPlugin topics referencing the actions
+4. Create agent planner (sf_create_agent_planner) — create GenAiPlannerBundle linking all topics
+5. Create agent (sf_create_agent) — create the Bot referencing the planner
+6. Activate the agent (sf_activate_agent)
+
+The agent type is IMMUTABLE after creation — choose carefully (EinsteinCopilot for internal, ExternalCopilot for customer-facing).`,
         inputSchema: CreateAgentSchema,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, async (params) => {
@@ -14,22 +25,20 @@ export function registerAgentforceTools(server) {
             label: params.label,
             description: params.description,
             type: params.type,
-            company: params.company,
-            persona: params.persona,
-            tone: params.tone,
-            instructions: params.instructions,
         });
         return resultContent(result);
     });
     server.registerTool("sf_create_agent_topic", {
-        title: "Create Agentforce Topic",
-        description: `Creates a Topic for an Agentforce Agent. Topics define areas of expertise — what types of user requests the agent can handle. Each topic has a description (what it covers), scope (what kinds of questions it answers), and optional step-by-step instructions for how the agent should respond. Topics are linked to Actions that the agent can execute.`,
+        title: "Create Agentforce Topic (GenAiPlugin)",
+        description: `Creates a Topic (GenAiPlugin) for an Agentforce Agent. Topics define the agent's areas of expertise — what types of user requests it handles. Each topic has a description (routing criteria), scope (what it covers), step-by-step instructions, and references to agent actions.
+
+Create topics AFTER creating agent actions (sf_create_agent_action) since topics reference actions by API name.
+Then create the planner bundle (sf_create_agent_planner) to link all topics to the agent.`,
         inputSchema: CreateAgentTopicSchema,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, async (params) => {
         const auth = await getAuth();
         const result = await createAgentTopic(auth, {
-            agentName: params.agentName,
             topicName: params.topicName,
             label: params.label,
             description: params.description,
@@ -40,34 +49,78 @@ export function registerAgentforceTools(server) {
         return resultContent(result);
     });
     server.registerTool("sf_create_agent_action", {
-        title: "Create Agentforce Action",
-        description: `Creates an Agentforce Action linked to a Flow, Apex class, or Prompt Template. Actions are the concrete steps an agent takes when handling a topic. The agent decides which action to invoke based on the user's request and the topic's instructions. Flow actions are the most common — create a Flow first, then link it as an agent action.`,
+        title: "Create Agentforce Action (GenAiFunction)",
+        description: `Creates an Agentforce Action (GenAiFunction) linked to a Flow. Actions are the concrete steps an agent takes when handling a topic. The LLM invokes actions based on the topic's instructions and the user's request.
+
+IMPORTANT: This deploys a complete GenAiFunction bundle including:
+- The GenAiFunction metadata (invocationTarget, invocationTargetType, mappingAttributes)
+- input/schema.json — the LLM-facing JSON schema for input parameters (REQUIRED for action invocation)
+- output/schema.json — the LLM-facing JSON schema for output parameters
+
+Without the schema files, the LLM cannot invoke the action. This tool handles all three files automatically.
+
+Create actions BEFORE topics (topics reference actions by API name).
+The referenced flow MUST exist and be Active with runInMode=SystemModeWithoutSharing.`,
         inputSchema: CreateAgentActionSchema,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, async (params) => {
         const auth = await getAuth();
         try {
-            // Agent actions are created via the GenAiPlanner/GenAiFunctionDef metadata
-            const { upsertMetadata, x } = await import("../services/salesforce.js");
-            const inputsXml = (params.inputs ?? []).map((inp) => `
-          <met:inputs>
-            <met:name>${x(inp.name)}</met:name>
-            <met:value>${x(inp.value)}</met:value>
-          </met:inputs>`).join("\n");
-            const xml = `<met:metadata xsi:type="met:GenAiFunction" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
-          <met:fullName>${x(params.agentName)}.${x(params.topicName)}.${x(params.actionName)}</met:fullName>
-          <met:masterLabel>${x(params.label)}</met:masterLabel>
-          <met:description>${x(params.description)}</met:description>
-          <met:type>${x(params.type)}</met:type>
-          <met:functionRef>${x(params.reference)}</met:functionRef>
-          ${inputsXml}
-        </met:metadata>`;
-            const result = await upsertMetadata(auth, xml);
+            const base64Zip = await buildGenAiActionZip({
+                actionName: params.actionName,
+                label: params.label,
+                description: params.description,
+                flowApiName: params.flowApiName,
+                inputs: params.inputs ?? [],
+                outputs: params.outputs ?? [],
+            }, API_VERSION);
+            const deployId = await deployZip(auth, base64Zip);
+            const result = await pollDeployStatus(auth, deployId, 120_000);
             return resultContent(result);
         }
         catch (err) {
             return resultContent({ success: false, message: err instanceof Error ? err.message : String(err) });
         }
     });
+    server.registerTool("sf_create_agent_planner", {
+        title: "Create Agentforce Planner Bundle (GenAiPlannerBundle)",
+        description: `Creates a GenAiPlannerBundle that connects topics to the agent's planning engine.
+
+The planner bundle is the CRITICAL link between the Bot and its topics (GenAiPlugins). Without it, the agent will have 0 topics visible and cannot route requests or invoke actions.
+
+Create the planner bundle AFTER creating all topics (sf_create_agent_topic) and BEFORE creating the agent (sf_create_agent).
+Then reference this planner's API name when calling sf_create_agent.`,
+        inputSchema: CreateAgentPlannerSchema,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (params) => {
+        const auth = await getAuth();
+        const result = await createAgentPlanner(auth, {
+            plannerName: params.plannerName,
+            label: params.label,
+            description: params.description,
+            topicNames: params.topicNames,
+        });
+        return resultContent(result);
+    });
+    server.registerTool("sf_activate_agent", {
+        title: "Activate Agentforce Agent",
+        description: `Activates an Agentforce Agent so it is available to users. The agent must be inactive (deactivated) before you can make configuration changes like adding/removing topics or actions. After making changes, re-activate with this tool.`,
+        inputSchema: { type: "object", properties: { agentApiName: { type: "string", description: "API name of the agent to activate, e.g. 'CRM_Record_Creator'" } }, required: ["agentApiName"] },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (params) => {
+        const auth = await getAuth();
+        const result = await activateAgent(auth, params.agentApiName);
+        return resultContent(result);
+    });
+    server.registerTool("sf_deactivate_agent", {
+        title: "Deactivate Agentforce Agent",
+        description: `Deactivates an Agentforce Agent so configuration changes can be made. You must deactivate an agent before modifying its topics, actions, or planner configuration. After making changes, re-activate with sf_activate_agent.`,
+        inputSchema: { type: "object", properties: { agentApiName: { type: "string", description: "API name of the agent to deactivate, e.g. 'CRM_Record_Creator'" } }, required: ["agentApiName"] },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (params) => {
+        const auth = await getAuth();
+        const result = await deactivateAgent(auth, params.agentApiName);
+        return resultContent(result);
+    });
 }
-//# sourceMappingURL=agentforce.js.map
+//# sourceMappingURL=agentforce.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "salesforce-metadata-mcp",
-  "version": "2.1.2",
+  "version": "2.1.3",
   "description": "The most comprehensive Salesforce metadata and development MCP server: 60+ tools for custom objects, flows, Apex, LWC, Agentforce, deployments, and more",
   "license": "MIT",
   "private": false,