salesforce-metadata-mcp 2.1.3 → 2.1.4

package/AGENTFORCE.md

@@ -167,6 +167,124 @@ You must deactivate an agent before modifying its topics, actions, or planner:
 
 After making changes, re-activate with `sf_activate_agent`.
 
+> **Note:** `sf_update_agent_topic` handles deactivate/reactivate automatically.
+
+---
+
+## Listing and Inspecting Agents
+
+### List all agents (`sf_list_agents`)
+
+No parameters required. Returns all agents with status:
+
+```
+sf_list_agents → { agents: [{ apiName, label, status, lastModifiedDate }] }
+```
+
+### Get full agent config (`sf_get_agent`)
+
+```json
+{ "agentApiName": "CRM_Record_Creator" }
+```
+
+Returns activation status, all topics (GenAiPlugin), actions (GenAiFunction), and planner bundles (GenAiPlannerBundle) in the org.
+
+---
+
+## Updating Topics and Actions
+
+### Update a topic in-place (`sf_update_agent_topic`)
+
+Automatically deactivates the agent, updates the GenAiPlugin, then reactivates:
+
+```json
+{
+  "agentApiName": "CRM_Record_Creator",
+  "topicName": "Account_Management",
+  "label": "Account Management",
+  "description": "Handle requests to create, update, or find Account records",
+  "scope": "Creating, updating, or looking up company/account information",
+  "instructions": ["Ask for company name", "Collect optional fields", "Call the appropriate action", "Confirm success"],
+  "actions": ["Create_Account", "Update_Account"],
+  "escalationEnabled": false
+}
+```
+
+### Update an action (`sf_update_agent_action`)
+
+Redeploys the GenAiFunction bundle with new schema files:
+
+```json
+{
+  "actionName": "Create_Account",
+  "label": "Create Account",
+  "description": "Creates a new Account record with company name, industry, phone, and website",
+  "invocationTargetType": "Flow",
+  "flowApiName": "Create_Account_Record_v2",
+  "inputs": [
+    { "name": "AccountName", "label": "Account Name", "type": "Text", "required": true },
+    { "name": "AnnualRevenue", "label": "Annual Revenue", "type": "Currency", "required": false }
+  ],
+  "outputs": [
+    { "name": "AccountId", "label": "Account ID", "type": "Text" }
+  ]
+}
+```
+
+### Apex-backed actions
+
+Set `invocationTargetType: "ApexClass"` and provide `apexClassName` instead of `flowApiName`:
+
+```json
+{
+  "actionName": "Search_Knowledge",
+  "label": "Search Knowledge Base",
+  "description": "Searches the knowledge base for articles matching the query",
+  "invocationTargetType": "ApexClass",
+  "apexClassName": "KnowledgeSearchAction",
+  "inputs": [{ "name": "searchQuery", "label": "Search Query", "type": "Text", "required": true }],
+  "outputs": [{ "name": "articleBody", "label": "Article Body", "type": "TextArea" }]
+}
+```
+
+---
+
+## Deleting Agents (`sf_delete_agent`)
+
+```json
+{
+  "agentApiName": "CRM_Record_Creator",
+  "deleteTopics": true,
+  "deleteActions": true
+}
+```
+
+- `deleteTopics: true` — also deletes the agent's GenAiPlugin topics (discovered via the planner bundle)
+- `deleteActions: true` — also deletes the GenAiFunction actions referenced by those topics
+- Without flags, only the Bot and GenAiPlannerBundle are deleted
+
+**WARNING:** Deleted topics and actions affect all agents that reference them.
+
+---
+
+## Testing Agents (`sf_test_agent`)
+
+Send a test message without opening the Salesforce UI:
+
+```json
+{
+  "agentApiName": "CRM_Record_Creator",
+  "message": "Create an account called Acme Corp in the Technology industry"
+}
+```
+
+Returns:
+- `response` — the agent's reply text
+- `sessionId` — the session created (for follow-up messages)
+- `success` — whether the full API round-trip succeeded
+
+The agent must be **Active** before testing.
+
 ---
 
 ## End-to-End Example
