Configuring a Custom Action: Instructions and Input and Output Parameters

A custom action in Agentforce is an operational building block. It is not just a way for the agent to generate text, it is a way for the agent to execute a specific task. Choosing the reference action type is only the starting point. To make a custom action reliable and predictable in real conversations, you must configure its instructions, its input behavior, and its output behavior. This is the layer where an agent becomes a governed system that triggers the right work at the right time, collects the right data, and returns results in a controlled way.

Action instructions define what the action does, when it should be used, and how the agent should apply it. Think of action instructions as a contract between the reasoning engine and the action. Good instructions focus on meaning, not technical details. They clarify the business purpose of the action, the situations where it is appropriate, which inputs are required, what outcome is expected, and what the agent should do after the action completes. If instructions are vague, the agent may call the action too often, fail to call it when needed, or make unsafe assumptions about missing data. If instructions are precise, behavior becomes repeatable because the same situation leads to the same decision to run the action.

Strong action configuration also includes best practices that help the agent recognize when the action should be invoked. One of the most effective techniques is to provide a small set of example utterances. These are sample user messages that should trigger the action. Keeping this to a small number of examples is important because the goal is not to cover every possible phrase, but to give clear signals of intent. A good set of utterances represents the typical ways users ask for that specific outcome. For example, an address update action might be triggered by messages like “I need to change my delivery address” or “Please update my shipping address.” These utterances help the reasoning engine match real user intent to the correct operation.

Another best practice is to describe dependent actions and expected behavior around them. Many actions should not run in isolation. They depend on earlier steps such as authentication, order lookup, or confirmation. If you document these dependencies in the action instructions, the agent becomes much less likely to execute a sensitive operation too early. The instructions can guide the agent to gather prerequisites first and only then run the main action, which improves both correctness and safety.

Input configuration controls what the agent must have before the action runs and how missing information is handled. Require Input determines which parameters are mandatory. These are values the action cannot run without because execution would fail or produce the wrong outcome. Require Input turns inputs into strict requirements. If the values exist in variables, the agent can pass them immediately. If they do not exist, the agent must obtain them before proceeding.

Collect Data from user defines whether the agent should ask the user for the missing required input. This is a crucial distinction. Require Input says the value must be present. Collect Data from user says that if it is not present, the agent should request it from the user instead of guessing. This is one of the simplest ways to increase reliability. For example, if the action needs an order number and it is not in context, the agent should ask for it rather than trying to infer it from incomplete text.

Output configuration controls what the action returns and how the agent is allowed to use that output. One important setting is Filter from agent action, which lets you exclude a particular output so the agent will not use it. This is useful when an output is technical, internal, or not meant to affect the conversation or downstream logic. However, there is a key rule to remember. At least one output must remain in use. Otherwise, the action becomes meaningless for the agent because it executes work but produces nothing that the agent can apply as a result.

Another important setting is Show in conversation. This determines whether the action output should be displayed to the user in the chat. Not every output should be shown. Sometimes the best design is to store an output in a variable for later logic, while keeping it invisible to the user. This is especially true for internal identifiers, technical flags, or sensitive values. On the other hand, user-friendly outcomes such as confirmations, next steps, or status summaries are usually appropriate to show. Show in conversation gives you control over the user experience and helps prevent accidental disclosure of internal data.

After configuration, testing is essential. Agent Builder includes a conversation preview that helps you validate behavior using real utterances. This is where you confirm whether the reasoning engine triggers the action at the correct moment, whether the agent correctly asks for missing required inputs, and whether outputs appear as intended. Conversation preview is also the fastest way to detect two common issues: an action that never triggers because examples and instructions are not aligned with real user wording, or an action that triggers too aggressively and interrupts the flow when it should not.

When these elements are configured well, your custom action behaves like a reliable operational component. Instructions define the purpose and usage conditions. Utterances help the agent recognize intent. Require Input and Collect Data from user ensure correct data collection. Output controls determine what is used, what is hidden, and what is shown, with at least one output always remaining active. Conversation preview then confirms the configuration works in real interaction patterns.

Next, we will shift focus to what you can do without custom development. The next topic is which standard actions most commonly appear in an Employee Agent and how they support typical internal enterprise scenarios.