developing-agentforce

What this skill does

# 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](references/agent-validation-and-debugging.md)
   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](references/posture-and-determinism.md).

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](references/salesforce-cli-for-agents.md) for exact command syntax.

1. **Design** — Read [Design & Agent Spec](references/agent-design-and-spec-creation.md) 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](references/agent-design-and-spec-creation.md), 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](references/examples.md) 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](references/salesforce-cli-for-agents.md), Section 12 for creation steps and [Agent User Setup](references/agent-user-setup.md) for required permissions.
   **3b. Kick off ADL provisioning (only if the Spec has a Knowledge Grounding section).** Read [Data Library Reference](references/data-library-reference.md). 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](references/agent-user-setup.md), Step 2b for the discovery-then-assign procedure.
   **Do not proceed to code generation until environment is v