@@ -210,7 +328,11 @@ If the agent routes correctly but never invokes actions (agent says "I can't do
 
 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"`.
 
-3. **Check ConversationDefinitionEventLog** — Run SOQL:
+3. **Use `sf_get_agent_logs`** — Queries ConversationDefinitionEventLog automatically:
+   ```json
+   { "agentApiName": "CRM_Record_Creator", "limit": 50, "hoursBack": 2 }
+   ```
+   Or run SOQL manually:
    ```sql
    SELECT EventLabel, EventTarget, EventDetails
    FROM ConversationDefinitionEventLog
@@ -221,3 +343,5 @@ If the agent routes correctly but never invokes actions (agent says "I can't do
    Look for `TopicClassificationSuccess` (routing worked) vs `ActionExecuted` (action ran).
 
 4. **Verify planner exists** — If `TopicClassificationSuccess` never appears, the GenAiPlannerBundle may be missing. Use `sf_create_agent_planner` to create it.
+
+5. **Use `sf_test_agent`** — Send a test message programmatically and inspect the response without opening the Salesforce UI.

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## [2.1.4] - 2026-05-28
+
+### New Tools — Agentforce CRUD & Debugging
+
+#### Read
+- `sf_get_agent` — Retrieve full agent configuration from org including activation status, all topics (GenAiPlugin), actions (GenAiFunction), and planner bundles (GenAiPlannerBundle)
+- `sf_list_agents` — List all Agentforce agents in the org with name, label, activation status, and last modified date
+
+#### Update
+- `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.
+- `sf_update_agent_action` — Update an existing GenAiFunction and regenerate its LLM-facing schema files via zip deploy. All provided fields replace existing values.
+
+#### Delete
+- `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.
+
+#### Test & Debug
+- `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.
+- `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.
+
+### Enhanced Existing Tools
+
+#### `sf_create_agent`
+- Added `systemPrompt` optional param — custom system prompt injected into every conversation
+- Added `openingMessage` optional param — welcome message shown when users first open the agent
+
+#### `sf_create_agent_action` / `sf_update_agent_action`
+- Added `invocationTargetType` param (`"Flow"` | `"ApexClass"`, default `"Flow"`) — support for Apex class actions in addition to AutoLaunchedFlows
+- Added `apexClassName` optional param — Apex class API name for ApexClass-backed actions
+- `flowApiName` is now optional (required only when `invocationTargetType` is `"Flow"`)
+
+#### `sf_create_agent_topic` / `sf_update_agent_topic`
+- Added `escalationEnabled` optional boolean — sets `canEscalate` on the GenAiPlugin (allows human agent escalation)
+- Added `fallbackTopic` optional string — API name of a fallback GenAiPlugin topic
+
+#### `sf_create_agent_planner`
+- Added `dataLibraryName` optional param — API name of a Data Library (Knowledge Base) for Knowledge-grounded agents
+
+### New SOAP Helpers (internal)
+- `readMetadataItem(type, fullName)` — SOAP readMetadata for a single component
+- `listMetadataType(type)` — SOAP listMetadata for all components of a type
+- `deleteMetadataItems(type, fullNames[])` — SOAP deleteMetadata for one or more components
+
+---
+
 ## [2.1.3] - 2026-05-28
 
 ### Bug Fixes — Agentforce Action Invocation

package/dist/schemas/index.js

@@ -862,6 +862,8 @@ export const CreateAgentSchema = z.object({
     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."),
+    systemPrompt: z.string().max(32000).optional().describe("Custom system prompt to override the agent's default behavior and persona. Injected into the agent's context before every conversation."),
+    openingMessage: z.string().max(2000).optional().describe("Welcome message shown to users when they first open the agent (set as welcomeMessage on the Bot)."),
 }).strict();
 export const CreateAgentTopicSchema = z.object({
     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."),
@@ -870,6 +872,8 @@ export const CreateAgentTopicSchema = z.object({
     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."),
+    escalationEnabled: z.boolean().optional().describe("Whether this topic can escalate to a human agent (sets canEscalate on GenAiPlugin). Default: false."),
+    fallbackTopic: z.string().max(80).optional().describe("API name of another GenAiPlugin topic to fall back to if this topic cannot handle the request."),
 }).strict();
 const AgentParamSchema = z.object({
     name: z.string().max(80).describe("Parameter API name matching the flow variable name, e.g. 'AccountName'"),
@@ -882,15 +886,58 @@ export const CreateAgentActionSchema = z.object({
     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"),
+    invocationTargetType: z.enum(["Flow", "ApexClass"]).default("Flow").describe("Type of backend to invoke: 'Flow' for AutoLaunchedFlow (most common), 'ApexClass' for an Apex class implementing InvocableMethod."),
+    flowApiName: z.string().max(255).optional().describe("API name of the AutoLaunchedFlow to invoke (required when invocationTargetType is Flow). Must be Active with runInMode=SystemModeWithoutSharing."),
+    apexClassName: z.string().max(255).optional().describe("API name of the Apex class to invoke (required when invocationTargetType is ApexClass). Class must have an @InvocableMethod."),
+    inputs: z.array(AgentParamSchema).optional().describe("Input parameters. Each becomes a parameter the LLM collects from the user. Type MUST match the flow variable / Apex param type."),
+    outputs: z.array(AgentParamSchema.omit({ required: true })).optional().describe("Output parameters 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."),
+    dataLibraryName: z.string().max(80).optional().describe("API name of a Data Library (Knowledge Base) to attach to this planner for Knowledge-grounded agents."),
+}).strict();
+export const GetAgentSchema = z.object({
+    agentApiName: z.string().min(1).max(80).describe("Agent API name, e.g. 'CRM_Record_Creator'"),
+}).strict();
+export const UpdateAgentTopicSchema = z.object({
+    agentApiName: z.string().min(1).max(80).describe("API name of the agent that owns this topic. The agent is automatically deactivated before the update and reactivated after."),
+    topicName: z.string().min(1).max(80).regex(/^[A-Za-z][A-Za-z0-9_]*$/).describe("Topic API name to update (GenAiPlugin developer name)"),
+    label: z.string().min(1).max(255).describe("Updated topic display label"),
+    description: z.string().min(1).max(5000).describe("Updated routing description"),
+    scope: z.string().min(1).max(5000).describe("Updated scope"),
+    instructions: z.array(z.string().max(2000)).optional().describe("Updated step-by-step instructions (replaces existing)"),
+    actions: z.array(z.string().max(80)).optional().describe("Updated action API names (replaces existing)"),
+    escalationEnabled: z.boolean().optional().describe("Whether this topic can escalate to a human agent"),
+    fallbackTopic: z.string().max(80).optional().describe("API name of fallback topic"),
+}).strict();
+export const UpdateAgentActionSchema = z.object({
+    actionName: z.string().min(1).max(80).regex(/^[A-Za-z][A-Za-z0-9_]*$/).describe("Action API name to update (GenAiFunction developer name)"),
+    label: z.string().min(1).max(255).describe("Updated action display label"),
+    description: z.string().min(1).max(5000).describe("Updated action description"),
+    invocationTargetType: z.enum(["Flow", "ApexClass"]).default("Flow").describe("Type of backend to invoke"),
+    flowApiName: z.string().max(255).optional().describe("API name of the AutoLaunchedFlow (required if invocationTargetType is Flow)"),
+    apexClassName: z.string().max(255).optional().describe("API name of the Apex class (required if invocationTargetType is ApexClass)"),
+    inputs: z.array(AgentParamSchema).optional().describe("Updated input parameters (replaces existing)"),
+    outputs: z.array(AgentParamSchema.omit({ required: true })).optional().describe("Updated output parameters (replaces existing)"),
+}).strict();
+export const DeleteAgentSchema = z.object({
+    agentApiName: z.string().min(1).max(80).describe("API name of the agent to delete, e.g. 'CRM_Record_Creator'"),
+    deleteTopics: z.boolean().default(false).describe("If true, also deletes the agent's GenAiPlugin topics (identified via its GenAiPlannerBundle)"),
+    deleteActions: z.boolean().default(false).describe("If true, also deletes the GenAiFunction actions referenced by the agent's topics"),
+}).strict();
+export const ListAgentsSchema = z.object({}).strict();
+export const TestAgentSchema = z.object({
+    agentApiName: z.string().min(1).max(80).describe("API name of the agent to test, e.g. 'CRM_Record_Creator'"),
+    message: z.string().min(1).max(5000).describe("Test message to send to the agent, e.g. 'Create an account called Acme Corp'"),
+    orgUrl: z.string().url().optional().describe("Override the Agentforce bootstrap URL (defaults to SF_INSTANCE_URL). Required only if your My Domain URL differs from the instance URL."),
+}).strict();
+export const GetAgentLogsSchema = z.object({
+    agentApiName: z.string().max(80).optional().describe("Filter logs by agent API name (optional — omit to see all agent activity in the org)"),
+    limit: z.number().int().min(1).max(200).default(20).describe("Maximum number of log entries to return (default: 20)"),
+    hoursBack: z.number().min(0.1).max(24).default(1).describe("How many hours back to look (default: 1 hour)"),
 }).strict();
 // ─── MCP SERVER MANAGEMENT ───────────────────────────────────────────────────
 export const CreateMcpServerSchema = z.object({

package/dist/services/deployment.js

@@ -86,11 +86,14 @@ export async function buildGenAiActionZip(params, apiVersion) {
         <parameterName>${escapeXml(out.name)}</parameterName>
         <parameterType>output</parameterType>
     </mappingAttributes>`).join("\n");
