In one sentence: an agent action is an autolaunched Flow with a description written for a model to read. The Flow is the easy half. What decides whether the action ever gets used is the text around it: the action description, the input labels, and the instruction in the topic that points at it. A perfectly good Flow the agent never chooses is the most common first result.
Choose something small
A first action should do one thing, with one or two inputs and a small result. “List the open cases on an account” works. “Handle the customer’s request” is not an action, it is a project.
The shape to aim for: inputs the agent can plausibly obtain from the conversation or from the record already in context, a query or an update in the middle, and an output short enough to read aloud in a sentence or two.
Build the Flow
Create an autolaunched Flow. Every variable the agent supplies is marked available for input. Every variable you want back is marked available for output. Keep both lists short. Each input is something the agent has to work out, and every extra one is another chance for it to guess wrong.
Two decisions matter more than the rest.
- Running context. An autolaunched Flow can run in system context and ignore sharing entirely. Decide that deliberately and write down why.
- Failure behaviour. Add fault paths. A Flow that throws gives the agent an unhelpful failure, which it will often paper over with an apology or, worse, a plausible guess.
Return text the model can use rather than a raw record collection. A short formatted string travels better than a set of sObjects the agent has to interpret:
Open cases for Northwind Ltd: 3
00012345 High Login fails after password reset
00012389 Medium Invoice PDF missing from portal
00012401 Low Question about SSO rollout
The description is the real interface
When you add the Flow as an agent action you write a description for the action and for each input and output. That text is what the planner reads when it decides what to call. Treat it as the contract, because it is.
Say when to use the action and when not to. “Returns open cases for a single account. Use when the user asks about current support issues for a named account. Do not use for closed cases, and do not use for contacts.” The negative half earns its place as soon as you have two similar actions.
Input descriptions should state the expected format. “Salesforce Account record Id, 15 or 18 characters” stops the agent passing an account name into an Id field, which it will otherwise cheerfully attempt.
Testing it
Test the Flow on its own first, in debug, with a real Id. If it fails there, nothing downstream is worth investigating.
Then test in the conversation preview. Watch the plan, not only the reply. The preview shows which topic was selected, which action was called and what values were passed, and most first-action failures are visible there at a glance: wrong topic, no action chosen, or the right action called with a mangled input.
Three phrasings, minimum. Ask for the same thing the way a support rep would, the way a manager would, and the way somebody who has never used the system would. If only one of the three routes correctly, the description is too narrow.
What usually goes wrong first
- The action is never chosen. Nearly always a description problem, or the action sits under a topic whose scope does not cover the question.
- The input arrives wrong. A name where an Id was expected. Fix the input description, and consider accepting a name and resolving it inside the Flow.
- The answer is invented. The Flow returned nothing usable and the model filled the gap. Return an explicit “no records found” string instead of an empty variable.
- It works for you and nobody else. Permissions. The agent, the action’s running identity and the data each have separate access, and yours is almost certainly wider.
Frequently asked
Flow or Apex for a first action? Flow, unless you need callouts, awkward logic or precise error handling. Apex gives more control over what the agent receives back, which matters later rather than first.
How many inputs is too many? Three is comfortable. Past that the agent guesses more often, and each guess is a way for the call to be wrong without anyone noticing.
Can one action call another? Not directly. The agent chains actions itself based on its instructions, and chaining is considerably less reliable than one action that does the whole job.
Does a clean preview mean it works? No. The preview runs as you, in your session. Test with a user holding the permissions the real audience will have, and check the current documentation for what the preview does and does not simulate.
