How to build your first Agentforce service agent

The Trailhead quick start makes it look like an afternoon: pick the service agent template, accept the defaults, chat with your new agent in the preview pane. And that part genuinely is an afternoon. The trouble starts when you try to put the agent in front of real customers — you hit a permissions error on a user you never knowingly created, a knowledge index that refuses to finish, and refund questions routing to the wrong topic every third attempt.

None of this is a reason to avoid Agentforce. It’s a reason to build in the right order, because most of the failure modes live in the steps the tutorials compress into a sentence: provisioning, the agent user, and testing. The demo is the easy 20%.

This guide walks the whole path in sequence — prerequisites, agent creation and its user, topics, actions, knowledge grounding, testing, and channel deployment — with the gotchas flagged where we typically see builds stall.

Step 1: Clear the prerequisites — edition, Einstein, and Data Cloud

Before anything appears in Setup, three things have to be true of your org.

The right edition and licensing. Agentforce requires Enterprise edition or above, and usage is metered: as of March 2026, list pricing is $2 per conversation or 20 Flex Credits per action (about $0.10, with credits at $500 per 100,000). Enterprise+ orgs get 100,000 free Flex Credits with Salesforce Foundations — comfortably enough for a pilot. Developer Edition orgs and Trailhead playgrounds work for learning.
Einstein generative AI turned on. In Setup, find Einstein Setup and flip the toggle, then refresh. Every Agentforce feature sits behind this switch, and Salesforce’s setup docs treat it as the first gate: no Einstein, no agents menu.
Agentforce enabled, with Data Cloud provisioned. Next, search Setup for Agentforce Agents and enable Agentforce itself. The retrieval features — data libraries, knowledge grounding — run on Data Cloud, so confirm it’s provisioned in the org before you plan any knowledge work. In orgs where Data Cloud was never set up, this is the step that quietly adds days to the plan.

One more prerequisite that isn’t a toggle: something for the agent to do. If your cases have no consistent categorisation, your knowledge base is three stale articles, and your “process” lives in one agent’s head, fix that first. Our Agentforce readiness check covers the org-level questions worth answering before you spend a single credit.

Step 2: Create the agent, then lock down its user

In Setup, open Agentforce Agents and create a new agent from the Agentforce Service Agent template. The wizard asks for a name, a description, a role, and company context. Take these seriously — they end up in the agent’s system-level context. Then deselect the template’s default topics apart from the one or two you actually intend to ship. A first agent should do one job. “Answer order status questions and create a case when it can’t” is a job. “Handle customer service” is a wish.

Here’s the part the quick starts compress: your agent runs as a real user. The template creates (or asks you to pick) an agent user — historically named something like EinsteinServiceAgent with the Einstein Agent User profile — and every record the agent reads or writes goes through that user’s permissions. Salesforce’s own workshop guidance is blunt about it: the agent “will have access to all of the data and metadata that that user can see,” so start from a minimum-access profile and grant only what the job needs.

In practice that means:

Assign the standard permissions. Salesforce ships permission sets for service agents — the troubleshooting docs reference the AgentforceServiceAgentUserPsg permission set group for the agent’s running user. Assign it before you test anything.
Grant object access explicitly. For a typical case-deflection agent, the Trailhead project has you build a permission set with read access on Contact fields and read/create/edit on Case. Your objects will differ; the principle won’t.
Expect silent failures. This is the number-one first-build gotcha. When the agent user lacks field or object access, the agent doesn’t throw a stack trace at the customer — it apologises and says it can’t help. If your agent seems inexplicably useless in testing, check the agent user’s permissions before you touch a single instruction.

Step 3: Write topics that route — the classification description is logic, not documentation

A topic is a job category: it bundles a classification description, a scope statement, instructions, and a set of actions. When a customer message arrives, the reasoning engine picks a topic — and it makes that choice using only the topic’s name and classification description. Not the scope. Not the instructions. Not the actions attached to it.

That one fact explains most misrouting. Teams write a beautiful classification description-shaped paragraph of marketing copy (“Handles all customer inquiries with care”), then wonder why billing questions land in the FAQ topic. The classification description is routing logic. Write it like logic:

Name topics with verbs. “Provide Order Status” beats “Orders”. The name participates in classification, so make it describe the action, not the noun.
Put example phrasings in the description. Include the ways customers actually ask — “where’s my stuff”, “has it shipped”, “track my package” — not just the canonical form.
Make topics mutually exclusive on paper. If two classification descriptions could plausibly claim the same utterance, the model will split them unpredictably. Merge the topics or sharpen the boundary.

Then there are instructions — the guidance the agent follows after a topic is selected. Be specific and reference actions by name; the workshop pattern is literally “If asked to book, use the action ‘Create Booking’.” Two habits pay off here. First, don’t rely on instruction order: if steps must happen in sequence, put the sequence in a single instruction rather than three separate ones. Second, write instructions for the failure path — what to do when the record isn’t found, when the customer won’t give an order number, when the honest answer is “let me get a human.”