+    const isApex = params.invocationTargetType === "ApexClass";
+    const invocationTarget = isApex ? (params.apexClassName ?? "") : (params.flowApiName ?? "");
+    const invocationTargetType = isApex ? "apexClass" : "flow";
     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>
+    <invocationTarget>${escapeXml(invocationTarget)}</invocationTarget>
+    <invocationTargetType>${invocationTargetType}</invocationTargetType>
     <isConfirmationRequired>false</isConfirmationRequired>
     <masterLabel>${escapeXml(params.label)}</masterLabel>
     ${inputsXml}

package/dist/services/salesforce.js

@@ -1219,6 +1219,8 @@ function buildBotXml(params) {
     <met:richContentEnabled>true</met:richContentEnabled>
     <met:sessionTimeout>0</met:sessionTimeout>
     <met:type>${x(params.type ?? "EinsteinCopilot")}</met:type>
+    ${params.systemPrompt ? `<met:systemPrompt>${x(params.systemPrompt)}</met:systemPrompt>` : ""}
+    ${params.openingMessage ? `<met:welcomeMessage>${x(params.openingMessage)}</met:welcomeMessage>` : ""}
   </met:metadata>`;
 }
 function buildGenAiPluginXml(params) {
@@ -1239,8 +1241,9 @@ function buildGenAiPluginXml(params) {
     <met:description>${x(params.description)}</met:description>
     <met:scope>${x(params.scope)}</met:scope>
     <met:pluginType>Topic</met:pluginType>
-    <met:canEscalate>false</met:canEscalate>
+    <met:canEscalate>${params.escalationEnabled === true ? "true" : "false"}</met:canEscalate>
     <met:language>en_US</met:language>
+    ${params.fallbackTopic ? `<met:fallbackPlugin>${x(params.fallbackTopic)}</met:fallbackPlugin>` : ""}
     ${instructionsXml}
     ${functionsXml}
   </met:metadata>`;
@@ -1250,11 +1253,16 @@ function buildGenAiPlannerBundleXml(params) {
     <met:genAiPlugins>
       <met:genAiPluginName>${x(t)}</met:genAiPluginName>
     </met:genAiPlugins>`).join("\n");
+    const dataLibXml = params.dataLibraryName ? `
+    <met:dataLibraries>
+      <met:dataLibraryName>${x(params.dataLibraryName)}</met:dataLibraryName>
+    </met:dataLibraries>` : "";
     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>
+    ${dataLibXml}
     ${pluginsXml}
   </met:metadata>`;
 }
@@ -1527,4 +1535,328 @@ export async function deactivateAgent(auth, agentApiName) {
         return { success: false, message: sanitizeError(err instanceof Error ? err.message : String(err)) };
     }
 }
