SF Agent Script

Single-plugin lifecycle for `.agent` files: compile diagnostics, native quality, preview, local-first Eval Studio, exact-version release eval, inactive publication, and gated activation.

What it does

Owns the entire Agent Script lifecycle: compile and quality hardening, structural review, preview, local-first Eval Studio, exact-version release eval contracts, inactive publication, and Guardrail-mediated activation.

Start

Open the extension from its primary command:

/sf-agentscript

Open its Manager detail or change its package state with:

/sf-pi open sf-agentscript
/sf-pi enable sf-agentscript
/sf-pi disable sf-agentscript

Safety notes

• Compile-on-save stays silent on unsupported files and on failed write/edit results; only enabled edit-time High hardening rules join that feedback.
• Deferred quality repair uses Pi's actionable pre-settlement boundary after retries and queued user work finish.
• Global per-rule quality toggles dynamically control reporting, repair, metrics, and local-file publication gating without a reload.
• Quality cards show every finding header by default; overlong variable descriptions gate publication, while official instruction-template diagnostics remain pre-activation recommendations.
• Eval batches retry a rejected org credential once with Agentforce named-user auth; org reads retain the normal @salesforce/core connection and tokens are never logged or persisted.
• Local-first: one cached official Agent Script parse/lint/index/compile pass owns each source identity before any network call; mutable documents are created only for mutation paths.
• Diagnostics and code actions use deterministic source-bound identities; stale, missing, or ambiguous quick fixes are refused, and official provider availability is explicit.
• Structure, quality, and review are agent-type-aware: ordinary agents use start_agent, while GoalBasedAgent uses its orchestrator and projects workflows, triggers, bundles, and local actions.
• Escalation follows the official active Omni-Channel prerequisite without an additional Employee-versus-Service Agent restriction.
• Apex action preflight uses Salesforce's registered action description for authoritative primitive and wrapper input/output contracts; failed target rows are never hidden behind resolved samples.
• Eval Studio inventories repository EvalSpec JSON and local Run artifacts without Salesforce calls; org/version resolution occurs only after an explicit Run or Release Contract action.
• Eval runs synthesize trace artifacts from inline Evaluation API data by default; explicit trace fetches are idempotent GETs.
• Eval turn artifacts preserve a parsed response sequence for every lastExecution.llmEvents entry without duplicating full prompt bodies; missing get_state evidence is unavailable, never a passing zero, and exact repeated surface sentences are detected even when LLM-event evidence is absent.
• Preview and eval completion cards render bounded full-conversation replays with every user/agent utterance, per-turn path, latency, and integrity proof while keeping LLM-facing tool text compact.
• Voice context profiles reuse the official AST for syntax, streaming, locale, model/persona, inbound, filler, progress, and router facts; policy advisories never duplicate official voice or HyperClassifier diagnostics.
• Generated Voice suites add concise greeting and distressed-caller probes and enforce one customer-facing LLM completion per turn; exact-version Voice release contracts refuse designated suites without strict get_state-backed response-integrity evidence.
• Runtime smoke narrows VoiceCall by the optional phone number and correlates AgentWork through WorkItemId instead of combining unrelated latest records.
• Publication always creates an inactive version; activation requires complete exact-org, exact-BotVersion generated-baseline evidence plus the current designated release suite when configured.
• Untested activation is a distinct Guardrail Safety Envelope; acknowledge_untested_activation is intent, never approval.
• 5xx-only retry on POST avoids amplifying server-side overload (no Retry-After contract on the Eval API); client-side Eval API batch timeouts are terminal and configurable through batch_timeout_ms.
• Preview sessions land under .sfdx/agents/** (sf-guardrail carve-out); rest of .sfdx/** stays blocked.

Exact reference

Show commands, tools, providers, and hooks

• Extension id: sf-agentscript
• Intent: Build agents
• Category: Agent Tool
• Maturity: stable
• Default state: on
• Commands: /sf-agentscript
• LLM tools: agentscript_authoring, agentscript_preview, agentscript_eval, agentscript_lifecycle
• Providers: none
• Events/hooks: session_start, session_shutdown, tool_result, agent_before_settle

For contributors

• Full extension README
• Source folder
• Agent editing rules
• Agent operating guide
• Reference index

Troubleshooting

See the Troubleshooting section in the full README for extension-specific recovery steps.