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.

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

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!"

The config block contains configuration parameters that define the agent.

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

The runtime block is a sub-block of Config that controls the agent’s runtime behavior.

1config:
2    developer_name: "Demo_Agent_1"
3    runtime:
4        streaming: True
5        thought_chunks: False
6        citation: True
7        groundedness: True
8        reset_to_initial_node: False

The file_upload block, nested inside config, controls how the agent handles files that the customer uploaded during a conversation.

• auto — Default file handling. Uploaded files are made available to the agent using standard behavior.
• managed — Use this mode when you want fine-grained control over which uploaded files reach which subagent. This is the mode that pairs with slice syntax on @system_variables.uploaded_files, so you can pass a specific batch (for example, @system_variables.uploaded_files[0:5]) into an individual subagent.
• disabled — Uploads are rejected without displaying a message to the customer.
• error — Uploads are rejected and treated as an error. If provided, the message in message is shown to the customer. If message isn’t provided, Agentforce generates a message.

1config:
2    developer_name: "Support_Agent"
3    agent_label: "Customer Support Agent"
4    file_upload:
5        mode: "managed"
6        message: "Something went wrong. Try again."

The access block defines the agent’s default user.

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

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>.

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.

The modality block configures agent behavior for a specific modality. The current allowed modality is voice. Use modality voice: to control how the agent sounds — its voice, speaking speed, pronunciation of specialized terms, and how it handles turn-taking on a live call.

1modality voice:
2    voice_id: "UgBBYS2sOqTuMpoF3BR0"
3    outbound_speed: 1.0
4    outbound_style_exaggeration: 0.5

The voice variant supports these variables. All variables are optional except voice_id when configuring a live voice channel.

The additional_configs block groups three sub-configurations that fine-tune turn-taking behavior on a live call.

1modality voice:
2    inbound_filler_words_detection: True
3    inbound_keywords:
4        keywords:
5            - "urgent"
6            - "emergency"
7    voice_id: "UgBBYS2sOqTuMpoF3BR0"
8    outbound_speed: 1.0
9    outbound_style_exaggeration: 0.5
10    pronunciation_dict:
11        - grapheme: "Eliquis"
12          phoneme: "ɛlɪkwɪs"
13          type: "IPA"
14    outbound_filler_sentences:
15        - waiting: ["Let me look into that...", "Give me a moment..."]
16    additional_configs:
17        speak_up_config:
18            speak_up_first_wait_time_ms: 10000
19            speak_up_follow_up_wait_time_ms: 10000
20            speak_up_message: "Are you still there?"
21        endpointing_config:
22            max_wait_time_ms: 1000
23        beepboop_config:
24            max_wait_time_ms: 1000

To branch agent logic based on the customer’s current channel at runtime (as opposed to configuring voice-specific behavior here), use the @system_variables.current_modality system variable.

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.

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.

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.

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 Patterns
• Agent Script Reference
• Configure Models in Agent Script

j

Get Started

Agentforce Examples

Agent Script

Language Characteristics

Agent Script Blocks

Specify Different Models

Flow of Control

Manage Agents

Download Documentation

Examples

Patterns

Reference

Agentforce DX

Agentforce APIs and SDKs

Agentforce Actions

Agentforce Service Errors

Models and Prompts

Headless Agentforce Development