Expect imperfection. In our experience, classification for ambiguous or out-of-scope messages is genuinely non-deterministic — the same odd utterance can land in different topics on different runs. You reduce the variance with sharper descriptions; you don’t eliminate it. That’s an argument for fewer, crisper topics on a first agent, not more.

Step 4: Build actions in Flow, Apex, or prompt templates — the descriptions are the API contract

Actions are what the agent can actually do: look up an order, create a case, draft a reply. You build them from three main sources, and the choice matters less than people think — pick whichever your team can test and maintain:

Action type	Best for	Inputs/outputs defined by	Watch out for
Flow	Record lookups, guided steps, logic admins own	Flow input/output variables	Changing a flow’s variables later typically means reworking the action — design the interface up front
Apex	Callouts, complex logic, anything needing unit tests	`@InvocableVariable` fields	Bulk safety and sharing still apply, and the agent user needs access to the class
Prompt template	Summarising, drafting text, flexible Q&A	Template inputs	Output is generated text — don’t use it where the answer must be exact

Whichever you choose, understand this: the labels and descriptions on your action and its inputs are the real API contract. The agent decides when to call an action and how to fill its parameters by reading those descriptions — Salesforce’s developer guidance says outright that Agentforce uses them to match conversation intent to the right action. A vague description isn’t a cosmetic problem. It’s a broken interface.

Here’s what that looks like in an Apex invocable action, with descriptions written for the model rather than for a human skimming code:

public with sharing class GetOrderStatus {
    public class Input {
        @InvocableVariable(
            label='Order Number'
            description='The customer-facing order number, like ORD-10442. Ask the customer for it if they have not provided one. Never guess it.'
            required=true)
        public String orderNumber;
    }

    public class Output {
        @InvocableVariable(
            label='Order Status Summary'
            description='A short, customer-safe summary of the order status. Relay it without adding details.')
        public String statusSummary;
    }

    @InvocableMethod(
        label='Get Order Status'
        description='Looks up one order by order number and returns its current status. Use whenever a customer asks where an order is or whether it shipped.')
    public static List<Output> getOrderStatus(List<Input> inputs) {
        // Agent invocations arrive one at a time, but stay bulk-safe anyway.
        Set<String> orderNumbers = new Set<String>();
        for (Input i : inputs) {
            orderNumbers.add(i.orderNumber);
        }
        Map<String, Order> byNumber = new Map<String, Order>();
        for (Order o : [SELECT OrderNumber, Status FROM Order
                        WHERE OrderNumber IN :orderNumbers]) {
            byNumber.put(o.OrderNumber, o);
        }
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            Order o = byNumber.get(i.orderNumber);
            Output out = new Output();
            out.statusSummary = (o == null)
                ? 'No order found for number ' + i.orderNumber + '.'
                : 'Order ' + o.OrderNumber + ' is currently: ' + o.Status + '.';
            results.add(out);
        }
        return results;
    }
}

Notice the input description tells the agent how to obtain the value (“ask the customer”), not just what it is — and the not-found path returns a usable sentence instead of throwing. Per the InvocableMethod contract, the method takes one list-typed input and returns a list. When you register the action in Agent Builder, you also choose which inputs the agent must collect from the user and which outputs display directly in the conversation. Review those toggles deliberately; the defaults aren’t always what you want customers to see.

Step 5: Ground the agent in knowledge — and wait for the index

A service agent that can’t answer “how do I return this?” from your actual policy isn’t deflecting anything. Grounding comes through an Agentforce Data Library — either uploaded files or your Salesforce Knowledge base — paired with the Answer Questions with Knowledge action.

The setup is short. The failure modes aren’t, and this is where “why doesn’t it answer?” tickets come from. The official troubleshooting guidance is worth reading in full before you build; the highlights:

The index must say Ready. Behind a data library sits a Data Cloud search index (named KA_ plus your library name for Knowledge). Until its status is Ready, the knowledge action returns nothing — the agent just shrugs. Indexing takes time after setup and after content changes. Check the Search Index tab before concluding your agent is broken.
If you only see the file-upload option, Salesforce Knowledge isn’t enabled in the org. Enable it (and Lightning Knowledge) first.
The agent user needs retrieval permissions too. Data space access in Data Cloud, read access plus field-level security on every Knowledge field the library indexes, and the Allow View Knowledge permission. Data category visibility applies to the agent user like anyone else. Miss any of these and retrieval silently returns nothing.
Mind the file limits. As of this writing, uploads cap at 4 MB for text and HTML files and 100 MB for PDFs, and PDFs with embedded rich content can fail to index.

