Agentforce Integration

Pro Plan Feature

Agentforce chat in the taskpane requires a Keelstone Pro plan. The six Invocable Apex actions are included in the managed package for all plans, but the embedded chat widget only loads for Pro and Enterprise orgs.

Keelstone Pro embeds a Salesforce Agentforce agent directly in your Excel or Word taskpane. The agent communicates with your open document through six Invocable Apex actions that make authenticated callouts to the Keelstone server, which relays commands to the active taskpane via the existing socket relay.

How it works

User types in Agentforce chat (inside Office taskpane)
    │
    ▼
Agentforce Agent → Invocable Apex Action
    │   e.g. KS_QueryAndWrite(keelstoneSessionId, soql, target)
    │
    ▼
Apex HTTP POST → https://app.keelstone.dev/api/excel/query
    │   Authorization: Bearer {keelstoneSessionId}
    │
    ▼
Keelstone server → looks up taskpane socket → emits ks:write
    │
    ▼
Taskpane socket handler → Excel.run() → writes rows
    │
    ▼
Agent receives result → "14 rows written to A1:D14 ✓"

The keelstoneSessionId flows through the entire chain automatically — it is set as a hidden Conversation Variable in the Embedded Messaging channel and passed to every action without user involvement.

---

Prerequisites

Requirement	Notes
Keelstone managed package v1.4.0+	Installs the six Apex action classes
Keelstone Pro plan active	Contact Keelstone team to upgrade
Agentforce platform license	Required in your Salesforce org
Digital Engagement / Messaging for In-App and Web add-on	Required to create the Embedded Messaging channel
Einstein AI enabled	Setup → Einstein → Einstein Settings
A published Salesforce Site or Experience Cloud site	To host the Embedded Messaging endpoint

---

The six Agentforce actions

The managed package installs these @InvocableMethod Apex classes. They appear in Agentforce Topic setup prefixed with kstone__.

Excel actions

Action label	Apex class	What it does
KS: Get Excel Range	kstone__KS_GetRange	Returns the address and values of the currently selected cells
KS: Write Data to Excel	kstone__KS_WriteData	Writes a 2D array to a range or named range
KS: Query Salesforce and Write to Excel	kstone__KS_QueryAndWrite	Runs a SOQL query and writes results into the spreadsheet

Word actions (Pro plan, requires Word taskpane)

Action label	Apex class	What it does
KS: Get Word Document Text	kstone__KS_GetDocumentText	Returns the full plain text of the open Word document
KS: Update Word Content Control	kstone__KS_UpdateContentControl	Updates a tagged Content Control section by tag name
KS: Scan Document for Keywords	kstone__KS_ScanKeywords	Searches the document for a keyword list, returns match counts

---

Setup — Salesforce admin steps

Step 1 — Create the Embedded Messaging channel

1. Setup → Messaging Settings → New Channel
2. Select Messaging for In-App and Web (Enhanced)
3. Fill in:
   • Channel Name: Keelstone_Document_Assistant
   • Display Name: Keelstone Document Assistant
4. Save. Then open Conversation Variables → New:
   • Variable Name: keelstoneSessionId
   • Data Type: Text
   • Hidden: ✅ Yes
   • Description: Keelstone Office session token — set automatically, do not prompt the user.
5. Save. Do not publish yet.

Step 2 — Create the Agentforce Agent

1. Setup → Einstein → Agents → New Agent
2. Type: Agentforce Agent (Custom)
3. Fill in:
   • Agent Label: Keelstone Document Assistant
   • API Name: Keelstone_Document_Assistant
   • Description: Reads and writes the user's open Excel or Word document via the Keelstone Office Add-in.
4. Under Channels, add the Keelstone_Document_Assistant channel.
5. Save — you are now in the Agent Builder.

Step 3 — Create a Topic

1. In the Agent Builder, click New Topic
2. Fill in:
   • Topic Label: Keelstone Document Operations
   • API Name: Keelstone_Document_Operations
   • Description (used for routing):

     Use this topic for any request to read data from, write data to, or analyze the user's open Excel workbook or Word document. This includes writing Salesforce records to Excel, reading document content, updating Word contract sections, and scanning documents for keywords.

   • Scope: Custom
3. In the Instructions field, paste:

You are a document assistant embedded in the Keelstone Office Add-in sidebar.
The user has an Excel workbook or Word document open on their desktop alongside this chat.

Rules:
- Always pass the keelstoneSessionId conversation variable to every Keelstone action. Never ask the user for it — it is set automatically.
- Before writing data to Excel, confirm the target range with the user unless they already specified one.
- When a query-and-write action completes, tell the user how many rows were written and where.
- For Word content control updates, confirm the tag name with the user before updating unless they specified it.
- For KS: Write Data to Excel, format dataJson as a JSON string 2D array: '[["Name","Amount"],["Acme Corp",75000]]'
- For KS: Scan Document for Keywords, format keywordsJson as a JSON array string: '["indemnity","limitation of liability","governing law"]'
- If an action returns success=false, read the error field from resultJson and explain it plainly.
- Never display the keelstoneSessionId value in chat.
- If a Word action returns a "requires pro plan" error, explain that Word and PDF features require a Keelstone Pro subscription.
- If you receive a "Taskpane not connected" error, ask the user to open the Keelstone add-in in Excel or Word and try again.

