Most teams ship their first custom Agent Action in a single afternoon. The work is split between defining the action (instructions, inputs, outputs) and writing the underlying flow or Apex. Get the action working in the Plan Trace before you wire it into a topic and let real users hit it.
- Decide the action type
Pick Apex if you need loops, callouts, or sObject orchestration. Pick Flow if an admin can build the logic. Pick Prompt Template if the action's job is generating text against grounded data. Standard and Data Library Search are usually obvious by the use case.
- Build the underlying flow or Apex method first
For Apex, write a public class with one @InvocableMethod and matching InvocableVariable inputs and outputs. For Flow, build an autolaunched flow with input and output variables marked Available for Input and Output.
- Create the Agent Action record
Setup, Agent Actions, New Agent Action. Pick the type. Pick the reference (Apex class, Flow API name, prompt template, etc.). Salesforce reads the input and output signatures from the underlying artifact.
- Write the action instruction and parameter descriptions
The action instruction tells the reasoning engine when to use this action. Write it in the second person, name the user phrases the action should match, and call out negative cases. Each parameter gets its own description for value extraction.
- Attach the action to a topic
Open Agent Builder, open the agent, open the topic. Click Add Action and pick your action from the org library. The action is now considered for any message that the topic classifier sends to it.
- Test in the Conversation Preview and read the Plan Trace
Send messages that should and should not trigger the action. The Plan Trace shows the decision path. Refine the instruction or parameter descriptions until the action fires when it should and stays silent when it should not.
- Save the test cases to Agentforce Testing Center
Capture both the positive and negative test messages as a saved test set. Testing Center re-runs the set on every agent change and flags regressions before deploy.
Apex, Flow, Prompt Template, Standard, or Data Library Search. Drives what underlying artifact the action wraps.
The specific Apex class, Flow, prompt template, or Data Library the action invokes. Required and immutable after creation.
Natural-language description the reasoning engine uses to decide when to invoke this action. The most important configuration field on the record.
Per-parameter natural-language descriptions used for value extraction from the conversation and for downstream actions to consume the output.
Toggles the action on or off across all topics it is attached to. Useful for emergency rollback without unwiring topics.
- The action instruction is the only thing the reasoning engine uses to pick actions. Vague instructions ("use this for orders") match too much and trigger the wrong action.
- Apex actions need the @InvocableMethod annotation and matching InvocableVariable inputs. A regular @AuraEnabled method will not surface as an Agent Action.
- Changing an Apex method's signature breaks the bound Agent Action. The action keeps the old schema until you re-bind, and runtime calls fail with a parameter mismatch.
- Flow actions run with the running user's context. A flow that updates fields the agent's user cannot edit fails silently from the agent's point of view.
- Custom actions attached inline inside Agent Builder are scoped to that agent. Create org-level actions in the Agent Action library if you want reuse.