How to Build Better Agentforce Agents: Best Practices That Actually Work

If your Agentforce agent isn't following instructions the way you wrote them, the problem is almost never the AI; it's the architecture. Vague subagent names, overlapping descriptions, instructions doing too much, and business logic buried in natural language are responsible for the majority of agent failures in the field.

The good news: nearly all of it is fixable. This guide covers the Agentforce agent design patterns that work, with examples you can copy directly.

What Is Agentforce Agent Design (and Why It Keeps Going Wrong)?

Agentforce agent design is the practice of structuring AI agents: their subagents, actions, and instructions, so they route correctly, execute reliably, and stay within defined boundaries.

Most agents fail because three core elements get blurred:

• Reasoning: classifying what the user wants and guiding the conversation end-to-end
• Decision-making: applying business rules to determine what to do (belongs inside Flow or Apex Actions)
• Execution: running the actual task via Actions

When these overlap, the agent gets confused. The habits below are how you keep them cleanly separated.

A. Agentforce Subagents: How to Name, Describe, and Scope Them Correctly

A subagent is a focused worker that owns one job. Three things define a good one: its Name, Classification Description, and Scope. Get all three right and routing largely takes care of itself.

1. Name it like a job title, not a label

The name tells the routing layer what this subagent handles. Vague names are one of the most common causes of routing failure.

Avoid names that overlap with other subagents, even slightly. If two subagents could plausibly claim the same request, routing will misfire.

2. Write a classification description that actually routes

This is where most routing problems start. The classification description tells the agent when to choose this subagent. It needs to cover the full range of requests in natural language, not technical shorthand, and it must be distinct from every other subagent's description.

• Weak: "Handles billing."
• Better: "Handles requests to view an invoice, disputes about incorrect charges, payment method updates, and questions about why a bill changed."

The second version works because it maps to the actual language customers use, covers edge cases, and doesn't compete with adjacent subagents.

3. Set scope with explicit do's and don'ts

Scope prevents a subagent from wandering into work that isn't its job. Always define both what it can do and what it cannot.

• Weak: "Handle order questions only."
• Better: "Your job is only to look up order status, start returns, and explain the return policy. 

You can read order records and create return requests. You cannot issue refunds, change prices, or edit customer account details."

The "cannot" list matters as much as the "can" list.

Full subagent example: Password Reset

B. Agentforce Actions: Naming, Instructions, and Input Design

Actions are the tools an agent calls to get things done. How you name and describe them determines whether the agent reaches for the right one.

1. Use descriptive action names with no abbreviations

Every action name should describe exactly what it does: no guessing, no abbreviations.

2. Write 1–2 line action instructions that cover behavior and edge cases

An action's instruction tells the agent what it does and when to use it. One to two lines is the right length, but make them earn it.

• Weak: "Gets order info." → Better: "Get order details including status, items, and delivery date. Requires a valid order ID. Use when a customer asks where their order is or what they bought."
• Weak: "Updates a phone number." → Better: "Updates the customer's phone number on the account. If no record exists, create one."
• Weak: "Cancels orders." → Better: "Cancels an open order that hasn't shipped yet. Requires an order ID. Use only after the customer confirms they want to cancel."

Key rule: Only mark an input as required if its value is guaranteed to be available before the action runs. If a required input isn't present at runtime, the action won't execute, even if everything else is configured correctly.

3. Define inputs and outputs precisely

• Capture required fields like email or orderId, before calling an action
• Never call an action with incomplete parameters
• Map outputs to variables so later steps can use them

C. Agentforce Instructions: How to Write Them Without Breaking Your Agent

Instructions guide the agent's reasoning. They don't compute, they describe. Understanding that distinction is what separates clean agent design from brittle agent design.

1. Write instructions that guide sequences, not execute logic

Be explicit about order of operations: "First verify identity using the 'Verify Customer' action, then provide account information."

Tie actions to the situations that trigger them: "Use the 'Track Order' action when a customer asks about delivery date or package location."

2. Formatting and consistency rules that matter

