SfSkills Domains Docs GitHub

Home / agentforce / agent-actions

agent-actions

Designing or reviewing Agentforce actions: Flow actions, Apex invocable actions, prompt-template actions, action naming, input and output contracts, confirmation requirements, and safe error behavior.

Open the skill folder on GitHub

Agent Actions

Use this skill when the agent already knows the right subagent, but still needs a safe and understandable way to do work. Agent actions are the operational boundary between conversational intent and real system side effects. Poor action design leads to vague capabilities, hard-to-recover failures, and agents invoking the wrong tool because names or contracts are ambiguous.

The design goal is simple: a small, well-named action set with stable inputs, predictable outputs, and deliberate confirmation for side effects. Salesforce guidance emphasizes keeping action counts low, using clear names and descriptions, and shaping input types so the agent can select and execute actions reliably. Action design should help the agent understand what the tool does, what data it needs, and when failure should be surfaced to the user versus returned as a structured business result.

Agent actions can be Flow-based, Apex invocable, or prompt-template oriented depending on the task. Flow actions are strong when declarative orchestration is enough. Apex invocable actions are better when service-layer control, strict contracts, or heavier logic matter. Prompt-template actions fit generation tasks, not destructive record mutation. The boundary should be chosen intentionally.

Terminology. Subagent is the April 2026 rename of topic. Nothing about behaviour changed, and metadata types, API names, and the "topic selector" pattern name still say topic.

Before Starting

Check for salesforce-context.md in the project root. If present, read it first.

Gather if not available:

Questions to Ask Before Configuring

Ask these before building or reviewing an action. Each one traces to a gotcha in references/gotchas.md.

QuestionWhy it mattersWhat a good answer addsWhat proper configuration adds over just doing it
"Does this action read, or does it change or send something?"Writes need "Require user confirmation", which adds a turn and an LLM call (Gotcha 3)A read or write label per action and the confirmation decisionA brake on every side effect, and no confirmation noise on reads
"Which business rule must hold every single time?"Rules in instructions are followed most of the time, not always (Gotcha 7)The list of rules to enforce inside the Apex class or flowThe rule holds even when the model misreads an instruction
"Which values must the user supply, and which can the agent find?""Require input" and "Collect data from user" decide what the agent asks for (Gotcha 8)Per-input settings and an instruction for each inputFewer wrong guesses and fewer unnecessary questions
"Which subagent owns this job, and how many actions does it already have?"Unassigned actions never fire, and more than 15 per topic degrades performance (Gotchas 5, 6)The owning subagent and its action countReliable selection instead of a crowded tool belt
"Which user does the action run as, and what can that user reach?"The agent user determines what the agent can access (Gotcha 10)The agent user and the objects, fields and classes it needsLeast-privilege access that matches the action's write scope
"What should the agent say on failure?"Raw exceptions are weak contracts, and outputs drive the reply (Gotchas 4, 9)Error codes, user-safe messages and planner-visible outputsRecoverable failures the agent can explain

Core Concepts

Actions Are Capabilities, Not Conversation Dumps

An action should do one business job clearly. Do not create vague actions like runProcess or handleRequest that hide several outcomes. The LLM selects actions based on semantic clarity of names + descriptions; "do the thing" descriptions produce "do something random" behavior.

Rule of thumb: if you can't explain what the action does to a business user in one sentence, the action is too broad. Split it.

Naming And Description Drive Tool Selection

The agent relies on action labels, descriptions, and parameter meaning to choose correctly. Human-readable clarity is part of the runtime contract.

Naming pattern (recommended):

Description pattern:

Stable Input And Output Shapes Improve Reliability

The agent needs narrow, predictable parameters and results. Avoid overloading one action with many loosely related required fields or generic object blobs.

Input design rules:

Output design rules:

Confirmation And Error Behavior Need Deliberate Design

Destructive or customer-visible side effects should be confirmation-aware. Failures should return clear business meaning rather than raw stack traces or empty silence.

Confirmation patterns:

Error patterns:

Common Patterns

Pattern 1: Flow Action For Declarative Orchestration

When to use: The task can be modeled as clear declarative steps and the admin team should retain ownership.

Structure: Use a narrow Flow boundary (auto-launched flow with explicit input/output variables). Keep inputs explicit and typed. Ensure the output is meaningful enough for the agent to continue or explain a failure. Fault connectors on every element.

Why not the alternative: Apex adds complexity when the task is mainly orchestration; admins can maintain the flow without code skills.

Pattern 2: Apex Invocable Service Action

When to use: The action needs reusable service logic, stricter contracts, or finer transaction control.

Structure:

public class CreateCaseForAccount {
    @InvocableMethod(label='Create Case for Account'
        description='Creates a support case attached to a specific Account and returns the Case ID. Use when customer reports an issue; do NOT use for feature requests (those go to a different action).')
    public static List<Result> createCase(List<Request> requests) {
        // ... bulk-safe implementation
    }

    public class Request {
        @InvocableVariable(required=true label='Account ID' description='Salesforce ID of the parent Account')
        public String accountId;
        @InvocableVariable(required=true label='Subject' description='Short description of the issue, plain English')
        public String subject;
        @InvocableVariable(label='Priority' description='Low, Medium, High; defaults to Medium if omitted')
        public String priority;
    }

