Agent Script DSL for deterministic Agentforce agents. TRIGGER when: user writes or edits .agent files, builds FSM-based agents, uses Agent Script CLI (sf agent generate authoring-bundle, sf agent validate authoring-bundle, sf agent preview, sf agent publish authoring-bundle, sf agent activate), or a

SF AI AgentScript Skill Agent Script is the code first path for deterministic Agentforce agents. Use this skill when the user is authoring .agent files, building finite state topic flows, or needs repeatable control over routing, variables, actions, and publish behavior. Start with the shortest guide first: [references/activation checklist.md](references/activation checklist.md) Migrating from the Builder UI? Use [references/migration guide.md](references/migration guide.md) When This Skill Owns the Task Use sf ai agentscript when the work involves: creating or editing .agent files deterministic topic routing, guards, and transitions Agent Script CLI workflows ( sf agent generate authoring bundle , sf agent validate authoring bundle , sf agent preview , sf agent publish authoring bundle , sf agent activate ) slot filling, instruction resolution, post action loops, or FSM design Delegate elsewhere when the user is: maintaining Builder metadata agents ( GenAiFunction , GenAiPlugin , GenAiPromptTemplate , Models API, custom Lightning types) → [sf ai agentforce](../sf ai agentforce/SKILL.md) designing persona / tone / voice → [sf ai agentforce persona](../sf ai agentforce persona/SKILL.md) building formal test plans or coverage loops → [sf ai agentforce testing](../sf ai agentforce testing/SKILL.md) If the user is in Builder Script / Canvas view but the outcome is a .agent authoring bundle, keep the work in sf ai agentscript . Right Size Determinism Determinism is a dial, not a destination. Use Agent Script when “mostly right” is not acceptable: gates, mandatory sequencing, explicit state transitions, compliance, or drift control. If a workflow is fully static and linear, use Flow or Apex instead of scripting the conversation. Prefer a deterministic envelope: deterministic entry/gate → flexible middle → deterministic closeout. More determinism is not automatically better. Start minimal, then harden only the parts that show routing drift, sequencing failures, or compliance risk. Required Context to Gather First Ask for or infer: agent purpose and whether Agent Script is truly the right fit Service Agent vs Employee Agent target org and publish intent expected actions / targets (Flow, Apex, PromptTemplate, etc.) whether the request is authoring, validation, preview, or publish troubleshooting Activation Checklist Before you author or fix any .agent file, verify these first: 1. Exactly one start agent block 2. No mixed tabs and spaces 3. Booleans are True / False 4. No else if and no nested if 5. No top level actions: block 6. No @inputs in set expressions 7. linked variables have no defaults 8. linked variables do not use object / list types 9. Use explicit agent type 10. Use @actions. prefixes consistently 11. Use run @actions.X only when X is a topic level action definition with target: 12. Do not branch directly on raw @system variables.user input contains/startswith/endswith for intent routing 13. On prompt template outputs, prefer is displayable: False + is used by planner: True 14. Do not assume @outputs.X is scalar — inspect the output schema before branching or assignment For the expanded version, use [references/activation checklist.md](references/activation checklist.md). Non Negotiable Rules 1) Service Agent vs Employee Agent Agent type Required Forbidden / caution AgentforceServiceAgent Valid default agent user , correct permissions, target org checks, prefer sf org create agent user Publishing without a real Einstein Agent User AgentforceEmployeeAgent Explicit agent type Supplying default agent user Full details: [references/agent user setup.md](references/agent user setup.md) 2) Recommended top level block convention Use this order for consistency in this skill's examples and reviews: Official Salesforce materials present top level blocks in differing sequences, and local validation evidence indicates multiple orderings compile. Treat this as a style convention, not a standalone correctness or publish blocker. 3) Critical config fields Field Rule developer name Must match folder / bundle name description Public docs/examples should use this config field agent type Set explicitly every time default agent user Service Agents only Local tooling also accepts agent description: for compatibility, but this skill's public docs and examples should prefer description: . 4) Syntax blockers you should treat as immediate failures else if nested if comment only if bodies top level actions: invocation level inputs: / outputs: blocks reserved variable / field names like description and label Canonical rule set: [references/syntax reference.md](references/syntax reference.md) and [references/validator rule catalog.md](references/validator rule catalog.md) Recommended Workflow Recommended Authoring Workflow Phase 1 — design the agent decide whether the problem is actually deterministic enough for Agent Script model topics as states and transitions as edges define only the variables you truly need Phase 2 — author the .agent create config , system , start agent , and topics first add target backed actions with full inputs: and outputs: use available when for deterministic tool visibility normalize raw intent/validation signals into booleans or enums before branching; avoid direct substring checks on raw user utterances for critical control flow keep post action checks at the top of instructions: Default authoring stance Default to direct .agent authoring and edits in source control. Use sf agent generate authoring bundle no spec only when the user wants local bundle scaffolding. Treat sf agent generate agent spec as optional ideation / topic bootstrap, not the default workflow. Do not route Agent Script users toward sf agent create or sf agent generate template . Phase 3 — validate continuously Validation already runs automatically on write/edit. Use the CLI before publish: The validator covers structure, runtime gotchas, target readiness, and org aware Service Agent checks. Rule IDs live in [references/validator rule catalog.md](references/validator rule catalog.md). Phase 4 — preview smoke test Use the preview loop before publish: derive 3–5 smoke utterances start preview with the start / send / end subcommands, not bare sf agent preview if you use authoring bundle , always choose a mode explicitly: simulate actions or use live actions inspect topic routing / action invocation / safety / grounding fix and rerun up to 3 times Full loop: [references/preview test loop.md](references/preview test loop.md) Phase 5 — publish and activate Publishing does not activate the agent. For automation, prefer version <n json so activation is deterministic and machine readable. Deterministic Building Blocks These execute as code, not suggestions: conditionals available when guards variable checks direct set / transition to run @actions.X only when X is a topic level action definition with target: variable injection into LLM facing text Important distinction: Deterministic : set , transition to , and run @actions.X for a target backed topic action LLM directed : reasoning.actions: utilities / delegations such as @utils.setVariables , @utils.transition , and {!@actions.X} instruction references If you need deterministic behavior for something that is currently modeled as a reasoning level utility, either: rewrite it as direct set / transition to , or promote it to a topic level target backed action and run that action See [references/instruction resolution.md](references/instruction resolution.md) and [references/architecture patterns.md](references/architecture patterns.md). Cross Skill Integration Cross Skill Orchestration Task Delegate to Why Build flow:// targets [sf flow](../sf flow/SKILL.md) Flow creation / validation Build Apex action targets [sf apex](../sf apex/SKILL.md) @InvocableMethod and business logic Test topic routing / actions [sf ai agentforce testing](../sf ai agentforce testing/SKILL.md) Formal test specs and fix loops Deploy / publish [sf deploy](../sf deploy/SKILL.md) Deployment orchestration High Signal Failure Patterns Symptom Likely cause Read next Internal Error during publish invalid Service Agent user or missing action I/O [references/agent user setup.md](references/agent user setup.md), [references/actions reference.md](references/actions reference.md) invalid input/output parameters on prompt template action Target template is in Draft status — activate it first [references/action prompt templates.md](references/action prompt templates.md draft template publish errors) Parser rejects conditionals else if , nested if , empty if body [references/syntax reference.md](references/syntax reference.md) Action target issues missing Flow / Apex target, inactive Flow, bad schemas [references/actions reference.md](references/actions reference.md) Prompt template runs but user sees blank response prompt output marked is displayable: True [references/production gotchas.md](references/production gotchas.md), [references/action prompt templates.md](references/action prompt templates.md) Prompt action runs but planner behaves like output is missing output hidden from direct display but not planner visible [references/production gotchas.md](references/production gotchas.md), [references/actions reference.md](references/actions reference.md) ACTION NOT IN SCOPE on run @actions.X run points at a utility / delegation / unresolved action instead of a topic level target backed definition [references/syntax reference.md](references/syntax reference.md), [references/instruction resolution.md](references/instruction resolution.md) Deterministic cancel / revise / URL checks behave inconsistently raw @system variables.user input matching or string method guards are being used as control flow critical validation [references/syntax reference.md](references/syntax reference.md), [references/production gotchas.md](references/production gotchas.md) @outputs.X comparisons or assignments behave unexpectedly the action output is structured/wrapped, not a plain scalar [references/actions reference.md](references/actions reference.md), [references/syntax reference.md](references/syntax reference.md) Preview and runtime disagree linked vars / context / known platform issues [references/known issues.md](references/known issues.md) Validate passes but publish fails org specific user / permission / retrieve back issue [references/production gotchas.md](references/production gotchas.md), [references/cli guide.md](references/cli guide.md) Reference Map Start here [references/activation checklist.md](references/activation checklist.md) [references/syntax reference.md](references/syntax reference.md) [references/actions reference.md](references/actions reference.md) Publish / runtime safety [references/agent user setup.md](references/agent user setup.md) [references/production gotchas.md](references/production gotchas.md) [references/customer web client.md](references/customer web client.md) [references/known issues.md](references/known issues.md) Architecture / reasoning [references/architecture patterns.md](references/architecture patterns.md) [references/instruction resolution.md](references/instruction resolution.md) [references/fsm architecture.md](references/fsm architecture.md) [references/patterns quick ref.md](references/patter

sf-ai-agentscript