Building a agent with agentforce script in Salesforce

Agent Script is a language used to build agents in Agentforce Builder. It uses natural language for conversations and programmatic logic for business rules.

But simple goals often require thoughtful engineering. Let's break down how the agent is structured and why each decision matters.

How to create agentscript

• Click on app launcher and search for Agentforce Studio.
• Now click on New Agent button to create a new agent.
• New page will be open and where you can go with custom agent and ready-made agents. We will go with custom agent.
• Enter the purpose of your agent or what you'd like it to do.
• Now click Send button. to generate the agent.
• It will generate the agent script based on your purpose and here is the final script you can follow:

The system block

The system block gives general instructions to the agent. It also includes message prompts used in different situations. The welcome and error messages are required.

For multiline messages, use the pipe symbol (|). To personalize messages, you can use variables. For example, use {!@variables.userPreferredName} to show the user’s name in the welcome message.

system:
    instructions: "You are a friendly and empathetic agent that helps customers with their questions."
    messages:
        error: "Sorry, something went wrong."
        welcome: "Hello! How are you feeling today?"

The config block

Every Agentforce agent starts with a config block that establishes identity. This block define metadata about the agent such as its name, agent user, label etc. Here "default_agent_user" is a einstein user that will be used to invoke the agent. Make sure you have created this user in salesforce and have assigned appropriate permissions to it. We can add more property in config block:

config:
    developer_name: "BookAgent"
    agent_label: "Book Agent"
    default_agent_user: "custom_service_agent@00dg5000002y0z71166583081.ext"
    description: "Show the available books to user"

The variables block

Variables help the agent remember information, track progress, and keep context during a conversation. You define variables in the variables block, and all sub-agents can use them.

There are three types of variables:

• Regular variable: You can give it a default value, and the agent can update it later.
• Linked variable: Its value comes from an output (like an action result). It cannot have a default value.
• System variable: These are already created by the system and ready to use.

Variable naming rules:

• Must start with a letter (not an underscore)
• Can contain letters, numbers, and underscores only
• Cannot end with an underscore
• Cannot have double underscores (__)
• Maximum length is 80 characters

mutable - Optional. Allows the agent to change the variable's value. To ensure a variable's value is never changed, define the variable without mutable.

variables:
    book_name: mutable string
        description: "Capture the book name"
        label: "book name"
    book_number: mutable string
        description: "Capture the book number"
        label: "book number"
    book_detail: mutable object
        description: "Store the book detail"
        label: "book detail"
    active_flow: mutable string
        label: "active_flow"
        description: "Track which workflow is currently in progress. Values: bookDetail or empty string for none."

The agent router

The start agent block (called Agent Router in Canvas view) is a special sub-agent that uses the start_agent prefix. The agent starts from this block every time a user sends a message.

It is used to begin the conversation and decide when to move to other sub-agents. It also handles classification, filtering, and routing of requests.

start_agent agent_router:
    description: "Welcome the user and determine the appropriate subagent based on user input"

    reasoning:
        instructions: ->
            if @variables.active_flow == "bookInfo":
                transition to @subagent.book_management
            | Welcome the guest and analyze their input to determine the most appropriate subagent to handle their request.

        actions:
            go_to_book_management: @utils.transition to @subagent.book_management
                description: "Invoke when user want to request about books"

The pipe character (|) introduces a natural language instruction to the LLM. This is the key design philosophy of Agentforce: declarative conditions check structured state; prose instructions guide the model's language behaviour.

The Topic and Action: connecting AI with Salesforce Data

The Retrieve_Book_Detail action connects the agent to real Salesforce data using an Apex invocable class:

subagent book_management:
    description: "Show the book detail, summarizes book."
    reasoning:
        instructions: ->
            set @variables.active_flow = "bookInfo"

            if @variables.book_name is None and @variables.book_name == "" or @variables.book_number is None and @variables.book_number == "":
                | Ask the customer for book name or book number to get the specific book detail. Invoke {!@actions.set_bookname} to set the book name. Or Invoke {!@actions.set_bookNumber} to set the book number.
            if @variables.book_name is not None and @variables.book_name != "" or @variables.book_number is not None and @variables.book_number != "":
                | To find the book detail invoke this action {!@actions.go_to_retrieve_book_detail}
                set @variables.active_flow = ""

        actions:
            set_bookname: @utils.setVariables
                description: "Set the book name when they provide it."
                with book_name = ...
            set_bookNumber: @utils.setVariables
                description: "Set the book number when they provide it."
                with book_number = ...
            go_to_retrieve_book_detail: @actions.Retrieve_Book_Detail
                with bookName = @variables.book_name
                with bookNumber = @variables.book_number
                set @variables.book_detail = @outputs.bookingInformation

    actions:
        Retrieve_Book_Detail:
            label: "Retrieve Book Detail"
            description: |Display the specific book detail when they provide the book number or book name.
            target: "apex://BookRetrieveAction"
            inputs:
                bookName: string
                    label: "Book Name"
                    description: "Enter the book name"
                    is_required: False
                    complex_data_type_name: "lightning__textType"
                bookNumber: string
                    label: "Book Number"
                    description: "Enter the book number"
                    is_required: False
                    complex_data_type_name: "lightning__textType"
            outputs:
                bookingInformation: object
                    label: "bookingInformation"
                    complex_data_type_name: "@apexClassType/c__BookRetrieveAction$AvailableBookDetail"
                    is_displayable: False
                    filter_from_agent: False
                    

