Agent Script Blocks

A script consists of blocks where each block contains a set of properties. These properties can describe data or procedures. Agent Script contains several different block types.

Agent Script Blocks

This section gives you a high-level understanding of each block type.

System Block

The system block contains general instructions for the agent. This information includes a list of message prompts that the agent uses during specific scenarios. welcome and error are required messages:

For multiline messages, use the pipe symbol (”|”)
To personalize messages or include other context information, use linked variables.

For example, to dynamically inject the user’s preferred name into the welcome message, use {!@variables.userPreferredName}.

In this example, if the userPreferredName is Sam, customers see the welcome message “Hi Sam! I’m your personal shopping assistant”.

1system:
2    instructions:|
3        You are an AI agent. Have a friendly conversation with the user.
4
5    messages:
6        welcome:|
7            Welcome  {!@variables.userPreferredName}! I'm your personal shopping assistant.
8
9            I can help you:
10            - Find products and check availability
11            - Track your orders
12            - Process returns and refunds
13            - Answer questions about our policies
14
15            How can I assist you today?
16        error: "Whoops!"

Config Block

The config block contains configuration parameters that define the agent.

Parameter	Description
`developer_name`	The Salesforce API name of the agent (max 80 chars). Must start with a letter, contain only alphanumeric and underscores, and can’t end with underscore or have consecutive underscores. Must be unique in your org - you can’t have two agents with the same `developer_name`.
~~`default_agent_user`~~	Deprecated in this block. Specify `default_agent_user` in the Access Block.
`agent_label`	Optional. The agent’s label, displayed in the UI. Auto-generated from `developer_name` if not provided.
`description`	Description of the agent’s goals and purpose.
`company`	Optional. Information about your company.
`role`	Optional. The agent’s role. For example, “Help the customer select the perfect gift.”
`agent_version`	The agent’s version. Set automatically when you create a new version of your agent.
`agent_type`	Optional. The type of agent. Currently, allowed values are `AgentforceServiceAgent` (default) or `AgentforceEmployeeAgent`. Set automatically when you create an agent from a template.
`enable_enhanced_event_logs`	Optional. Indicates whether to enable conversation logging for debugging and monitoring. Allowed values are `True` or `False`. Default: `False`.
`user_locale`	Optional. User locale setting.

Example Config Block

1config:
2    developer_name: "Demo_Agent_1"
3    agent_label: "Demo Agent"
4    description: "This is my demo agent"

Access Block

The access block defines the agent’s default user.

Parameter	Description
`default_agent_user`	API name or ID of the default Salesforce user that is used to run this agent. Required for Agentforce Service agents.

1access:
2    default_agent_user: "service@example.com"

Variables Block

The variables block contains the list of global variables that the agent and script can use. See Variables.

1variables:
2    string_var: mutable string = "hello world"
3    hotel_info: mutable string = "Dreamforce Hotel"

You reference variables throughout the script by using the syntax @variables.<variable_name>.

Language Block

The language block defines which languages the agent supports.

1language:
2    default_locale: "en_US"
3    additional_locales: ""
4    all_additional_locales: False

For a list of supported languages, see Agentforce Language Support.

Connection Block

You can use the connection block to describe how this agent interacts with outside connections. For instance, this code snippet shows how the agent interacts with Enhanced Chat.

1connection messaging:
2    escalation_message: "One moment while I connect you to the next available service representative."
3    outbound_route_type: "OmniChannelFlow"
4    outbound_route_name: "agent_support_flow"
5    adaptive_response_allowed: True

You can use the connection block alongside the @utils.escalate command.

Subagent Blocks

Use the subagent block to specify the instructions, logic, and actions for a subagent. A subagent block contains a description, a list of actions, and the reasoning instructions. To define a connection to another Agentforce agent in your Salesforce org, see Connected_Subagent Blocks (Beta) .

1subagent Order_Management:
2    description: "Handles order lookup, order updates, and summaries including status, date, location, items, and driver."
3
4    reasoning:
5        instructions: ->
6            if @variables.order_summary == "":
7                run @actions.lookup_current_order
8                with member_email=@variables.member_email
9                set @variables.order_summary=@outputs.order_summary
10
11            | Refer to the user by name {!@variables.member_name}.
12              Show their current order summary: {!@variables.order_summary} when conversation starts or if requested.
13              If they want past order info, ask for Order ID and use {!@actions.lookup_order}.
14
15        actions:
16            lookup_order: @actions.lookup_order
17                with query = ...
18                set @variables.order_summary=@outputs.order_summary
19                set @variables.order_id=@outputs.order_id
20
21            lookup_current_order: @actions.lookup_current_order
22                with member_email=@variables.member_email
23                set @variables.order_summary=@outputs.order_summary
24                set @variables.order_id=@outputs.order_id
25
26    actions:
27        lookup_order:
28            description: "Retrieve order details."
29            inputs:
30                query: string
31            outputs:
32                order_summary: string
33                order_id: string
34            target: "flow://SvcCopilotTmpl__GetOrdersByContact"
35
36
37        lookup_current_order:
38            description: "Retrieve current order details."
39            inputs:
40                member_email: string
41            outputs:
42                order_summary: string
43                order_id: string
44            target: "flow://SvcCopilotTmpl__GetOrderByOrderNumber"

These properties make up a subagent block:

