Agent Script Reference: Actions

An action defines a task that a topic can perform, such as calling a Flow, a prompt template, or an Apex class. You can store the action's output in a variable, make the output available to the reasoning engine, and choose whether the LLM can display the output to customers.

A topic can have many actions. You can import an action from a library or define it directly in the topic. Topics don't share actions - each action is unique to a topic. If you import an action to a topic, the topic gets its own copy of the imported action.

You define a topic's actions in the actions block.

You can call the action explicitly from the logic section of a topic's reasoning block. In this case, the action is run every time the topic is run, as the agent parses the topic.

You can also call the action from the topic's after_reasoning block In this case, the action is run after the topic exits, every time the topic is run.

You can also expose the defined action to the LLM in the topic's reasoning.actions block, which is where tools are specified. In this case, Agentforce passes the tool with your specified inputs to the LLM after parsing the entire topic. The LLM can subjectively choose to run the tool based on the current context. If the tool is run, it's run when the LLM receives the resolved prompt, not when the agent parses the topic.

To provide more explicit instructions to the LLM, you can optionally reference the tool from the prompt. In this example, we explicitly reference the send_verification_code_tool tool:

In this example, we define a single action, send_verification_code_action. We explicitly call the action from the logic section of the reasoning instructions. We also expose the action as a tool to the LLM (send_verification_code_tool), so that the LLM can choose to call the action if the customer didn't get the verification code the first time.

So you can call actions (specified in topic.actions) deterministically, and you can expose actions as tools (specified in topic.reasoning.actions) that the LLM can choose to use based on the current context.

In the Actions and Tools example, the action is defined as send_verification_code_action and exposed as a tool called send_verification_code_tool. If you create actions in the UI and expose them as tools, the action and the tool have the same name.

See Using Actions, Tools (Reasoning Actions), and Reasoning Instructions.

An action definition contains these properties.

Property	Description
action name	Required string. The action's name.
description	Optional string. Description of the action's behavior and purpose. The LLM uses this description to help it decide when to call the action.
inputs	Optional object. Defines the action's input parameters, if any.
include_in_progress_indicator	Optional boolean (`True`/`False`). Indicates whether the agent shows progress indicator when running the action.
target	Required string. Reference to an executable (apex, flow, or prompt).
label	Optional string. The action's name to display to the customer. Auto-generated if not specified. By default, Agentforce creates the label from the action's name, where `my_action` becomes "My Action".
outputs	Optional object. Defines the action's output parameters, if any.
require_user_confirmation	Optional boolean. Indicates whether the customer must confirm before the agent runs the action.

The action's identifier, which you use to run the action. Action names must follow Salesforce developer name standards:

Begin with a letter, not an underscore.
Contain only alphanumeric characters and underscores.
Can't end with underscore.
Can't contain consecutive underscores (__).
Maximum length of 80 characters.
snake_case is recommended.

Defines the action's input parameters, their type, and whether the input is required. For example:

You can use these types for input and output parameters:

string - text values
number - numeric values (floating point)
integer - integer values
long - long integer values
boolean - True/False values
object - complex objects
date - date values (YYYY-MM-DD)
datetime - dateTime values
time - time values
currency - currency values
id - Salesforce ID values
list[<type>] - a list of values of the same type. You can use any supported type in this list. For example, list[string] or list[number].

A reference to an executable. Use the format {TARGET_TYPE}://{DEVELOPER_NAME}. An action can have these targets:

apex (Apex)
flow (Flow)
prompt (Prompt Template)

For example:

Defines the action's output parameters and the parameters' properties. By default, the agent remembers the action's output information for the entire session. The agent can make choices based on the information, and use the information to answer customer questions. For example, if a get_product_care action returns information about how to maintain a product, the agent remembers that information for the entire session, and can use the information to answer questions.

Output parameters can be of these types.

To hide output information from the agent, set the output parameter's filter_from_agent property to True.

Supported properties for output parameters are:

Property	Description
`description`	Optional. String. Description of the output parameter. By default, Agentforce generates this property from the parameter name. For example, the parameter `error_code` becomes `Error Code`.
`developer_name`	Required. String. Value that can override the parameter's developer name.
`label`	Optional. String. Human-readable label for the output parameter's value. By default, Agentforce autogenerates the label from the output parameter's name. For example, `error_code` becomes `Error Code`.
`complex_data_type_name`	Required if the parameter is a complex data type. String. Indicates the type returned by the target. For example, suppose that an action has a flow target and an output parameter called `customer_info`. If the flow returns information of type `lightning__recordInfoType`, the action's `customer_info` parameter must have the type `object` and the property `complex_data_type_name: lightning__recordInfoType`.
`filter_from_agent`	Optional. Boolean. 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`.

For example:

Once you've defined an action in the topic's reasoning.actions block, you can call the action in a topic's reasoning logic, or expose it as a tool to the LLM.

To ensure that an action runs every time a topic runs, use run @actions.<action_name> in the topic's reasoning block. In this example, an action checks business hours. The action doesn't require input, and we store the action's output in variables. These variables can be accessed by other topics, or by this topic next time it runs.

You can expose an action as a tool in the reasoning actions block, enabling the LLM to choose whether to run the tool. When you expose the tool to the LLM, you can choose whether to explicitly reference the tool from any prompts you specify in the reasoning block. See Tools (Reasoning Actions).

Typically, an LLM recognizes when to use a tool. However, you can also use {!@actions.<action_name>} in the prompt to provide more context.