npm package: @sf-explorer/agentforce-service
Description: Express server for Agentforce agent APIs - sendMessage, compile, get/update agent metadata
Latest version: 1.0.0

# @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:

```bash
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:**

```bash
npm install
npm run build
npm start -- example
```

**From the server folder:**

```bash
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)

```bash
# 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)

1. **POST /api/startSession** → get `sessionId`
2. **POST /api/sendmessage** → chat (repeat as needed); response includes `messages[].planId`
3. **POST /api/trace** → (optional) get plan trace for a `planId` from sendmessage
4. **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.

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

### sendmessage

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

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

### trace

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

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

### endSession

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

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

### compile

```json
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

```json
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)