Agent Script Skill

What This Skill Is For

This skill is for developing Agentforce agents, primarily with Agent Script, Salesforce's scripting language for AI agents.

⚠️CRITICAL: Agent Script is NOT AppleScript, JavaScript, Python, or any other language. Do NOT confuse Agent Script syntax or semantics with any other language you have been trained on.

Agent Script agents are defined by AiAuthoringBundle metadata: a .agent file (agent behavior) plus bundle-meta.xml (bundle metadata). Actions can be implemented with invocable Apex, autolaunched Flows, Prompt Templates, and other supported types.

This skill covers the full Agent Script lifecycle: designing agents, writing Agent Script code, validating and debugging, deploying and publishing, and testing.

How to Use This Skill

This file maps user intent to task domains and relevant reference files in references/. Treat this file as the execution router for end-to-end agent development, and use references for deep detail.

Identify user intent from task descriptions. ALWAYS read indicated reference files BEFORE starting work.

Rules That Always Apply

1. Always --json. ALWAYS include --json on EVERY sf CLI command. Do NOT pipe CLI output through jq or 2>/dev/null. Read the full JSON response directly — LLMs parse JSON natively.

2. Verify target org. Before any org interaction, run sf config get target-org --json to confirm a target org is set. If none configured, ask the user to set one with sf config set target-org <alias>.

3. Diagnose before you fix. When validating/debugging agent behavior, ALWAYS --use-live-actions to preview authoring bundles. Send utterances then read resulting session traces to ground your understanding of the agent's behavior. Trace files reveal subagent selection, action I/O, and LLM reasoning. DO NOT modify .agent files or action implementations without this grounding. See Validation & Debugging for trace file locations and diagnostic patterns.

4. Spec approval is a hard gate. Never proceed past Agent Spec creation without explicit user approval.

5. Don't stall. After a step completes successfully, announce the next step and start it. Do not wait for the user to say "what's next" or "ok, continue." The only checkpoints that require explicit user approval are: (a) Agent Spec approval, (b) the pre-Publish CHECKPOINT, (c) any A/B branch the skill explicitly surfaces (e.g., Data Cloud not provisioned during ADL setup). Long-running async work like ADL indexing should run in the background while the skill continues with work that doesn't depend on the result.

6. Draft-first lifecycle. During normal authoring, stay in draft iteration: edit .agent + action implementations, validate, deploy, and preview as many times as needed. Do NOT publish/activate by default. Publish + activate are explicit release actions that require the user to confirm they are ready to commit the current draft to metadata and expose it to end users.

7. Default agentic, pin with cause. Use the most agentic posture that meets each subagent's requirement, and add deterministic controls only for regulation/trust gates or observed failures. For detailed posture rules, see Posture & Determinism.

8. No nested if or else if. Agent Script only supports flat if/else blocks. No else if, no if inside else, no if inside if. For multi-branch logic, use sequential if statements or compound conditions (if A and B:). Nested structures cause silent compile failures.

9. Action implementation is a user decision. During planning/spec work, default new actions to NEEDS STUB placeholders. Always ask the user whether they want to scan org/project for existing implementations and/or generate new Apex/Flow/Prompt implementations before taking either path.

Task Domains

Every task domain below has Required Steps. Follow verbatim, in order. The default path is: design -> draft implementation loop -> validation/preview loop -> explicit user-approved release.

Create an Agent

User wants to build new agent from scratch. ALWAYS use Agent Script. Work with User to understand the agent's purpose, subagents, and actions using plain language without Salesforce-specific terminology.

Required Steps

Read CLI for Agents for exact command syntax.

1. Design — Read Design & Agent Spec to draft an Agent Spec. Default all new actions to NEEDS STUB placeholders during planning. Ask the user which implementation path they want before implementation work:
   • Path A: Keep placeholders only (no implementation now)
   • Path B: Scan for existing actions to reuse
   • Path C: Generate new actions Only run scans (reading sfdx-project.json, searching @InvocableMethod, AutoLaunchedFlow, prompt templates, external service registrations, standard invocable actions, and custom objects) if the user explicitly chooses Path B or C. If the agent's purpose involves answering from documents (e.g., "answer customer questions from our product manual", "respond based on a policy guide", "FAQ from a PDF"), ask the user: "Will this agent answer questions from a document corpus (PDF/DOCX/TXT)? If so, what file path?" Capture the path in the Spec under a "Knowledge Grounding" section. Asking now — during requirements capture — is critical: ADL indexing takes minutes, so we want the file path captured pre-Spec-approval and provisioning kicked off as early as possible. Always save Agent Spec as file.
2. STOP for user approval of Agent Spec. Present to user (including the Knowledge Grounding section if present). Ask for approval or feedback. Do not proceed without approval. Once approved, proceed without stopping unless a step fails.
3. Validate environment prerequisites — Read Design & Agent Spec, Section 3 (Environment Prerequisites). Based on agent type from design, validate org environment:
   • Employee agent: Confirm config block does NOT include default_agent_user, connection messaging:, or MessagingSession linked variables. Remove if present. See Examples for a complete employee agent example.
   • Service agent: Query org for Einstein Agent User. If one exists, confirm username with user. If none, guide user through creation. See CLI for Agents, Section 12 for creation steps and Agent User Setup for required permissions. 3b. Kick off ADL provisioning (only if the Spec has a Knowledge Grounding section). Read Data Library Reference. Run the Step 0 preflight: SELECT COUNT() FROM DataKnowledgeSpace (DC provisioned check), then GET /einstein/data-libraries (ADL service health check). If DC is not provisioned, present the A/B choice from that reference. If DC is provisioned but the ADL service returns 400 INTERNAL_ERROR, surface the "DC up, ADL broken" path and skip grounding for this run. If both checks pass, run the create POST (reference Step 1) to capture libraryId. Compute rag_feature_config_id = "ARFPC_<libraryId>" from the libraryId alone — that's enough to author the bundle. Then start the upload + indexing flow (reference Steps 2–6) in the background while authoring continues. Per Rule 5, do not block on async indexing; retrieverId is only needed for runtime queries (gated in Step 8). Also kick off the Data Cloud permset assignment for the agent user — see Agent User Setup, Step 2b for the discovery-then-assign procedure. **Do not proceed to code generation until environment is va