• Use consistent terminology throughout, don't alternate between "customer," "user," and "client" for the same entity.
• Pick one list style (- or *) and stick to it across the entire agent.
• Avoid stacking "always" and "never" rules, they conflict, and the agent won't know which wins.
• Keep decision-making inside Actions, not instructions. Business logic written as prose isn't guaranteed to execute the same way every time.

3. Separate classification guidelines from post-classification steps

If a request needs classifying before anything else happens, write that under its own heading: "Classification Guidelines", then handle the steps that follow under a separate section. Splitting them gives the agent clear context about prerequisites.

4. Use a Global/System Instructions subagent

Hold shared rulesL formatting standards, global do's and don'ts, tone guidance, in one place so you're not repeating them inside every subagent.

D. How to Reference Names Inside Agentforce Instructions

When you mention subagents, actions, or variables inside instructions, consistent formatting helps the agent recognize them.

New builder note: In Canvas view, type @ to pull subagents, actions, and variables directly into the script, the quoting convention above is primarily a legacy-builder habit.

Agentforce Configuration Best Practices: What to Enforce at the System Level

A few rules that apply across the entire agent design, not just individual subagents:

• Keep critical logic in Actions, not instructions. Put business logic in Flow or Apex. Natural-language if-else conditions are where behavior gets unpredictable.
• Limit actions per subagent. Stay under roughly 10–15. More than that invites misclassification and slows execution.
• Decide what happens first, then what's next. Classify before acting. Write them as separate sections.
  ‍

Context Variables and Subagent Filters

These two features ensure the agent has the right data and only the right options available to it.

• Context variables carry the supporting data that actions and decisions depend on. They help subagents coordinate and fill in gaps before the agent acts.
• Filters limit what the agent can see, exposing only the relevant subagents and actions for a given situation. Fewer options means less confusion and better routing accuracy.

Context variables in practice

For an agent deployed on both a public signup page and a logged-in Experience Cloud site:

• Public page: Capture email, phone, or membership_id through prompts, then use them for customer lookup and verification
• Experience Cloud (logged in): Auto-populate userId, accountId, or contactId from the session — no need to ask again

Filters in practice

Filters keep restricted actions out of the picture, lower decision complexity, and steer the agent down the right path without relying on instructions to do the work.

G. What Agent Script Changes About Agentforce Development

The new Agentforce Builder introduces Agent Script, and it directly addresses the biggest pain point in agent design: getting agents to follow logic reliably.

What's actually new:

• Deterministic logic now lives in the agent itself. The old safe practice was "keep decision-making in Flow or Apex because agents won't follow logic reliably in instructions." Agent Script changes that it's a human-readable language that supports real conditional logic (if/else, variable comparisons, action sequences) that runs predictably instead of being interpreted by the LLM.

• Subagent transitions can be hard-wired. You can define exactly when the agent hands off from one subagent to another, deterministically.

Three ways to build:

• Chat with Agentforce in plain English and it generates the script.
• Canvas view for readable block-based editing (type / for patterns like if/else, @ to add resources).
• Script view for writing directly in defined syntax.

Better debugging. The new builder adds step-by-step tracing, you can see exactly what the agent did at each moment and how long each part took. A significant upgrade over guessing why a response went sideways.

Key Takeaways

• Design before you write. Separate reasoning, decision-making, and execution and keep them separated throughout.
• Subagents win or lose on names, descriptions, and scope. Clear, specific, and non-overlapping across all three.
• Actions need good names and tight instructions. One to two lines, only the inputs you truly need, under 10–15 per subagent.
• Instructions guide, they don't compute. Use them for sequences and trigger conditions, not business logic.
• For hard logic, use the right tool. Flow or Apex in the legacy builder; Agent Script expressions in the new one.
• Context variables and filters give the agent the right data and keep the wrong options out of reach.
  ‍

Conclusion

If your agent isn't behaving, resist the urge to add more words to the instructions. The fix is almost always structural, a clearer boundary, a deterministic rule, or a value stored in a variable instead of left to chance. Design it like a system, and it will behave like one.

At MIDCAI, our team specializes in a wide range of Agentforce implementations, from subagent architecture and action design to Agent Script, context variable strategy, multi-agent builds, and Experience Cloud deployments. If you're building from scratch or untangling an agent that isn't working, we can help you get it right.

Talk to the MIDCAI team →

‍