And the unglamorous truth: retrieval quality tracks content quality. Ten current, well-structured articles beat two hundred stale ones. If your knowledge base needs a cleanup, do it before go-live — the agent will surface your worst article to a customer eventually.

Step 6: Test in the Testing Center, then deploy to a real channel

The conversation preview in Agent Builder is a smoke test, not a test plan. It’s single-threaded, it’s you typing polite questions you already know the answer to, and it proves almost nothing about production behaviour.

Batch testing before humans arrive

The Agentforce Testing Center runs batch tests: you upload test cases as CSV or let it generate cases from your topics and actions, and each case pairs an utterance with the expected topic, expected actions, and expected response. Run it in a sandbox — test conversations execute real actions, and real actions modify real records.

Three honest caveats from the field. Batch results vary between runs, because topic classification isn’t deterministic — run suites more than once and look at trends, not single passes. Scoring leans on semantic similarity, so a confidently wrong answer can pass; spot-check transcripts for factual accuracy yourself. And batch cases are single-turn as of early 2026, so multi-turn flows — identity verification before an action, say — still need manual adversarial testing. Test like a frustrated customer: missing information, out-of-scope requests, attempts to talk the agent past its guardrails.

Wiring up Messaging for In-App and Web

Deployment is Service Cloud plumbing, and the official workshop walks it end to end. The sequence: turn on Messaging in Setup, create a routing configuration and a queue (this queue is your human fallback — build it even if humans are “phase two”), then create a Messaging for In-App and Web channel with routing type Agentforce Service Agent and your queue as fallback. Finally, create an Embedded Service Deployment pointed at the same domain as the channel, publish it, and drop the snippet or the Embedded Messaging component onto your site. Two small gotchas: the domain must match between channel and deployment, and published changes can take several minutes to propagate — don’t debug a deployment you published ninety seconds ago.

Go-live guardrails

Before the toggle flips: keep irreversible or high-value actions (refunds above a threshold, cancellations) out of scope or behind human approval, confirm escalation hands the full transcript to the queue, and leave enhanced event logs on so you can audit what the agent actually did. Then read the transcripts daily for the first weeks. We’ve written up what separates production agents from demos — the short version is that launch is the start of the tuning loop, not the end of the project.

The distance between a badge and a production agent

Look back at the sequence and a pattern emerges: almost none of the hard parts are AI. Provisioning is licensing and org hygiene. The agent user is access control. Topic descriptions are interface design. Action descriptions are API contracts. The knowledge index is data plumbing. Testing is testing. Trailhead teaches the builder mechanics in a few hours — and it’s genuinely good at that — but the mechanics were never the risk. The risk is the same set of platform disciplines that decide whether any Salesforce feature survives contact with production.

That’s actually encouraging. It means your existing skills transfer: the admin who writes clean permission sets, the developer who documents invocable actions properly, the architect who insists on a sandbox test plan — they’re the ones who ship working agents. It also means the timeline is knowable. Budget the afternoon for the build, then budget real days for permissions, grounding, and testing, and you’ll come in roughly on schedule instead of mysteriously three weeks late.

Build the narrow agent first. Get one topic routing reliably, one set of actions behaving, one knowledge library indexed and answering. Everything after that — more topics, more channels, voice — is iteration on a foundation you understand, rather than a bigger version of a demo you don’t. That’s the difference between having an agent and running one, and it’s well within reach of a competent Salesforce team. If you’d rather not learn every gotcha first-hand, our Agentforce practice exists because we already did.

Understanding the basics

What do you need before you can build an Agentforce service agent?

Three things: a Salesforce org on Enterprise edition or above with Agentforce licensing (Developer Edition works for learning), Einstein generative AI enabled in Setup, and Data Cloud provisioned if you want knowledge grounding through data libraries. You’ll also need Salesforce Knowledge enabled to ground the agent in articles, plus a Messaging-capable channel for deployment.

How does an Agentforce agent choose which topic to use?

The reasoning engine matches the customer’s message against each topic’s name and classification description — and nothing else. Scope, instructions, and attached actions play no part in routing. That’s why vague or overlapping classification descriptions cause misrouting: two topics that could both plausibly claim an utterance get chosen unpredictably. Verb-led topic names and descriptions containing real example phrasings are the fix.

Can you test an Agentforce agent before customers see it?

Yes, in two layers. The conversation preview in Agent Builder gives quick manual checks while you build. The Agentforce Testing Center then runs batch tests — uploaded via CSV or AI-generated — comparing each utterance’s actual topic, actions, and response against expectations. Run batch tests in a sandbox, since test conversations execute real actions against real records, and repeat runs to account for non-deterministic classification.

Standing up your first service agent and want it to survive contact with real customers? Talk to us — we’ve already made the mistakes so you don’t have to.

How to build your first Agentforce service agent (and what Trailhead glosses over)