Both inputs are optional — the Apex class handles either a name or a number. The output is a strongly-typed Apex inner class (AvailableBookDetail), ensuring the agent always receives well-structured data it can reason over or display directly to the user.

Putting it all together: a complete Agentforce bot

config:
    developer_name: "BookAgent"
    agent_label: "Book Agent"
    default_agent_user: "custom_service_agent@00dg5000002y0z71166583081.ext"
    description: "Show the available books to user"
        
system:
    instructions: "You are a friendly and empathetic agent that helps customers with their questions."
    messages:
        error: "Sorry, something went wrong."
        welcome: "Hello! How are you feeling today? Phenoble is known for its phenomenal work in the field and its relationships with clients are great. Our success stems from our core values, which guide everything we do. We believe in trust, equality, and inclusivity."

variables:
    book_name: mutable string
        description: "Capture the book name"
        label: "book name"
    book_number: mutable string
        description: "Capture the book number"
        label: "book number"
    book_detail: mutable object
        description: "Store the book detail"
        label: "book detail"
    active_flow: mutable string
        label: "active_flow"
        description: "Track which workflow is currently in progress. Values: bookDetail or empty string for none."

start_agent agent_router:
    description: "Welcome the user and determine the appropriate subagent based on user input"

    reasoning:
        instructions: ->
            if @variables.active_flow == "bookInfo":
                transition to @subagent.book_management
            | Welcome the guest and analyze their input to determine the most appropriate subagent to handle their request.

        actions:
            go_to_book_management: @utils.transition to @subagent.book_management
                description: "Invoke when user want to request about books"

subagent book_management: description: "Show the book detail, summarizes book." reasoning: instructions: -> set @variables.active_flow = "bookInfo"

        if @variables.book_name is None and @variables.book_name == "" or @variables.book_number is None and @variables.book_number == "":
            | Ask the customer for book name or book number to get the specific book detail. Invoke {!@actions.set_bookname} to set the book name. Or Invoke {!@actions.set_bookNumber} to set the book number.
        if @variables.book_name is not None and @variables.book_name != "" or @variables.book_number is not None and @variables.book_number != "":
            | To find the book detail invoke this action {!@actions.go_to_retrieve_book_detail}
            set @variables.active_flow = ""

    actions:
        set_bookname: @utils.setVariables
            description: "Set the book name when they provide it."
            with book_name = ...
        set_bookNumber: @utils.setVariables
            description: "Set the book number when they provide it."
            with book_number = ...
        go_to_retrieve_book_detail: @actions.Retrieve_Book_Detail
            with bookName = @variables.book_name
            with bookNumber = @variables.book_number
            set @variables.book_detail = @outputs.bookingInformation

actions:
    Retrieve_Book_Detail:
        label: "Retrieve Book Detail"
        description: |Display the specific book detail when they provide the book number or book name.
        target: "apex://BookRetrieveAction"
        inputs:
            bookName: string
                label: "Book Name"
                description: "Enter the book name"
                is_required: False
                complex_data_type_name: "lightning__textType"
            bookNumber: string
                label: "Book Number"
                description: "Enter the book number"
                is_required: False
                complex_data_type_name: "lightning__textType"
        outputs:
            bookingInformation: object
                label: "bookingInformation"
                complex_data_type_name: "@apexClassType/c__BookRetrieveAction$AvailableBookDetail"
                is_displayable: False
                filter_from_agent: False

## Apex class