+// ─── Metadata read/list/delete helpers ───────────────────────────────────────
+export async function readMetadataItem(auth, type, fullName) {
+    const body = `<met:readMetadata>
+      <met:type>${type}</met:type>
+      <met:fullNames>${x(fullName)}</met:fullNames>
+    </met:readMetadata>`;
+    try {
+        const xml = await callMetadataSoap(auth, "readMetadata", body);
+        const error = extractSoapError(xml);
+        if (error)
+            return { success: false, message: error };
+        return { success: true, rawXml: xml };
+    }
+    catch (err) {
+        return { success: false, message: sanitizeError(err instanceof Error ? err.message : String(err)) };
+    }
+}
+export async function listMetadataType(auth, type) {
+    const body = `<met:listMetadata>
+      <met:queries><met:type>${x(type)}</met:type></met:queries>
+      <met:asOfVersion>${API_VERSION}</met:asOfVersion>
+    </met:listMetadata>`;
+    try {
+        const xml = await callMetadataSoap(auth, "listMetadata", body);
+        const error = extractSoapError(xml);
+        if (error)
+            return { success: false, message: error, items: [] };
+        const items = [];
+        for (const block of [...xml.matchAll(/<result>([\s\S]*?)<\/result>/gi)]) {
+            const inner = block[1];
+            const fullNameMatch = inner.match(/<fullName[^>]*>([\s\S]*?)<\/fullName>/i);
+            if (fullNameMatch) {
+                const labelMatch = inner.match(/<label[^>]*>([\s\S]*?)<\/label>/i);
+                const lastModifiedMatch = inner.match(/<lastModifiedDate[^>]*>([\s\S]*?)<\/lastModifiedDate>/i);
+                items.push({
+                    fullName: fullNameMatch[1].trim(),
+                    label: labelMatch?.[1].trim() ?? "",
+                    lastModifiedDate: lastModifiedMatch?.[1].trim() ?? "",
+                    type,
+                });
+            }
+        }
+        return { success: true, items };
+    }
+    catch (err) {
+        return { success: false, message: sanitizeError(err instanceof Error ? err.message : String(err)), items: [] };
+    }
+}
+export async function deleteMetadataItems(auth, type, fullNames) {
+    if (fullNames.length === 0)
+        return { success: true, deleted: [], message: "Nothing to delete" };
+    const fullNamesXml = fullNames.map(n => `<met:fullNames>${x(n)}</met:fullNames>`).join("\n");
+    const body = `<met:deleteMetadata>
+      <met:type>${x(type)}</met:type>
+      ${fullNamesXml}
+    </met:deleteMetadata>`;
+    try {
+        const xml = await callMetadataSoap(auth, "deleteMetadata", body);
+        const error = extractSoapError(xml);
+        if (error)
+            return { success: false, message: error, deleted: [] };
+        const deleted = [];
+        const errors = [];
+        for (const block of [...xml.matchAll(/<result>([\s\S]*?)<\/result>/gi)]) {
+            const inner = block[1];
+            const fullNameMatch = inner.match(/<fullName[^>]*>([\s\S]*?)<\/fullName>/i);
+            const successMatch = inner.match(/<success>(true|false)<\/success>/i);
+            const fnName = fullNameMatch?.[1].trim() ?? "";
+            if (successMatch?.[1] === "true") {
+                deleted.push(fnName);
+            }
+            else {
+                const msgMatch = inner.match(/<message[^>]*>([\s\S]*?)<\/message>/i);
+                errors.push(`${fnName}: ${msgMatch?.[1].trim() ?? "Unknown error"}`);
+            }
+        }
+        return {
+            success: errors.length === 0,
+            deleted,
+            message: deleted.length > 0 ? `Deleted: ${deleted.join(", ")}` : "Nothing deleted",
+            ...(errors.length > 0 ? { errors } : {}),
+        };
+    }
+    catch (err) {
+        return { success: false, message: sanitizeError(err instanceof Error ? err.message : String(err)), deleted: [] };
+    }
+}
+// ─── Agentforce query/management functions ────────────────────────────────────
+export async function getAgent(auth, agentApiName) {
+    try {
+        let status = "Unknown";
+        const statusResp = await fetchWithTimeout(`${auth.instanceUrl}/services/data/v${API_VERSION}/connect/einstein/copilot/${agentApiName}`, { method: "GET", headers: { "Authorization": `Bearer ${auth.accessToken}`, "Content-Type": "application/json" } }, 15_000).catch(() => null);
+        if (statusResp?.ok) {
+            const data = await statusResp.json().catch(() => ({}));
+            status = data.status ?? data.botStatus ?? "Unknown";
+        }
+        const [botResult, pluginList, funcList, plannerList] = await Promise.all([
+            readMetadataItem(auth, "Bot", agentApiName),
+            listMetadataType(auth, "GenAiPlugin"),
+            listMetadataType(auth, "GenAiFunction"),
+            listMetadataType(auth, "GenAiPlannerBundle"),
+        ]);
+        return {
+            success: true,
+            agent: { apiName: agentApiName, status, metadataFound: botResult.success },
+            topics: pluginList.items,
+            actions: funcList.items,
+            planners: plannerList.items,
+            message: `Agent '${agentApiName}' — status: ${status}, ${pluginList.items.length} topic(s), ${funcList.items.length} action(s), ${plannerList.items.length} planner(s).`,
+        };
+    }
+    catch (err) {
+        return { success: false, message: sanitizeError(err instanceof Error ? err.message : String(err)) };
+    }
+}
+export async function listAgents(auth) {
+    try {
+        const botList = await listMetadataType(auth, "Bot");
+        if (!botList.success)
+            return { success: false, message: botList.message ?? "Failed to list agents", agents: [] };
+        const agents = [];
+        for (const bot of botList.items) {
+            let status = "Unknown";
+            const resp = await fetchWithTimeout(`${auth.instanceUrl}/services/data/v${API_VERSION}/connect/einstein/copilot/${bot.fullName}`, { method: "GET", headers: { "Authorization": `Bearer ${auth.accessToken}` } }, 10_000).catch(() => null);
+            if (resp?.ok) {
+                const data = await resp.json().catch(() => ({}));
+                status = data.status ?? data.botStatus ?? "Unknown";
+            }
+            agents.push({ apiName: bot.fullName, label: bot.label, status, lastModifiedDate: bot.lastModifiedDate });
+        }
+        return { success: true, agents, message: `Found ${agents.length} agent(s).` };
+    }
+    catch (err) {
+        return { success: false, message: sanitizeError(err instanceof Error ? err.message : String(err)), agents: [] };
+    }
+}
+export async function updateAgentTopic(auth, params, agentApiName) {
+    try {
+        if (agentApiName) {
+            const deactResult = await deactivateAgent(auth, agentApiName);
+            if (!deactResult.success)
+                console.error(`Warning: deactivation returned: ${deactResult.message}`);
+        }
+        const result = await upsertMetadata(auth, buildGenAiPluginXml(params));
+        if (agentApiName) {
+            const actResult = await activateAgent(auth, agentApiName);
+            if (!actResult.success)
+                return { ...result, warning: `Topic updated but agent reactivation failed: ${actResult.message}` };
+        }
+        return result;
+    }
+    catch (err) {
+        if (agentApiName)
+            await activateAgent(auth, agentApiName).catch(() => { });
+        return { success: false, message: sanitizeError(err instanceof Error ? err.message : String(err)) };
+    }
+}
+export async function deleteAgent(auth, params) {
+    const deleted = [];
+    const errors = [];
+    try {
+        await deactivateAgent(auth, params.agentApiName).catch(() => { });
+        const botRead = await readMetadataItem(auth, "Bot", params.agentApiName);
+        let topicsToDelete = [];
+        let actionsToDelete = [];
+        let plannerToDelete = null;
+        if (botRead.success && botRead.rawXml) {
+            const plannerMatch = botRead.rawXml.match(/<plannerBundle[^>]*>([\s\S]*?)<\/plannerBundle>/i)
+                || botRead.rawXml.match(/<plannerBundleName[^>]*>([\s\S]*?)<\/plannerBundleName>/i);
+            if (plannerMatch)
+                plannerToDelete = plannerMatch[1].trim();
+        }
+        if ((params.deleteTopics || params.deleteActions) && plannerToDelete) {
+            const plannerRead = await readMetadataItem(auth, "GenAiPlannerBundle", plannerToDelete);
+            if (plannerRead.success && plannerRead.rawXml) {
+                topicsToDelete = [...plannerRead.rawXml.matchAll(/<genAiPluginName[^>]*>([\s\S]*?)<\/genAiPluginName>/gi)].map(m => m[1].trim());
+                if (params.deleteActions) {
+                    for (const topicName of topicsToDelete) {
+                        const topicRead = await readMetadataItem(auth, "GenAiPlugin", topicName);
+                        if (topicRead.success && topicRead.rawXml) {
+                            const actionNames = [...topicRead.rawXml.matchAll(/<functionName[^>]*>([\s\S]*?)<\/functionName>/gi)].map(m => m[1].trim());
+                            actionsToDelete.push(...actionNames);
+                        }
+                    }
+                    actionsToDelete = [...new Set(actionsToDelete)];
+                }
+            }
+        }
+        if (actionsToDelete.length > 0) {
+            const res = await deleteMetadataItems(auth, "GenAiFunction", actionsToDelete);
+            deleted.push(...(res.deleted ?? []));
+            if (res.errors)
+                errors.push(...res.errors);
+        }
+        if (topicsToDelete.length > 0) {
+            const res = await deleteMetadataItems(auth, "GenAiPlugin", topicsToDelete);
+            deleted.push(...(res.deleted ?? []));
+            if (res.errors)
+                errors.push(...res.errors);
+        }
+        if (plannerToDelete) {
+            const res = await deleteMetadataItems(auth, "GenAiPlannerBundle", [plannerToDelete]);
+            deleted.push(...(res.deleted ?? []));
+            if (res.errors)
+                errors.push(...res.errors);
+        }
+        const botRes = await deleteMetadataItems(auth, "Bot", [params.agentApiName]);
+        deleted.push(...(botRes.deleted ?? []));
+        if (botRes.errors)
+            errors.push(...botRes.errors);
+        return {
+            success: errors.length === 0,
+            deleted,
+            message: `Deleted ${deleted.length} component(s)${deleted.length > 0 ? ": " + deleted.join(", ") : ""}.`,
+            ...(errors.length > 0 ? { errors } : {}),
+        };
+    }
+    catch (err) {
+        return { success: false, message: sanitizeError(err instanceof Error ? err.message : String(err)), deleted };
+    }
+}
+export async function testAgent(auth, params) {
+    try {
+        const orgUrl = (params.orgUrl ?? auth.instanceUrl).replace(/\/$/, "");
+        const externalSessionKey = `mcp_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+        const bootstrapResp = await fetchWithTimeout(`${orgUrl}/agentforce/bootstrap/nameduser`, {
+            method: "POST",
+            headers: { "Authorization": `Bearer ${auth.accessToken}`, "Content-Type": "application/json" },
+            body: JSON.stringify({ botApiName: params.agentApiName, externalSessionKey, forceConfig: { endpoint: orgUrl } }),
+        }, 30_000);
+        if (!bootstrapResp.ok) {
+            const body = await bootstrapResp.text().catch(() => "");
+            return { success: false, message: `Bootstrap failed (HTTP ${bootstrapResp.status}): ${body.slice(0, 400)}` };
+        }
+        const bootstrap = await bootstrapResp.json();
+        const agentToken = bootstrap.token;
+        const agentUrl = (bootstrap.agentUrl ?? "").replace(/\/$/, "");
+        if (!agentToken || !agentUrl)
+            return { success: false, message: `Bootstrap missing token or agentUrl. Response: ${JSON.stringify(bootstrap).slice(0, 300)}` };
+        const sessionResp = await fetchWithTimeout(`${agentUrl}/sessions`, {
+            method: "POST",
+            headers: { "Authorization": `Bearer ${agentToken}`, "Content-Type": "application/json", "x-sfdc-app-context": "EinsteinGPT", "x-client-feature-id": "ai-platform-einstein-gpt" },
+            body: JSON.stringify({ externalSessionKey, instanceConfig: { endpoint: orgUrl } }),
+        }, 30_000);
+        if (!sessionResp.ok) {
+            const body = await sessionResp.text().catch(() => "");
+            return { success: false, message: `Session creation failed (HTTP ${sessionResp.status}): ${body.slice(0, 400)}` };
+        }
+        const sessionData = await sessionResp.json();
+        const sessionId = sessionData.sessionId ?? sessionData.id;
+        if (!sessionId)
+            return { success: false, message: `No sessionId in response: ${JSON.stringify(sessionData).slice(0, 300)}` };
+        const msgResp = await fetchWithTimeout(`${agentUrl}/sessions/${sessionId}/messages`, {
+            method: "POST",
+            headers: { "Authorization": `Bearer ${agentToken}`, "Content-Type": "application/json", "x-sfdc-app-context": "EinsteinGPT", "x-client-feature-id": "ai-platform-einstein-gpt" },
+            body: JSON.stringify({ message: { role: "user", content: [{ type: "text", text: params.message }] }, variables: [] }),
+        }, 90_000);
+        if (!msgResp.ok) {
+            const body = await msgResp.text().catch(() => "");
+            return { success: false, sessionId, message: `Message failed (HTTP ${msgResp.status}): ${body.slice(0, 400)}` };
+        }
+        const msgData = await msgResp.json();
+        const messages = msgData.messages ?? msgData.result?.messages ?? [];
+        const responseText = messages
+            .filter(m => m.type === "Reply" || m.role === "agent")
+            .map(m => {
+            if (typeof m.message === "string")
+                return m.message;
+            if (Array.isArray(m.content))
+                return m.content.map(c => c.text ?? "").join("");
+            return m.text ?? "";
+        })
+            .filter(Boolean)
+            .join("\n")
+            .trim();
+        return {
+            success: true,
+            sessionId,
+            response: responseText || JSON.stringify(msgData).slice(0, 1000),
+            message: responseText ? "Agent responded successfully." : "Message sent successfully.",
+        };
+    }
+    catch (err) {
+        return { success: false, message: sanitizeError(err instanceof Error ? err.message : String(err)) };
+    }
+}
+export async function getAgentLogs(auth, params) {
+    try {
+        const client = createClient(auth);
+        const limit = params.limit ?? 20;
+        let whereClause = "LogDate = TODAY";
+        if (params.agentApiName) {
+            const safe = params.agentApiName.replace(/'/g, "\\'");
+            whereClause += ` AND (EventTarget LIKE '%${safe}%' OR EventDetails LIKE '%${safe}%')`;
+        }
+        const query = `SELECT EventLabel, EventTarget, EventDetails, EventDate FROM ConversationDefinitionEventLog WHERE ${whereClause} ORDER BY EventDate DESC LIMIT ${limit}`;
+        const resp = await client.get(`/query?q=${encodeURIComponent(query)}`);
+        const records = resp.data.records ?? [];
+        const topicEvents = records.filter(r => (r.EventLabel ?? "").includes("TopicClassification")).length;
+        const actionEvents = records.filter(r => (r.EventLabel ?? "").includes("ActionExecuted")).length;
+        const errorEvents = records.filter(r => (r.EventLabel ?? "").toLowerCase().includes("error") || (r.EventLabel ?? "").toLowerCase().includes("fail")).length;
+        const logs = records.map(r => {
+            let details = r.EventDetails;
+            try {
+                details = JSON.parse(r.EventDetails ?? "{}");
+            }
+            catch { /* keep raw */ }
+            return { time: r.EventDate, event: r.EventLabel, target: r.EventTarget, details };
+        });
+        return {
+            success: true,
+            totalRecords: records.length,
+            summary: { topicClassifications: topicEvents, actionsExecuted: actionEvents, errors: errorEvents },
+            logs,
+            message: `${records.length} entries: ${topicEvents} topic classification(s), ${actionEvents} action execution(s), ${errorEvents} error(s).`,
+        };
+    }
+    catch (err) {
+        const msg = sanitizeError(err instanceof Error ? err.message : String(err));
+        if (msg.includes("INVALID_TYPE") || msg.includes("ConversationDefinition"))
+            return { success: false, message: "ConversationDefinitionEventLog is not available in this org. Requires Event Monitoring or Agentforce debugging enabled.", logs: [] };
+        return { success: false, message: msg, logs: [] };
+    }
+}
 //# sourceMappingURL=salesforce.js.map

package/dist/tools/agentforce.js

@@ -1,66 +1,75 @@
-import { CreateAgentSchema, CreateAgentTopicSchema, CreateAgentActionSchema, CreateAgentPlannerSchema } from "../schemas/index.js";
-import { getAuth, createAgent, createAgentTopic, createAgentPlanner, activateAgent, deactivateAgent, API_VERSION } from "../services/salesforce.js";
+import {
+    CreateAgentSchema, CreateAgentTopicSchema, CreateAgentActionSchema, CreateAgentPlannerSchema,
+    GetAgentSchema, UpdateAgentTopicSchema, UpdateAgentActionSchema, DeleteAgentSchema,
+    ListAgentsSchema, TestAgentSchema, GetAgentLogsSchema,
+} from "../schemas/index.js";
+import {
+    getAuth, createAgent, createAgentTopic, createAgentPlanner,
+    activateAgent, deactivateAgent, getAgent, listAgents,
+    updateAgentTopic, deleteAgent, testAgent, getAgentLogs, API_VERSION,
+} from "../services/salesforce.js";
 import { buildGenAiActionZip, deployZip, pollDeployStatus } from "../services/deployment.js";
 import { resultContent } from "./utils.js";
+
 export function registerAgentforceTools(server) {
+    // ─── CREATE ──────────────────────────────────────────────────────────────
     server.registerTool("sf_create_agent", {
         title: "Create Agentforce Agent",
         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
+1. Create flows (sf_create_flow) — AutoLaunchedFlows that perform actions, must be Active with runInMode=SystemModeWithoutSharing
+2. Create agent actions (sf_create_agent_action) — link each flow as a GenAiFunction with LLM-facing schemas
 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
+4. Create agent planner (sf_create_agent_planner) — create GenAiPlannerBundle linking all topics (CRITICAL link)
 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).`,
+The agent type is IMMUTABLE after creation — choose carefully:
+- EinsteinCopilot: internal employee-facing (Lightning sidebar)
+- ExternalCopilot: customer-facing Agentforce Service Agent`,
         inputSchema: CreateAgentSchema,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, async (params) => {
         const auth = await getAuth();
-        const result = await createAgent(auth, {
-            agentName: params.agentName,
-            label: params.label,
-            description: params.description,
-            type: params.type,
-        });
+        const result = await createAgent(auth, params);
         return resultContent(result);
     });
+
     server.registerTool("sf_create_agent_topic", {
         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.
+        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 routing description, scope, 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.`,
+Then create the planner bundle (sf_create_agent_planner) to link all topics to the agent.
+
+Set escalationEnabled: true to allow this topic to escalate to a human agent.
+Set fallbackTopic to route to another topic when this one cannot handle the request.`,
         inputSchema: CreateAgentTopicSchema,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, async (params) => {
         const auth = await getAuth();
-        const result = await createAgentTopic(auth, {
-            topicName: params.topicName,
-            label: params.label,
-            description: params.description,
-            scope: params.scope,
-            instructions: params.instructions,
-            actions: params.actions,
-        });
+        const result = await createAgentTopic(auth, params);
         return resultContent(result);
     });
+
     server.registerTool("sf_create_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.
+        description: `Creates an Agentforce Action (GenAiFunction) linked to a Flow or Apex class. Actions are the concrete steps an agent takes when handling a topic.
 
-IMPORTANT: This deploys a complete GenAiFunction bundle including:
+IMPORTANT: 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)
+- input/schema.json — the LLM-facing JSON schema for input parameters (REQUIRED for 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.
+Without schema files the LLM cannot invoke the action. This tool generates all three files automatically.
+
+Set invocationTargetType to "ApexClass" for Apex-backed actions (provide apexClassName instead of flowApiName).
+For Flow actions (default): the flow must be Active with runInMode=SystemModeWithoutSharing.
 
-Create actions BEFORE topics (topics reference actions by API name).
-The referenced flow MUST exist and be Active with runInMode=SystemModeWithoutSharing.`,
+Type matching: inputs/outputs type MUST match the flow variable type — use "Currency" for Currency fields, "Date" for Date fields, etc. Using "Text" for a Currency field causes "incorrect format" errors.
+
+Create actions BEFORE topics (topics reference actions by API name).`,
         inputSchema: CreateAgentActionSchema,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, async (params) => {
@@ -70,7 +79,9 @@ The referenced flow MUST exist and be Active with runInMode=SystemModeWithoutSha
                 actionName: params.actionName,
                 label: params.label,
                 description: params.description,
+                invocationTargetType: params.invocationTargetType,
                 flowApiName: params.flowApiName,
+                apexClassName: params.apexClassName,
                 inputs: params.inputs ?? [],
                 outputs: params.outputs ?? [],
             }, API_VERSION);
@@ -82,6 +93,7 @@ The referenced flow MUST exist and be Active with runInMode=SystemModeWithoutSha
             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.
@@ -89,22 +101,20 @@ The referenced flow MUST exist and be Active with runInMode=SystemModeWithoutSha
 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.`,
+Then reference this planner's API name when calling sf_create_agent.
+
+For Knowledge-grounded agents, set dataLibraryName to the API name of a Data Library (Knowledge Base).`,
         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,
-        });
+        const result = await createAgentPlanner(auth, params);
         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.`,
+        description: `Activates an Agentforce Agent so it is available to users. After making configuration changes (adding/removing topics or actions), 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) => {
@@ -112,6 +122,7 @@ Then reference this planner's API name when calling sf_create_agent.`,
         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.`,
@@ -122,5 +133,153 @@ Then reference this planner's API name when calling sf_create_agent.`,
         const result = await deactivateAgent(auth, params.agentApiName);
         return resultContent(result);
     });
