@sf-explorer/agentforce-service

@sf-explorer/agentforce-service

Express server for Agentforce agent APIs. Exposes sendMessage, compile, get agent, and update agent endpoints. Initializes from sf force:org:display --json. Serves a bundled React UI when built.

Getting Started

Recommended: Run with npx

No install required. From your Salesforce project directory:

npx @sf-explorer/agentforce-service
npx @sf-explorer/agentforce-service /path/to/sf-project
npx @sf-explorer/agentforce-service . --org my-org --port 3847

Then open http://localhost:3847 for the UI.

From source (development)

From the repo root:

npm install
npm run build
npm start -- example

From the server folder:

cd server
npm install
npm run build
npm start -- ../example

Ensure you have an authenticated Salesforce org (sf org login web and sf config set target-org <alias>).

Development (from repo)

# Build (client + server)
npm run build

# Start server
npm start
npm start -- ../example
npm start -- ../example --org my-org --port 3847

The build outputs the client to dist/client and compiles TypeScript to dist/. The UI is served at the root URL when the server runs.

Install (optional)

For a global install: npm install -g @sf-explorer/agentforce-service, then run agentforce-service [projectDir] [--org alias] [--port 3847].

APIs

Session flow (order matters)

• POST /api/startSession → get sessionId
• POST /api/sendmessage → chat (repeat as needed); response includes messages[].planId
• POST /api/trace → (optional) get plan trace for a planId from sendmessage
• POST /api/endSession → end session when done

Endpoints

Method	Path	Description
POST	/api/startSession	Start agent preview (agentBundleName or apiNameOrId)
POST	/api/sendmessage	Send message via agent.preview.send()
POST	/api/trace	Get plan trace for a planId (from sendmessage response)
POST	/api/endSession	End preview session
POST	/api/compile	Compile AgentScript via ScriptAgent.compile()
GET	/api/agents	List agents (local, remote, or all previewable)
GET	/api/agent/:developerName	Retrieve agentscript metadata from Metadata API
PUT	/api/agent/:developerName	Deploy an agentscript package to the org
GET	/api/tests	List test definitions (local JSON files)
GET	/api/tests/:filename	Retrieve test content by filename
POST	/api/tests/run	Run test (Salesforce AI Evaluation or local JSON)
GET	/api/tests/runs/:runId	Retrieve test run status or results

startSession

Uses @salesforce/agents Agent.preview.start(). Pass either agentBundleName (script agent) or apiNameOrId (production agent). For script agents, optional useMock (default true) controls simulated vs live mode.

POST /api/startSession
{ "agentBundleName": "AgentScriptDemo" }
{ "agentBundleName": "AgentScriptDemo", "useMock": false }
// or
{ "apiNameOrId": "BotIdOrApiName" }

sendmessage

Uses @salesforce/agents agent.preview.send().

POST /api/sendmessage
{ "sessionId": "...", "message": "Hello" }

trace

Uses @salesforce/agents agent.getTrace(planId). planId comes from sendmessage response messages[].planId. Requires an active session.

POST /api/trace
{ "sessionId": "...", "planId": "..." }

endSession

Uses @salesforce/agents agent.preview.end().

POST /api/endSession
{ "sessionId": "..." }

compile

POST /api/compile
{ "agentBundleName": "AgentScriptDemo" }

retrieve agents

GET /api/agents?source=all   # all previewable (default)
GET /api/agents?source=local # agent bundles in project
GET /api/agents?source=remote # published bots in org

get agent

GET /api/agent/AgentScriptDemo

update agent

PUT /api/agent/AgentScriptDemo
{ "sourcePath": "/optional/path/to/bundle" }

If sourcePath is omitted, uses {projectDir}/force-app/main/default/aiAuthoringBundles/{developerName}.

tests

List, retrieve, and run agent tests.

GET /api/tests?dir=all        # List test files (root + example/)
GET /api/tests/energy-test-case.json   # Retrieve test content
POST /api/tests/run           # Run test (see body options below)
GET /api/tests/runs/:runId    # Get run status; ?results=true for full results

Run options:

• Salesforce AI Evaluation – { "aiEvaluationDefinitionName": "MyTestDef" } → returns { runId }; poll /api/tests/runs/:runId for status/results.
• Local run – { "testFile": "energy-test-case.json", "agentBundleName": "MyAgent" } → executes test cases via preview session; returns { total, passed, failed, results }.

Prerequisites

• Node.js >= 18
• Salesforce CLI (sf) installed and authenticated
• A Salesforce project with aiAuthoringBundles (for compile/agent APIs)