```java:BookRetrieveAction.apxc

public class BookRetrieveAction {
	@InvocableMethod(label='Retrieve Book Detail' description='Retrieves book details using name or')
    public static List<BookDetailRespon> getBookDetail(List<BookDetailRequest> req) {

        List<BookDetailRespon> testdriveResponses = new List<BookDetailRespon>();

        for(BookDetailRequest input : req) {

            List<Book__c> foundBookDetail = new List<Book__c>();

            if(String.isNotBlank(input.bookName) && String.isNotBlank(input.bookNumber)) {
                foundBookDetail = [SELECT Id, Name, Book_Name__c, Genere__c, Price__c, Quantity__c FROM Book__c WHERE Book_Name__c = :input.bookName OR Name = :input.bookNumber LIMIT 1];
            }
            else if(String.isNotBlank(input.bookName)) {
                foundBookDetail = [SELECT Id, Name, Book_Name__c, Genere__c, Price__c, Quantity__c FROM Book__c WHERE Book_Name__c = :input.bookName LIMIT 1];
            }
            else if(String.isNotBlank(input.bookNumber)) {
                foundBookDetail = [SELECT Id, Name, Book_Name__c, Genere__c, Price__c, Quantity__c FROM Book__c WHERE Name = :input.bookNumber LIMIT 1];
            }

            AvailableBookDetail availableTestDrive = new AvailableBookDetail();
            availableTestDrive.accounts = new List<BookDetailInfo>();

            for(Book__c bk : foundBookDetail) {
                availableTestDrive.accounts.add(new BookDetailInfo(bk));
            }

            BookDetailRespon response = new BookDetailRespon();
            response.bookingInformation = availableTestDrive;

            testdriveResponses.add(response);
        }

        return testdriveResponses;
    }

    @JsonAccess(serializable='always' deserializable='always')
    public class BookDetailRequest {

        @InvocableVariable(label='Book Number' description='Enter the book number')
        public String bookNumber;
        
        @InvocableVariable(label='Book Name' description='Enter the book name')
        public String bookName;
    }

    @JsonAccess(serializable='always' deserializable='always')
    public class BookDetailRespon {

        @InvocableVariable
        public AvailableBookDetail bookingInformation;
    }

    @JsonAccess(serializable='always' deserializable='always')
    public class AvailableBookDetail {

        @AuraEnabled
        public List<BookDetailInfo> accounts;
    }

    @JsonAccess(serializable='always' deserializable='always')
    public class BookDetailInfo { 
        @AuraEnabled
        public String bnumber;
        
        @AuraEnabled
        public String name;
        
        @AuraEnabled
        public String genere;
        
        @AuraEnabled
        public Double price;
        
        @AuraEnabled
        public Double quantity;

        public BookDetailInfo(Book__c bk) {
            this.bnumber = bk.Name;
            this.name = bk.Book_Name__c;
            this.genere = bk.Genere__c;
            this.price = bk.Price__c;
            this.quantity = bk.Quantity__c;
        }
    }
}

Things that you should know

Logic instructions (->) always run in a fixed way. Use them for rules, actions, setting variables, and conditions. Prompt instructions (|) are normal language instructions sent to the AI. The AI understands them and decides how to reply to the user.

1. @variables - To reference a variable from the script, use @variables.<variable_name>. To reference a variable from within reasoning instructions, use {!@variables.<variable_name>}. Example: @variables.book_name

2. utils.transition to - Tells the agent to move to a different subagent. Transitions are one way. There's no return of control to the calling subagent. transition to executes immediately when encountered. The execution of the current directive block is halted, and control is passed to the new subagent.

3. utils.setVariables - Tells the agent to define a variable based on the natural language description. The … token instructs the LLM to set the value of the variable. The description instructs the LLM on how to set the value of the variable.

4. utils.escalate - Tells the agent to escalate to a human service rep. To use utils.escalate, you need an active Omni-Channel connection. This must be defined in a connection messaging block with outbound_route_type and outbound_route_name values.

Note: escalate is a reserved keyword and can't be used for subagent or action names.

5. filter_from_agent - If True, the output is excluded from the agent's context. If False, the output is included in the agent's context. Default value is False.

6. with - It used to bind a input values with the action or subagent. E.g. with book_name = @variables.book_name or with bookName = ...

7. set - It used to set the variable values in the reasoning instructions. E.g set @variables.book_name = @outputs.bookName

8. Use the go_to_ prefix - Name transition actions with a go_to_ prefix (for example, go_to_book_management) so the agent understands they navigate to other subagents.

9. complex_data_type_name - This is a placeholder for the name of the complex data type that will be returned by target.

10. You can access resources, such as actions, subagents, and variables, using the @ symbol.

• @actions.<action_name>: References an action.
• @subagent.<subagent_name>: References a subagent.
• @variables.<variable_name>: References a variable.
• @outputs.<output_name>: References an action output.