subagent name: This value is the name of the subagent that should accurately describe the scope and purpose of this subagent in a few words. Because this value can’t have spaces, use snake_case to name the subagent.
description: This property contains the description for this subagent. This value should help the agent determine when to use this subagent based on the user’s intent.
system.instructions (optional): Override system-level system instructions for this subagent only. By overriding system-level instructions, you can avoid giving conflicting intructions to the LLM, which can cause unexpected agent behavior. You can also change the agent’s voice & tone for a specific subagent. See Avoid Conflicting Instructions with Instruction Overrides.
reasoning: This section contains information sent to the reasoning engine. Its primary properties are instructions and actions.
- reasoning.instructions: This property contains guidance for the reasoning engine after it has decided that this subagent is relevant to the user’s request. The reasoning instructions can be a combination of logic instructions and prompt-based instructions. See Reasoning Instructions.
- reasoning.actions: The list of tools that are applicable for the reasoning engine to use. This list can point to agent actions listed in the higher-level actions section, as well as other functionality available to the reasoning engine (such as transitioning to another subagent, or setting a variable’s value). See Tools (Reasoning Actions).
actions: This section defines the agent actions available from this subagent. It contains a description of the action, the list of inputs and outputs, and the target location where this action resides. If you want to allow the reasoning engine to use one of these agent actions, you must also point to this action from the reasoning.actions section. See Actions.

Connected_Subagent Blocks (Beta)

Multi-Agent Orchestration (connected subagents) is a pilot or beta service that is subject to the Beta Services Terms at Agreements - Salesforce.com or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the Product Terms Directory. Use of this pilot or beta service is at the Customer’s sole discretion.

Note

Use the connected_subagent block to define a connection to another Agentforce agent in your Salesforce org. A connected subagent is different from a subagent that’s part of your current agent. You can use a connected subagent in a reasoning action to delegate tasks to another Agentforce agent.

For more information about using multiple agents in a Salesforce org, see Multi-Agent Orchestration (Beta).

1connected_subagent CRM_Agent:
2    label: "CRM_Agent"
3    target: "agentforce://X00Dfi200000dpFZ_CRM_Agent"
4    loading_text: |
5        Fetching CRM information....
6    description: "Use this tool for any request about CRM information"
7    # define input variables that you'll use to pass information to the connected agent
8    inputs:
9        EndUserLanguage: string = @variables.EndUserLanguage
10        currentRecordId: string = @variables.currentRecordId

1start_agent agent_router:
2    label: "Agent Router"
3    description: "Welcome the user and determine the appropriate subagent based on user input"
4    reasoning:
5        instructions: ->
6            | Select the best tool to call based on conversation history and user's intent.
7        actions:
8            # transition to a subagent
9            go_to_off_topic: @utils.transition to @subagent.off_topic
10
11            # Route to the CRM_Agent connected subagent
12            crm_agent: @connected_subagent.CRM_Agent

These properties make up a connected_subagent block:

connected_subagent name: The name used to reference this connected subagent elsewhere in your Agent Script.
target: The URI identifying the external agent. This value is filled in when you connect an agent as a subagent in Agentforce Builder.
label (optional): A human-readable label for the connected subagent.
description (optional): Describes the connected subagent’s capabilities or when it should be called. This description helps the reasoning engine decide when to delegate to the subagent.
loading_text (optional): A message shown to the customer while the connected subagent runs.
inputs (optional): Values passed to the connected subagent. Each input binding has two sides:
- The left side (for example, customer_id) is a linked, or context, variable defined in the connected subagent (that is, in the other Agentforce agent). Names a value that the connected subagent expects to receive.
- The right side (for example, @variables.Customer_Id) binds the connected subagent’s input to a variable in the calling agent. Can be any variable type.
For example, suppose your input is customer_id: string = @variables.Customer_Id. The connected subagent’s customer_id variable receives the value of the calling agent’s Customer_Id variable.

Start Agent Block

The start agent block (called the “Agent Router” in Canvas view) is a subagent that uses the start_agent prefix instead of the subagent prefix. With every customer utterance, the agent begins execution at this block. The start_agent subagent is used to initiate the conversation, and typically determines when to switch to the agent’s other subagents. This block handles subagent classification, filtering, and routing.

1start_agent agent_router:
2    description: "Welcome the user and determine the appropriate subagent based on user input"
3    reasoning:
4        instructions: |
5            You are an agent router for this assistant. Welcome the guest
6            and analyze their input to determine the most appropriate subagent
7            to handle their request.
8        actions:
9            go_to_identity: @utils.transition to @subagent.Identity_Verification
10                description: "Verifies user identity"
11                available when @variables.verified == False
12            go_to_order: @utils.transition to @subagent.Order_Management
13                description: "Handles order lookup, refunds, and order updates."
14                available when @variables.verified == True
15            go_to_faq: @utils.transition to @subagent.General_FAQ
16                description: "Handles various frequently asked questions."
17                available when @variables.verified == True
18            go_to_escalation: @utils.transition to @subagent.Escalation
19                description: "Handles escalation to a human rep."
20                available when @variables.verified == True and @variables.is_business_hours == True

For more guidance on how to use the start agent block for subagent routing and filtering, see Subagent Classification and Routing in Salesforce Help.

Agent Script Blocks

System Block

Config Block

Example Config Block

Access Block

Variables Block

Language Block

Connection Block

Subagent Blocks

Connected_Subagent Blocks (Beta)

Start Agent Block

Related Topics