+
+    // ─── READ ────────────────────────────────────────────────────────────────
+    server.registerTool("sf_get_agent", {
+        title: "Get Agentforce Agent Configuration",
+        description: `Retrieves the full configuration of an Agentforce Agent including activation status, all GenAiPlugin topics, GenAiFunction actions, and GenAiPlannerBundle planners in the org.
+
+Returns:
+- agent.status: Active / Inactive / Unknown
+- topics[]: all GenAiPlugin topics (name, label, lastModified)
+- actions[]: all GenAiFunction actions (name, label, lastModified)
+- planners[]: all GenAiPlannerBundle planners (name, label, lastModified)
+
+Note: topics/actions/planners list all components in the org (not filtered to this agent). Use sf_get_agent_logs to see which are actively routing.`,
+        inputSchema: GetAgentSchema,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (params) => {
+        const auth = await getAuth();
+        const result = await getAgent(auth, params.agentApiName);
+        return resultContent(result);
+    });
+
+    server.registerTool("sf_list_agents", {
+        title: "List All Agentforce Agents",
+        description: `Lists all Agentforce Agents (Bots) in the org with their API name, label, activation status, and last modified date.
+
+Use this to discover agents before updating, testing, or deleting them.`,
+        inputSchema: ListAgentsSchema,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (_params) => {
+        const auth = await getAuth();
+        const result = await listAgents(auth);
+        return resultContent(result);
+    });
+
+    // ─── UPDATE ──────────────────────────────────────────────────────────────
+    server.registerTool("sf_update_agent_topic", {
+        title: "Update Agentforce Topic (GenAiPlugin)",
+        description: `Updates an existing GenAiPlugin topic in-place without deleting and recreating it. Automatically deactivates the agent before the update and reactivates it after.
+
+Use this to change a topic's routing description, scope, instructions, or linked actions.
+All fields provided replace the existing values (instructions and actions arrays are replaced entirely).
+
+The agent must exist and be accessible — provide agentApiName for automatic deactivate/reactivate.`,
+        inputSchema: UpdateAgentTopicSchema,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (params) => {
+        const auth = await getAuth();
+        const { agentApiName, ...topicParams } = params;
+        const result = await updateAgentTopic(auth, topicParams, agentApiName);
+        return resultContent(result);
+    });
+
+    server.registerTool("sf_update_agent_action", {
+        title: "Update Agentforce Action (GenAiFunction)",
+        description: `Updates an existing GenAiFunction action and regenerates its LLM-facing input/output schema files. Uses zip-based metadata deploy (same as sf_create_agent_action) since GenAiFunction bundles require schema files.
+
+Use this to change an action's description, input/output parameters, or switch from one flow to another.
+All fields provided replace the existing values.
+
+After updating an action, the topics that reference it will automatically use the new schema on the next agent invocation.`,
+        inputSchema: UpdateAgentActionSchema,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (params) => {
+        const auth = await getAuth();
+        try {
+            const base64Zip = await buildGenAiActionZip({
+                actionName: params.actionName,
+                label: params.label,
+                description: params.description,
+                invocationTargetType: params.invocationTargetType,
+                flowApiName: params.flowApiName,
+                apexClassName: params.apexClassName,
+                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) });
+        }
+    });
+
+    // ─── DELETE ──────────────────────────────────────────────────────────────
+    server.registerTool("sf_delete_agent", {
+        title: "Delete Agentforce Agent",
+        description: `Cleanly deletes an Agentforce Agent (Bot) and optionally its related GenAiPlugin topics and GenAiFunction actions.
+
+Deletion order (to avoid dependency errors):
+1. Deactivates the agent
+2. Reads the Bot → finds GenAiPlannerBundle name
+3. Reads the GenAiPlannerBundle → finds GenAiPlugin topic names (if deleteTopics: true)
+4. Reads each GenAiPlugin → finds GenAiFunction action names (if deleteActions: true)
+5. Deletes GenAiFunctions → GenAiPlugins → GenAiPlannerBundle → Bot
+
+Set deleteTopics: true to also delete the agent's topics.
+Set deleteActions: true to also delete the actions (requires deleteTopics: true since action names are discovered via topics).
+
+WARNING: Deleting actions/topics affects all agents that reference them.`,
+        inputSchema: DeleteAgentSchema,
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+    }, async (params) => {
+        const auth = await getAuth();
+        const result = await deleteAgent(auth, params);
+        return resultContent(result);
+    });
+
+    // ─── TEST & DEBUG ─────────────────────────────────────────────────────────
+    server.registerTool("sf_test_agent", {
+        title: "Send Test Message to Agentforce Agent",
+        description: `Sends a test message to an Agentforce Agent via the Einstein Agent API and returns the agent's response. Useful for end-to-end testing without opening the Salesforce UI.
+
+Flow:
+1. Bootstraps an Agentforce session (POST /agentforce/bootstrap/nameduser)
+2. Creates a session (POST /einstein/ai-agent/v1/agents/{id}/sessions)
+3. Sends the message and returns the agent's reply text
+
+The agent must be Active. Set orgUrl if your My Domain URL differs from SF_INSTANCE_URL.
+
+Returns: response text, sessionId, and success status.`,
+        inputSchema: TestAgentSchema,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (params) => {
+        const auth = await getAuth();
+        const result = await testAgent(auth, params);
+        return resultContent(result);
+    });
+
+    server.registerTool("sf_get_agent_logs", {
+        title: "Get Agentforce Debug Logs",
+        description: `Queries ConversationDefinitionEventLog for Agentforce agent debug information. Shows topic routing decisions, action executions, and errors.
+
+Key event types to look for:
+- TopicClassificationSuccess — agent routed to a topic (routing is working)
+- ActionExecuted — agent invoked an action (full pipeline working)
+- TopicClassificationFail / Error — routing or execution failed
+
+If you see TopicClassificationSuccess but NO ActionExecuted events, the agent is routing correctly but cannot invoke actions — check that GenAiFunction schema files exist (redeploy with sf_create_agent_action).
+
+Requires ConversationDefinitionEventLog access (Event Monitoring or Agentforce debug enabled in the org).`,
+        inputSchema: GetAgentLogsSchema,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (params) => {
+        const auth = await getAuth();
+        const result = await getAgentLogs(auth, params);
+        return resultContent(result);
+    });
 }
 //# sourceMappingURL=agentforce.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "salesforce-metadata-mcp",
-  "version": "2.1.3",
+  "version": "2.1.4",
   "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,