    public class Result {
        @InvocableVariable public Boolean success;
        @InvocableVariable public String caseId;
        @InvocableVariable public String errorCode;
        @InvocableVariable public String message;
    }
}

The @InvocableVariable descriptions ARE the LLM's documentation. Write them well.

Pattern 3: Confirmation-Gated Mutation Action

When to use: The action creates, updates, deletes, or externally sends something significant.

Structure:

  1. Turn on "Require user confirmation" on the agent action (isConfirmationRequired = true in the GenAiFunction). See references/metadata-examples.md.
  2. The action's description explicitly states "requires user confirmation before execution".
  3. Agent prompt guidance reinforces: "for any action that sends contracts, cancels orders, or updates financial fields, require explicit user confirmation".
  4. On user decline, action is never invoked; agent explains to user what was NOT done.

Pattern 4: Prompt-Template Action For Content Generation

When to use: The action's job is to generate text/content from record context (e.g. draft email, summarize case, explain quote).

Structure: Register a Prompt Template (via Prompt Builder) as an agent action. The prompt template defines inputs (record references) and the model generates the output. DO NOT use prompt-template actions for mutation — they're generation-only.

Pattern 5: Read-Only Lookup Action

When to use: Agent needs to retrieve information before deciding next steps.

Structure: Thin invocable method that executes a specific SOQL query. Read-only; no side effects. Fast (sub-second). Returns a structured result the agent can reason over.

Read-only actions should be plentiful; mutation actions should be scarce. The asymmetry is deliberate — agents should READ freely and WRITE only with deliberation.

Decision Guidance

SituationRecommended ApproachReason
Declarative orchestration is sufficientFlow action (Pattern 1)Lower implementation overhead
Service logic or tighter contract control neededApex invocable action (Pattern 2)Better structure and reuse
Task is primarily content generationPrompt-template action (Pattern 4)Generation boundary is clearer
Action mutates records or triggers external side effectsConfirmation-gated (Pattern 3)Safer execution
Action name and schema feel genericRedesign before releaseAgent selection quality depends on clarity
Agent needs to retrieve info before decidingRead-only Apex lookup (Pattern 5)Fast, safe, composable
Action's work exceeds one transactionPlatform Event publish → async processingDon't block the conversation on long work

Review Checklist

  1. Inventory and classify. List each capability the subagent needs and mark it read or write, with its owner and expected invocation rate. Writes get the confirmation decision now.
  2. Pick the reference action. Flow for declarative orchestration, Apex invocable for strict contracts or service logic, prompt template for generation only. Put every must-always-hold rule inside the reference action.
  3. Write the action instructions. One to three sentences on what it does, when to use it and what it does not do; an instruction per input and output; then set Require input, Collect data from user, Show in conversation and Require user confirmation. references/metadata-examples.md shows the metadata form.
  4. Assign and lint. Add the action to its subagent (15 or fewer actions per topic), then run python3 scripts/check_agent_actions.py --manifest-dir force-app/main/default and the contract linter in agentforce/agentforce-tool-use-patterns.
  5. Test in preview, then in evals. Use the utterances you expect to trigger the action, confirm the read-back and the decline path for writes, and add the cases to the eval harness (agentforce/agentforce-eval-harness).

Salesforce-Specific Gotchas

  1. A technically valid invocable action can still be a poor agent action — generic names and overloaded schemas hurt tool selection.
  2. Prompt-template actions are not the right tool for transactional mutation — generation and side effects should not be blurred.
  3. Too many actions reduce action selection quality: a larger tool belt is not always a better one. The documented guidance is no more than 15 actions per topic (subagent); the earlier "20 per agent" figure was a local heuristic.
  4. Raw exceptions are weak agent outputs — business-safe result structures help the agent explain failure and recover.
  5. Apex invocable actions run under governor limits: CPU, SOQL and DML limits apply to the action's transaction. UNVERIFIED (2026-10-03): the earlier claim that all actions in a session share one governor budget; no source read describes how action transactions are scoped within a session.
  6. @InvocableVariable(label=...) is what the agent sees, not the Apex variable name — use clear labels.
  7. Flow-backed actions can be deactivated out from under the agent — deploy gates should include "agent-referenced Flow activation" verification.
  8. Managed-package invocable actions may have opaque contracts — the agent can call them but may not understand the outputs; wrap in a clarifying Apex invocable.
  9. Actions in customer-facing agents run as the agent user, not as the customer: the customer's own identity is not enforced unless the action checks it. Explicitly audit actions reachable by unauthenticated visitors. UNVERIFIED (2026-10-03): the earlier wording that Guest contexts "bypass" security; the documented model is that the agent user determines access.
  10. Running-user context is the agent's assigned User record: not the end customer interacting with the agent. Sharing implications differ from typical UI flows. The Generative AI guide states that the agent user determines what the agent can access and do.

Proactive Triggers

Surface these WITHOUT being asked:

Output Artifacts

ArtifactDescription
Action design reviewFindings on naming, schema, confirmation, failure behavior
Action boundary recommendationFlow vs Apex vs prompt-template guidance
Contract patternSuggested request and response shape for agent-safe execution
Confirmation policyWhich actions require confirmation + the UX pattern
Action inventoryList of actions per agent with purpose + owner + invocation rate

Package files