Agent Script | Agentforce Developer Cheat sheet

Here is a developer cheat sheet summarizing the key commands, syntax, and patterns for building Agentforce agents using Agentforce DX and Agent Script.

💻 Agentforce DX CLI Commands

Run these commands from your local Salesforce DX project using the integrated terminal (or via the VS Code Command Palette):

• Generate Agent Spec: sf agent generate agent-spec (Creates a YAML file with LLM-generated topics based on your company description).
• Generate Authoring Bundle: sf agent generate authoring-bundle (Creates the AiAuthoringBundle metadata containing the .agent script file).
• Validate Script: sf agent validate authoring-bundle (Checks your .agent script for syntax/compilation errors).
• Publish Agent: sf agent publish authoring-bundle (Compiles the script and generates the Bot and GenAi metadata in your org).
• Preview Agent: sf agent preview (Starts an interactive chat to test your agent. Use --use-live-actions for Live mode).
• Generate Test Spec: sf agent test create (Creates a YAML file defining utterances, expected topics, and outcomes).
• Run Automated Tests: sf agent test run (Executes tests. Use --verbose to see generated JSON data).

🧱 Agent Script Structure (Top-Level Blocks)

An Agent Script is a property-based language using key: value pairs. It is divided into core blocks:

• config: Sets foundational details like the agent's display label and developer name.
• system: Defines global instructions, personas, and standard messages (like welcome and error).
• variables: Defines global state variables used across all topics.
• start_agent: The topic selector. This is the entry point for every conversation, responsible for classifying intent and routing the user to the correct topic.
• topic: Defines a specific job. Contains the topic description, actions, and reasoning instructions.

✍️ Syntax & Formatting Rules

• Indentation: Whitespace-sensitive. You must use either spaces (at least 2) or tabs consistently. Mixing spaces and tabs causes compilation errors.
• Logic Instructions (->): Deterministic programmatic commands that execute before the prompt is sent to the LLM (e.g., setting variables, running actions, if/else conditions).
• Prompt Instructions (|): Multiline natural language directives passed directly to the LLM.
• Comments (#): Anything following the # on a line is ignored.

🔗 Referencing Resources

Use the @ symbol to reference resources, and curly brackets to inject them directly into LLM prompts.

• Reference a Variable: @variables.<variable_name>
• Inject Variable into Prompt: {!@variables.<variable_name>}
• Reference an Action: @actions.<action_name>
• Explicitly guide LLM to Action/Topic in Prompt: {!@actions.<name>} or {!@topics.<name>}

🧮 Operators & Conditionals

Agent Script supports standard flow control. Note that else if is not currently supported.

• Comparison: ==, !=, <, >, <=, >=
• Null Checks: is None, is not None (Use is None for unassigned values, not == "").
• Logical: and, or, not
• Arithmetic: +, -

🛠️ Actions vs. Tools (Reasoning Actions)

• Topic Actions (topic.actions): Run deterministically inside logic instructions using the run command. Because the LLM is not involved, you must manually bind variables to inputs using with and capture outputs using set.
• -> run @actions.get_weather with city = @variables.city -> set @variables.temp = @outputs.temperature
• Tools (topic.reasoning.actions): Actions exposed to the LLM. The LLM subjectively decides when to use them based on their description and the conversation context.

🧩 Common Patterns & Utility Functions

1. Filtering (Enforcing Business Rules) Use available when to completely hide topics or reasoning actions from the LLM unless a specific condition is met, preventing hallucination or unauthorized access.

available when: @variables.is_verified == True

2. Deterministic Transitions Use @utils.transition to in logic instructions to force a user to a required topic (like Identity Verification) before the LLM does any reasoning.

-> if @variables.is_verified == False
  -> run @utils.transition to @topics.identity_verification

3. Slot Filling (Extracting User Input) Use @utils.setVariables alongside the ... token to instruct the LLM to use its reasoning to extract information from the user's natural language and save it to a variable.

-> run @utils.setVariables with @variables.first_name = ...

4. System Overrides Add a system.instructions block inside a specific topic to override the global agent persona/instructions for that specific context (e.g., using a formal tone for compliance, and a casual tone for FAQs).

5. Escalation Use the built-in escalation utility (requires an active Omni-Channel connection block).

-> run @utils.escalate

[embed]Unlock Powerful Features of the New Agentforce Builder Discover the new Agentforce Builder and its groundbreaking features. Learn how to create, customize, and test AI agents…trailhead.salesforce.com

[embed]Salesforce Help Knowledgehelp.salesforce.com

[embed]Agent Script: Scripting Language for Reliable AI Agents Agent Script is the first scripting language for AI agents. Get precise control, blend deterministic rules with agentic…www.salesforce.com