Before You Start

To follow this guide you need an org with Agentforce enabled (Enterprise or higher, plus the Agentforce add-on or a Developer Edition org with agent trials), the Agents permission set assigned to your user, and at least one sample dataset — we’ll use Cases and Accounts.

The goal: build an agent that answers the question “What is the status of my open cases and who owns them?” and drafts a follow-up email if a case has been idle for more than 48 hours.

Step 1: Create the Agent Shell

Navigate to Setup → Agentforce Studio → Agents → New Agent.

Give it a name (Case Status Assistant), a short description, and pick Internal as the channel. Internal agents run inside Salesforce for employees; customer-facing channels require additional review.

Save and leave it inactive for now.

Step 2: Define the Topic

A topic is the set of jobs the agent is allowed to do. Click New Topic and fill it out:

  • Name: Case_Status_Lookup
  • Classification description: “User is asking about the status of their open cases, who owns a case, or wants a follow-up email drafted.”
  • Scope: “Answer questions about case status and draft follow-up emails. Do not modify case records, assign cases, or discuss cases owned by other users unless the user explicitly asks.”

The classification description is what Atlas uses to route a user’s question to this topic. Be specific. A vague description pulls in traffic you don’t want.

Step 3: Build the Actions

Before you can wire the agent, you need the actions it will call. We need two:

Action A: Get Open Cases

Create an Invocable Apex class:

public class GetOpenCasesForUser {
    @InvocableMethod(label='Get My Open Cases' 
                    description='Returns open cases owned by the running user')
    public static List<List<Case>> run(List<Request> requests) {
        List<List<Case>> results = new List<List<Case>>();
        for (Request r : requests) {
            results.add([
                SELECT Id, CaseNumber, Subject, Status, Priority, 
                       LastModifiedDate, Account.Name
                FROM Case
                WHERE OwnerId = :UserInfo.getUserId()
                  AND IsClosed = false
                ORDER BY LastModifiedDate ASC
                LIMIT 25
            ]);
        }
        return results;
    }
    public class Request {}
}

Expose it as an action in Agent Studio → Actions → New Action → From Apex. Name it Get_My_Open_Cases and write a clear description — the agent reads this to decide when to call it.

Action B: Draft Follow-Up Email

Create a prompt template (Setup → Prompt Builder → New Template → Flex) that takes a Case record as input and drafts a polite follow-up email asking the contact for an update. Save it and wrap it as an action.

Step 4: Attach Actions to the Topic

Back in the topic, add both actions. Write instructions that tell the agent when to use each one:

“When the user asks about their cases, first call Get_My_Open_Cases. For each case where LastModifiedDate is more than 48 hours ago, offer to draft a follow-up email using Draft_Followup_Email. Never send the email automatically — always show the draft and ask the user to confirm.”

This instruction block is the most important part of the whole agent. Write it carefully.

Step 5: Test in the Preview Pane

Agent Builder has a built-in preview on the right side. Try realistic prompts:

  • “What’s the status of my cases?”
  • “Any cases I’ve been ignoring?”
  • “Draft a follow-up for the oldest one.”

Watch the plan trace below each response. It shows which actions the agent chose and why. If the plan is wrong, your instructions are wrong — edit them, don’t edit the user’s expectations.

Step 6: Build a Test Set

Before activating, build a test set of 30–50 realistic inputs and expected outcomes. Agent Studio lets you record these and re-run them after every change. This is your safety net when you iterate on instructions later.

Step 7: Activate

Once your test set passes, activate the agent. For internal agents, it appears in the Einstein panel in the utility bar. Users with the agent permission set can start chatting immediately.

Things That Will Trip You Up

Over-broad topics. If your topic classification says “help with cases,” the agent will route almost every question there, including ones it can’t actually handle. Keep scopes tight.

Missing action descriptions. The agent picks actions by reading their descriptions. Vague or missing descriptions mean the agent guesses.

Testing only the happy path. The agent will be asked weird things. Test rude inputs, off-topic inputs, and prompts that try to get it to do things outside its scope.

Ignoring the plan trace. When a response is wrong, read the plan trace before blaming the model. Ninety percent of the time the issue is instructions, not reasoning.

What to Build Next

Once one agent is live, the temptation is to build ten more. Resist. Add more topics to the existing agent first — multi-topic agents share context and are cheaper to operate than many single-topic agents. Only spin up a new agent when the topics genuinely belong to different audiences (internal employees vs. external customers, for example).

Frequently Asked Questions

How much does an agent cost to run?

Agentforce is billed by conversation and by Einstein request credits consumed during reasoning. A simple internal agent handling a few dozen conversations a day is inexpensive. A customer-facing agent handling thousands of conversations is a line item worth watching.

Can I use Flow instead of Apex for actions?

Yes — any Flow marked as “available for Agentforce” shows up as an action. For simple CRUD, Flow is faster to build.

How do I debug a response I don’t like?

Open the conversation in Agent Builder’s debug view. It shows the full reasoning chain: which topic was selected, which actions ran, what arguments were passed, and what came back.

Share