Agent Script

An agent is one .agent file inside an authoring bundle: aiAuthoringBundles/<Name>/<Name>.agent plus <Name>.bundle-meta.xml (bundleType AGENT). A complete, linted agent is in guides/agentforce/build-agent-with-agentforce-dx.md.

Check it offline: Salesforce publishes the parser, linter and compiler as open source (github.com/salesforce/agentscript). The hub builds it locally (work/tools/README-aslint.md). sf agent validate authoring-bundle compiles on Salesforce's servers and remains the final word.

Blocks

default_agent_user goes in access. In config it still works but the linter warns: "'default_agent_user' is deprecated: Property default_agent_user has moved from config to access. Move field to access block." A service agent without it fails: "'default_agent_user' is required for AgentforceServiceAgent type agents." Create the user with sf org create agent-user (reference/access/users-permissions-and-agent-users.md).

Keep the recipes' block order (config, variables, system, connection, knowledge, language, start_agent, subagents); the linter accepts others.

Variables

variables:
    account_id: mutable string = ""
        description: "Salesforce ID of the account under review"
    approved: mutable boolean = False
    session_id: linked string
        description: "Messaging session ID"
        source: @MessagingSession.Id

• mutable: the agent reads and writes it. Give it a default. Types: string, number, boolean, object, date, timestamp, currency, id, list[T] (no nested lists).
• linked: read-only, filled from the session. It needs a source and can't have a default, an object type or a list type. The only sources the linter accepts are @MessagingSession (Id, MessagingEndUserId, EndUserLanguage), @MessagingEndUser (ContactId) and @VoiceCall (Id).
• visibility: "External" lets an API (the Agent API, family 5) set a variable; the default is Internal.
• Values: True, False, None, quoted strings and numbers. true fails: "'true' is not a valid value in AgentScript. Did you mean 'True' (capitalized)?"
• System variables: @system_variables.user_input (the latest utterance), .current_modality ("voice" or "text"), .current_connection.

Subagents, reasoning and tools

subagent review_duplicates:
    description: "Find duplicate candidates for an account"
    reasoning:
        instructions: ->
            | Ask for the account if you don't have it.
            if @variables.match_count > 0:
                | {!@variables.match_count} candidates were found.
            else:
                | No candidates yet.
        actions:
            capture_account: @utils.setVariables
                description: "Record the account ID the steward gives"
                with account_id = ...
    after_reasoning:
        if @variables.approved == True:
            transition to @subagent.confirm_merge

• Instructions are -> (a procedure: | lines, if, run, set) or | (a plain multi-line template). A quoted string is only allowed in system. In a subagent it fails: "Expected procedure (->) or template (|) syntax".
• reasoning.actions are tools the LLM may call. Each wraps a subagent action (@actions.x), a utility (@utils.x) or a subagent (@subagent.x). The subagent-level actions: block declares what exists (reference/agentforce/agent-script-actions-and-targets.md).
• On a tool: with param = ... lets the LLM fill a value, with param = @variables.x or a literal binds it, set @variables.y = @outputs.z saves an output, and available when <condition> hides the tool until the condition holds.
• before_reasoning / after_reasoning run logic with no LLM: if, set, run, transition to, but no | lines. after_reasoning runs after the reasoning loop on every request. It's skipped if the subagent transitioned away. Neither is allowed in a subagent that uses the EinsteinHyperClassifier model.
• Names in instruction text: write {!@actions.find_duplicates}, not the bare name.

The four utilities

Conditions, templates and operators

• if / else at the top level of a procedure. A nested if fails: "AgentScript does not support nested 'if' statements. Combine conditions with 'and'/'or', or restructure the logic."
• elif is a syntax error. else if compiles in the current open-source compiler, but Salesforce's docs say it isn't supported, so prefer and/or.
• Templates: {!@variables.x}, with a conditional value {!@variables.s if @variables.s else "pending"}.
• Operators: ==, !=, <, <=, >, >=, is, is not, and, or, not, +, -, . and []. Multiplication fails: "Operator '*' is not supported".

Where Salesforce's sources disagree (October 2026)