name: sf-agentscript
description: Agent Script lifecycle — author, preview, evaluate, and publish .agent files through four family tools: authoring, preview, eval, and lifecycle.
SF Agent Script
Use this skill whenever the user is editing .agent files, debugging an Agentforce agent, generating/running regression specs, previewing a local or published agent, or publishing/activating an agent.
Tools
| Tool | Use it for |
|---|
agentscript_authoring | Create bundles, compile/check or format .agent files, inspect structure/references/targets, run deterministic review, and mutate source. Uses verb + mode. |
agentscript_preview | Start/send/end live preview sessions, fetch planner traces, bulk-end sessions, clean stale preview artifacts, render rich human Preview Trace Reports, and return compact LLM trace digests. |
agentscript_eval | Generate starter eval specs, run regression suites, drill into failures, synthesize trace artifacts, fetch explicit live traces, and resolve active/latest version ids. |
agentscript_lifecycle | Publish, activate/deactivate, list versions, and diagnose/provision Service Agent users. |
Authoring contract
agentscript_authoring shape:
{ "verb": "compile", "mode": "check", "agent_file": "force-app/.../Billing_Bot.agent" }
Rules:
verb="create" omits mode and requires bundle_name.verb="compile" defaults mode to check; mode="format" writes canonical SDK formatting.verb="inspect" defaults mode to structure; modes: structure, context_profile, find_references, definition, check_targets, review, runtime_smoke.verb="mutate" requires mode; modes: set_field, rename, insert, delete, apply_quick_fix.- Use
agent_file, not a generic path field.
agent_file may be omitted only when exactly one current .agent file exists on the active Pi branch. Ambiguity is refused with candidates.
Preferred loop
1. agentscript_authoring { verb:"compile", mode:"check", agent_file }
2. agentscript_authoring { verb:"inspect", mode:"structure", agent_file }
3. agentscript_authoring { verb:"mutate", mode:"...", agent_file, ... }
4. agentscript_authoring { verb:"compile", mode:"check" }
5. agentscript_preview { action:"start", agent_file }
6. agentscript_preview { action:"send", message:"..." }
7. agentscript_eval { action:"generate_spec", agent_file, output_path:"..." }
8. agentscript_eval { action:"run", spec_path:"...", agent_api_name:"..." }
9. agentscript_lifecycle { action:"publish", agent_file, activate:true }
Branch-Durable Tool State
Tool results may carry details.sf_agentscript_branch_state. Treat it as a branch-aware pointer layer, not evidence storage.
It may let you omit:
agent_file when exactly one current .agent file exists on the branch- preview
agent_name/session_id when exactly one active preview session exists
- eval
spec_path or failed run_id when exactly one candidate exists
It will not guess when multiple candidates exist. Pass explicit ids when ambiguous.
Heavy artifacts remain on disk:
- preview sessions/traces under
.sfdx/agents/**
- eval run status/failures/synthesized traces under
.pi/state/sf-agentscript/**
- optional review reports at
output_path
Authoring modes
Compile
Use before inspecting deeply, mutating, previewing, or publishing.
{ "verb": "compile", "mode": "check", "agent_file": "..." }
Use fallback="server" only when local severity-1 diagnostics look like dialect-version skew. It requires target_org and costs a network call.
mode="format" writes canonical SDK formatting and refuses parse errors.
Inspect
Use inspect/structure instead of reading whole files. It returns components, line numbers, refs, stats, and parse-error flags.
Use inspect/context_profile before previewing or publishing voice, messaging, linked-variable, or stateful agents.
Use inspect/find_references before mutating a symbol. Use inspect/definition when you only need the declaration.
Use inspect/check_targets before publish when action targets must resolve in the org. Requires target_org.
Use inspect/review before publish or after behavioral changes. It is deterministic: no hidden model call, no numeric score. Readiness is ready, ready_with_warnings, blocked, or partial. Pass target_org to include read-only org checks: action-target resolution, Service Agent user readiness, and surface readiness probes such as Agentforce settings, phone number, voice/messaging channel, ServiceChannel, published voice planner, routing-flow, and fallback-queue checks for channel-linked agents. Pass output_path to write a Markdown report.
Use inspect/runtime_smoke only after a test call or message. It is read-only and diagnoses recent VoiceCall, AgentWork, and MessagingSession records; it does not place calls, send messages, or replace preview/eval.
Mutate
Prefer agentscript_authoring mutate over generic file editing when the change matches a supported mode. It survives whitespace drift and returns post-mutation diagnostics.
Use mode="apply_quick_fix" from compile quick-fix apply_via hints. If line numbers may have shifted, compile/check again first.
mode="set_field" supports scalar values: string, number, boolean, null. It updates existing fields and may add known scalar fields such as config.agent_type; use generic editing for list/object/block construction.
mode="rename" is for reference-safe renames of declarable symbols (@subagent.X, @topic.X, @actions.X, @variables.X). It also accepts legacy component paths such as subagent.billing.
mode="insert" and mode="delete" intentionally guide you to the generic edit tool followed by compile/check; they are not broad structured source-construction engines.
Use dry_run=true for risky changes.
Create
Use verb="create" for new bundles. It writes .agent plus bundle-meta.xml, validates locally before writing, and returns next steps using the family tools.
Preview
agentscript_preview action="start" accepts either agent_file or agent_api_name.
agent_file: local compile first, then server preview; supports context-variable patching for linked/state variables.agent_api_name: converse with a published active agent; surface digest only.
After a single preview session is active on the branch, send and end may omit agent_name and session_id. If more than one session is active, pass both explicitly.
Use context_variables to seed deterministic session state for preview or per-turn sends.
Preview send output uses two surfaces: the human renderer shows a rich Preview Trace Report (turn summary, route path, state changes, key state, tool activity, action I/O appendix, aligned planner timeline, diagnostics, stats, and drill pointers), while content[0].text stays compact for LLM context efficiency. Use details.digest for structured signals and agentscript_preview trace with the returned plan_id when the full raw trace is needed.
Eval
Use generate_spec to bootstrap a starter regression spec from a .agent file. Use run with agent_api_name so the runner resolves/injects Active BotVersion ids safely by default.
For long or exploratory local runs, pass batch_timeout_ms to cap each Evaluation API batch POST. The default remains 300000ms, and client-side timeouts are not retried. During a run, inspect .pi/state/sf-agentscript/runs/<run_id>/status.json for the current phase when persistence is enabled.
Eval runs synthesize trace artifacts from inline Evaluation API data by default. Use agentscript_eval action="trace" only when you explicitly need a live planner trace and have a known resident session_id/plan_id.
Use $latest_* placeholders or version_resolution="latest" only for the publish → eval → activate loop, and pass acknowledge_inactive_version=true when deliberately testing a non-Active version.
Use get_failure after large runs. If exactly one failed completed run exists on the current branch, run_id may be omitted; otherwise pass it explicitly.
Lifecycle
Use publish to ship a new agent/version. Set activate=true only when you intend to immediately serve the new version.
Use agent_user_status, diagnose_agent_user, and provision_agent_user for Service Agent user wiring. Provision defaults to dry_run=true; pass dry_run=false only after reviewing the plan. Live provisioning deploys a synthesized Permission Set for Apex action access with bounded Metadata API start/poll timeouts so stalled deploys return diagnostics instead of waiting on SDR's long default poll window.
Do not infer activation/deactivation targets from branch state. Pass agent_api_name explicitly for activate, deactivate, and list_versions.
Production observability handoff
When the user asks why a production agent behaved incorrectly, start with sf-data360 observability data, then reproduce locally with agentscript_preview, fix via agentscript_authoring, verify with agentscript_eval, and ship with agentscript_lifecycle.
