AgentPulse Script
Preview, test and debug Agentforce Agent Script (.agent) files in VS Code and Cursor.
- Preview — a rendered, navigable view of the script, toggled like Markdown preview. Needs nothing.
- Tests — the AI drafts regression scenarios from your agent, you keep the good ones, fill real data once, and
run them against your org through the Agentforce preview. Results show what the agent said, what the planner
did, and what landed in the backend, plus an AI verdict and an on-demand root-cause diagnosis.
- Any AI you already have. Uses whichever coding agent CLI is installed (Claude Code, Cursor Agent, OpenAI Codex,
Gemini, GitHub Copilot, OpenCode) — or, if you have none, your own Salesforce org's AI models. No API keys to
paste, nothing sent to AgentPulse.
Everything lives in native VS Code surfaces: Test Explorer, a Run History and Grounding view, CodeLens and Outline on
the .agent file, the status bar, and a run-detail tab.
Install
Extensions view → search AgentPulse Script → Install — VS Code from the
Marketplace; Cursor, VSCodium
and Windsurf from Open VSX. Or Cmd+Shift+P → Extensions: Install from VSIX… and pick the .vsix, then
Developer: Reload Window.
The Get started with AgentPulse Script walkthrough opens the first time you open a workspace with an agent bundle (later: Help → Welcome → Walkthroughs).
Quick start
Open a .agent file inside …/aiAuthoringBundles/<bundle>/. (Trust the workspace when VS Code asks — the
preview works without trust; tests run local tools and need it.)
Check Setup — the AgentPulse icon in the Activity Bar → Setup & Status. Every row should be green:
- Salesforce CLI and a connected org (
sf org login web).
- AI provider —
auto → <your CLI> when a coding CLI is installed. None installed? Click
Use my Salesforce org and the org answers the prompts instead.
Generate — Generate Scenarios (Run History, CodeLens, or the Command Palette) — one click; it replaces the
drafts you haven't reviewed yet. The Testing view opens and Drafts shows a spinning row per scenario being
drafted, with the current step and elapsed time, until the drafts arrive. Can't find the Testing view (Cursor may
keep it in the activity bar's overflow)? Use the Scenarios row in Setup & Status or AgentPulse Script: Show
Scenarios.
Review — Keep or Discard each draft (right-click, or Review Draft Scenarios). Only kept scenarios run.
Ground — scenarios use {{tokens}} for real data (an order id, an email). Fill each once in the
Grounding view; a scenario with an empty token is skipped, never run on invented data.
Run — ▷ in the Test Explorer. Results stream in; open a run from Run History for the conversation,
planner traces, analysis and Diagnose (root cause + suggested fix you can apply).
Requirements
| For |
You need |
| Preview |
nothing |
| Generate / diagnose |
an AI provider: any supported coding CLI signed in, or a connected Salesforce org with Einstein generative AI enabled. Node is not required — the editor's bundled runtime is used when node is missing. |
| Run against an org |
the Salesforce CLI (sf) — its built-in agent support is found automatically — and an authenticated org. Node 22+ or the editor's bundled runtime is used for runs. Agents linked to Messaging (RoutableId) also need MessagingSession records in the org; other agents don't. |
macOS and Linux are supported. On Windows, use WSL (open the project in VS Code's WSL window) — the extension runs on the workspace side, next to your project and sf.
AI providers
agentScript.ai.provider (default auto):
| Provider |
Uses |
Notes |
auto |
the first installed of claude, cursor-agent, codex, gemini, copilot, opencode, else your Salesforce org (after you opt in) |
the Setup row shows what it picked |
claude · cursor · codex · gemini · copilot · opencode |
that CLI, headless |
run read-only / without tools, from an empty scratch folder |
salesforce |
your org's Models API via anonymous Apex, with your normal sf login |
default model sfdc_ai__DefaultGPT41 (falls back to GPT-4o mini); refuses production orgs unless agentScript.ai.salesforce.allowProduction; Setup offers Use a different org for AI… or Allow production for AI when that happens |
custom |
any command: agentScript.ai.bin + agentScript.ai.args with {prompt} / {model} |
promptMode: "stdin" to pipe the prompt |
Other settings: agentScript.ai.model / agentScript.ai.models (per role: generate, customer, analyst, diagnose),
agentScript.ai.salesforce.org, agentScript.ai.timeoutSeconds, agentScript.ai.extraArgs,
agentScript.suite.org (the org tests run against; empty = your default org),
agentScript.suite.allowProductionApex (Apex verifiers are skipped on production orgs unless enabled),
agentScript.ui.native (set false for the classic Tests panel).
The engine reads the same choice from AI_CLI_* environment variables or scripts/ai-cli.config.json, so a
terminal or CI run behaves like the editor.
What a scenario checks
Generated scenarios are dynamic: a persona with objectives that an AI customer plays turn by turn against the
agent's real replies. A scenario passes only on the layers it declares:
- Conversation —
expectLast / rejectLast regexes on the final reply.
- Planner trace —
expectTopic, expectActions, rejectActions from the preview's plan traces.
- Backend —
expect{} Case fields, and an optional Apex verifier (apexVerify: inline code, a file, a
deployed Class.method, or a named entry in scripts/verifiers.<bundle>.json) that returns
AGV_VERIFY {ok, reason}. Generate with backend Apex checks drafts these against your org's real schema.
An AI analyst then reads the whole run and adds findings; it never flips a deterministic verdict.
Your data
Per bundle, under <repo>/scripts/: scenarios, grounding (real values — keep it out of git), suites, verifiers, run
history. Nothing leaves your machine except calls to your org and to the AI provider you chose. Writes are refused
rather than risk overwriting a file that no longer parses.
Agentforce Studio
Studio Sync exports kept scenarios to Testing Center (AiEvaluationDefinition) after you review the AI-written
utterances, and imports Testing Center tests back as drafts.
Help
Start with Setup & Status — each row says what's missing and offers a one-click fix. The AgentPulse: CLI
Output channel has the full log of every generate, run and diagnose.
Contributing and releasing: see MAINTAINERS.md in the source repository.