4. Save the Topic.

Step 4 — Add actions to the Topic

1. Click Add Actions and search Keelstone
2. Add all six actions: kstone__KS_GetRange, kstone__KS_WriteData, kstone__KS_QueryAndWrite, kstone__KS_GetDocumentText, kstone__KS_UpdateContentControl, kstone__KS_ScanKeywords
3. For each action, find the Keelstone Session ID input and set:
   • Source: Conversation Variable
   • Value: keelstoneSessionId
4. Save each action configuration.

Step 5 — Activate and publish

1. In the Agent Builder, click Activate Agent (resolve any validation errors)
2. Setup → Messaging Settings → Keelstone_Document_Assistant → Publish
3. From the generated embed snippet, copy these four values:
   • Bootstrap URL (e.g. https://yourorg.my.salesforce-sites.com/ESWKeelstoneDocumentAssistant/assets/js/bootstrap.min.js)
   • Salesforce Org ID (18-char, starts with 00D)
   • Deployment Name (e.g. Keelstone_Document_Assistant)
   • SCRT2 URL (e.g. https://yourorg.my.salesforce-scrt.com)

Step 6 — Activate the widget (Keelstone team)

Send the four values from Step 5 to the Keelstone team. They will run one admin API call to activate the chat widget in your org's taskpane:

POST https://app.keelstone.dev/api/admin/orgs/{orgId}/messaging-config
x-admin-key: <ADMIN_KEY>
Content-Type: application/json

{
  "bootstrapUrl":        "https://yourorg.my.salesforce-sites.com/ESWKeelstoneDocumentAssistant/assets/js/bootstrap.min.js",
  "orgId":              "00D...",
  "eswLiveAgentDevName": "Keelstone_Document_Assistant",
  "scrt2URL":           "https://yourorg.my.salesforce-scrt.com"
}

Once this returns {"success":true}, the next login from any user in your org will show the Agentforce chat bubble in the taskpane.

---

Using the agent — example prompts

The agent understands natural language. Here are representative examples:

Excel:

• "Pull all open opportunities for Acme Corp into A1"
• "What's in my current selection?"
• "Write a list of my accounts by industry to Sheet2!A1, no named range"
• "Run SELECT Name, CloseDate, Amount FROM Opportunity WHERE StageName = 'Negotiation' and write it to the pipeline tab"

Word:

• "Read this document and summarize the key obligations"
• "Update the Indemnification clause to cap liability at 2x annual contract value"
• "Scan for limitation of liability, governing law, and auto-renewal"

---

Action input reference

KS: Write Data to Excel

Input	Type	Notes
keelstoneSessionId	String	Auto-mapped from conversation variable
dataJson	String (required)	JSON string 2D array: '[["Name","ARR"],["Acme",50000]]'
target	String	Target cell or named range, e.g. "A1" or "Pipeline". Optional.
namedRange	Boolean	Create a named range. Default: true.

KS: Query Salesforce and Write to Excel

Input	Type	Notes
keelstoneSessionId	String	Auto-mapped
soql	String (required)	Full SOQL query
target	String	Target cell or named range. Optional.
includeHeaders	Boolean	Write column headers as row 1. Default: true.

KS: Update Word Content Control

Input	Type	Notes
keelstoneSessionId	String	Auto-mapped
tag	String (required)	The Content Control tag, e.g. "SF_Indemnification_Clause"
text	String (required)	Replacement text to insert

KS: Scan Document for Keywords

Input	Type	Notes
keelstoneSessionId	String	Auto-mapped
keywordsJson	String (required)	JSON array string: '["indemnity","limitation of liability"]'

Result JSON for all actions contains:

• success (Boolean) — true if the action completed without error
• resultJson (String) — JSON response body from the Keelstone server; contains error field if success=false

---

Troubleshooting

Symptom	Likely cause	Fix
Chat bubble does not appear	Org not on Pro plan, or messaging config not set	Confirm plan with Keelstone team; verify admin config endpoint was called
Action returns "Taskpane not connected"	User closed the taskpane	Ask user to reopen the Keelstone Excel or Word add-in
Action returns 403	Word/PDF action called from free plan	Upgrade to Pro
Action returns 429	Daily merge limit reached (free plan)	Limit resets daily; upgrade to Pro for unlimited
onEmbeddedMessagingReady not firing	Salesforce org on older release	Try setting embeddedservice_bootstrap.settings.hiddenPrechatFields before init() instead
Agent says "I couldn't find that action"	Actions not added to the Topic	Revisit Step 4 — add all six actions and map the session variable