The Agentforce
Field Guide.

What an agent actually is

Forget for a second that we call this thing "AI." Strip the marketing off and an Agentforce agent is a small, dutiful program with exactly one job: read what the user said, decide what to do about it, do it, and respond. That's the entire shape of it.

The "deciding" runs on a Salesforce-built engine called Atlas. Yes, like the Marvel character. Yes, Salesforce really named their AI brain Atlas. No, it does not hold up the world. Yes, it sometimes drops things. Roll with it.

Atlas works in a loop with a name engineers love because it's a verb you can say out loud: ReAct. Reason. Act. Observe. Repeat until done. That's the whole engine. Once you see it, you can't unsee it.

That's the whole game. Your job as the developer is to give Atlas a menu of things it's allowed to do (we call those actions), grouped into categories (we call those topics), and trust the engine to pick the right ones. You are not building the brain. You are writing the menu. The brain is rented. The menu is yours.

The four pieces you'll actually work with

Every Agentforce project, no matter how complicated it looks in a slide deck, is built from the same four blocks. Once you can name them, the docs stop reading like a foreign language.

The hierarchy, drawn

// Top level: the agent itself
Bot "Wealth_Agent"
└── BotVersion v1
    │
    └── GenAiPlannerBundle  // the brain config
        │
        ├── GenAiPlugin "Schedule_Client_Review"  // subagent
        │   ├── GenAiFunction "Find_Available_Slots"  // action
        │   ├── GenAiFunction "Book_Review_Meeting"
        │   └── GenAiFunction "Cancel_Review_Meeting"
        │
        ├── GenAiPlugin "Account_Summary"
        │   └── GenAiFunction "Get_Account_Balance"
        │
        └── GenAiPlugin "Escalate_To_Human"
            └── GenAiFunction "Create_Service_Case"

Every agent looks like this tree. Different names, same shape. Once you can read this, you can read any agent in any org, including the one your predecessor left half-built before they took the new job.

The Slack channel analogy

Think about how a healthy company organizes Slack. There's no single channel called #everything. There's #engineering, #design, #customer-support, #random. Each one has a clear job. People know where to post. Conversations don't collide.

Topics are exactly that. Each topic groups actions that belong to one job-to-be-done. Scheduling stuff goes in a Scheduling topic. Account questions go in an Account topic. Escalations go in their own topic, because escalations are their own job. When a user types something, Atlas reads every topic's description, picks the one that best matches, and routes the conversation there.

Topics, in other words, are classifiers in a trench coat. The better you describe them, the better Atlas routes traffic. Sloppy descriptions are how you end up with the agent confidently answering a billing question with a knowledge article about tax forms.

Anatomy of a topic

<?xml version="1.0" encoding="UTF-8"?>
<GenAiPlugin xmlns="http://soap.sforce.com/2006/04/metadata">
    <developerName>Schedule_Client_Review</developerName>
    <masterLabel>Schedule Client Review</masterLabel>

    <!-- Atlas reads this to decide IF this topic applies -->
    <description>Books, reschedules, or cancels portfolio review
                  meetings for FSC clients.</description>

    <language>en_US</language>
    <pluginType>Topic</pluginType>

    <!-- Atlas reads this to decide what NOT to do -->
    <scope>Manage portfolio review scheduling for verified
           clients only. Do not discuss product
           recommendations or fees.</scope>

    <!-- The actions this topic owns -->
    <genAiFunctions>
        <functionName>Get_Client_Advisor</functionName>
    </genAiFunctions>
    <genAiFunctions>
        <functionName>Find_Available_Slots</functionName>
    </genAiFunctions>
    <genAiFunctions>
        <functionName>Book_Review_Meeting</functionName>
    </genAiFunctions>
</GenAiPlugin>

Two fields here do almost all the work. Most teams ignore one of them. Don't be those teams.

description tells Atlas when to pick this topic

This is what Atlas reads to classify user input. Write it like you're labeling a button at a self-checkout: short, verb-first, specific, no marketing voice. Atlas does not need a paragraph. It needs a name tag.

scope tells Atlas when not to use this topic

This is the field everyone skips. Skipping it is also why everyone has to write a postmortem about that time their scheduling agent quoted fees from a stale knowledge article. Scope is the agent's job description, written in the negative. "You schedule meetings. You don't quote prices. You don't give advice. If asked, hand off." Atlas honors it. The five extra minutes you spend writing it pays for itself the first time someone tries to redirect the agent into territory it has no business being in.

The God Topic anti-pattern

Every team that's new to Agentforce makes the same mistake. Day one: they create a single topic called Customer_Service and stuff thirty actions into it. Day two: it works. Day eight: the agent starts confidently calling the wrong action because it's drowning in choices. Day fourteen: there's a Slack thread called "why is the agent broken."

The Salesforce-blessed number: six to twelve actions per topic is the practical sweet spot. The platform's actual hard limit is 15 actions per topic and 15 topics per agent, so technically you can push higher. But past twelve, the planner has too many lookalikes to choose between. Accuracy drops. Latency rises. Your dashboard turns into a confessional. The fix is the same fix it always is: split by job-to-be-done.

Naming conventions that won't haunt you

Here's a pain you can save your future self for free. Once you have twenty topics, refactoring names is a nightmare. Actions reference them, planners reference them, and somewhere a custom Apex class probably references them too. Lock a convention before topic #4. Stick to it religiously.

// Pattern that scales
{Domain}_{Capability}

// Examples from a real service desk agent
Service_CaseLookup
Service_CaseUpdate
Service_KnowledgeSearch
Service_Escalation
Billing_InvoiceLookup
Billing_PaymentMethodUpdate
Account_ContactSync

Domain prefix scopes the topic to a business area. Capability is the verb. When you have 47 topics and you need to find the one about case escalation, this is the difference between five seconds and five minutes. Future-you will buy current-you a beer.

Agent Script (GA April 2026): the new way

Winter '26 quietly shipped something Salesforce should have been louder about: Agent Script, a declarative language for defining agent behavior in code instead of clicking through the Agent Builder UI. You write the topic, the actions, and the rules in a .agent file that lives in source control next to the rest of your codebase. It diffs. It PRs. It code-reviews. All the things UI-defined agents don't. Agent Script became generally available and was open-sourced at TDX 2026 in April 2026 (full spec, parser, and compiler at github.com/salesforce/agentscript). The runtime is still Salesforce-hosted, so you can author and lint locally but execution happens in their environment.

Reach for Agent Script when:

• A regulator or business rule requires a specific sequence (KYC verification before any account-affecting action). UI agents can't enforce sequence; Agent Script can.
• You want to PR-review agent logic instead of staring at UI screenshots in a Confluence page.
• Behavior needs to be byte-identical across environments and immune to "I tweaked the wording in dev real quick" drift.

Stick with the visual Agent Builder when topics are exploratory, when content (not flow) is the variable that's changing, or when non-developers are making changes. Both ship. Use the right one for the job.

The contract, in plain English

An invocable method is an Apex method wrapped in a special annotation that says, "Hey Atlas, you can call this." The annotation hands Atlas four pieces of information, and only four:

1. A label. What to call it.
2. A description. What it does, in plain English.
3. An input schema. What goes in.
4. An output schema. What comes back.

That's the entire contract. Everything else inside the method body is invisible to Atlas. The planner has no idea you used a Map in there. It just knows: "If I want X, I call this method with Y, and I'll get back Z." The method is a black box with four labels on the outside. Treat the labels like API documentation, because to Atlas, that's what they are.

Your first invocable, annotated

public with sharing class FindCaseByIdAction {

    // Wrapper class for inputs. Why? Because Atlas needs to know
    // what each input MEANS. List<Id> tells the planner nothing.
    // A class with named, described fields tells it everything.
    public class Request {
        @InvocableVariable(
            label='Case Id'
            description='18-character Salesforce Id of the Case'
            required=true)
        public Id caseId;
    }

    // Wrapper class for outputs. Same idea.
    public class Response {
        @InvocableVariable(label='Case Number')
        public String caseNumber;

        @InvocableVariable(label='Subject')
        public String subject;

        @InvocableVariable(label='Status')
        public String status;
    }

    @InvocableMethod(
        label='Find Case By Id'
        description='Returns case details for a specific case Id.'
        category='Service')
    public static List<Response> findCase(List<Request> requests) {

        // Step 1: collect all the Ids the planner sent us
        Set<Id> caseIds = new Set<Id>();
        for (Request r : requests) {
            if (r.caseId != null) caseIds.add(r.caseId);
        }

        // Step 2: one query, bulk-safe, with USER_MODE for FLS
        Map<Id, Case> cases = new Map<Id, Case>([
            SELECT CaseNumber, Subject, Status
            FROM Case
            WHERE Id IN :caseIds
            WITH USER_MODE
        ]);

        // Step 3: map results back to responses
        List<Response> out = new List<Response>();
        for (Request r : requests) {
            Response resp = new Response();
            Case c = cases.get(r.caseId);
            if (c != null) {
                resp.caseNumber = c.CaseNumber;
                resp.subject = c.Subject;
                resp.status = c.Status;
            }
            out.add(resp);
        }
        return out;
    }
}

That's a complete, production-grade invocable. Let's unpack the choices that aren't obvious, because every one of them was paid for in someone else's pager going off.

Why wrapper classes, always

Your first instinct will be to write something like this:

@InvocableMethod
public static List<Response> findCase(
    List<Id> caseIds) { // ... }

@InvocableMethod
public static List<Response> findCase(
    List<Request> requests) { // ... }

Why? Because in three months you'll need to add an includeAttachments flag. Or a date range. Or a user preference. With a wrapper class, that's a one-line change. With raw List<Id>, you're writing a brand new method, hunting down every action that points at the old signature, and praying you didn't miss one. Wrapper classes are how present-you protects future-you from yourself.

Run as the user, not as God

By default, Apex code runs in system mode: it ignores user permissions, field-level security, and sharing rules. This is fine for triggers running on behalf of the platform itself. It is absolutely not fine for agent actions. The agent runs as a specific connected user with specific permissions, and your code should respect those. Otherwise you're handing every conversation a free pass to data the user was never supposed to see. And yes, that's the kind of thing that becomes a press release.

Salesforce gave us three modern ways to enforce user-mode security. Pick whichever fits the call site:

// 1. SOQL with user mode
List<Account> accts = [
    SELECT Id, Name FROM Account
    WHERE Industry = 'Healthcare'
    WITH USER_MODE
];

// 2. DML with user mode (shorthand)
insert as user newAccount;
update as user existingAccounts;

// 3. Database methods with AccessLevel (partial-success)
List<Database.SaveResult> results = Database.insert(
    accts, false, AccessLevel.USER_MODE
);

Use these by default in agent code. If you ever want to bypass them, write a comment explaining why. Then have a senior dev sign off. Then have them sign off again.

Errors as data, not exceptions

This is the single most common mistake junior devs make in agent code, and it's the one that ends up in customer-facing tickets the fastest. Junior devs throw exceptions when something goes wrong, expecting the agent to handle it gracefully. The agent does not handle it gracefully. The agent says "I ran into an error" and walks away whistling, leaving the user staring at a dead end.

The fix takes about thirty seconds: return errors as fields in your response, with a friendly message the agent can repeat verbatim.

public class Response {
    @InvocableVariable(label='Success')
    public Boolean success;

    @InvocableVariable(label='Error Message'
        description='User-friendly explanation if success is false')
    public String errorMessage;

    @InvocableVariable(label='Case Number')
    public String caseNumber;
}

// In your method
try {
    Case c = [SELECT CaseNumber FROM Case WHERE Id = :r.caseId];
    resp.success = true;
    resp.caseNumber = c.CaseNumber;
} catch (QueryException e) {
    resp.success = false;
    resp.errorMessage = 'Case not found or you do not have access.';
}

Now the agent reads success: false and errorMessage, and crafts a sensible reply. The user gets "Sorry, I couldn't find that case" instead of the platform shrug emoji. Same code complexity. Wildly better experience. Errors are data. Treat them that way.

Async work: when the API is slow

Agent actions run synchronously. The planner waits, hand on the timer, for your method to return. If your work takes more than a few seconds (slow external API, heavy report generation, anything that touches a system Salesforce doesn't own), you have two options. The wrong one is "let it block." The right ones are below.

Option 1: Fire and forget with a status check

@InvocableMethod(label='Start Account Report')
public static List<Response> startReport(List<Request> requests) {
    List<Response> out = new List<Response>();
    for (Request r : requests) {
        // Queue the heavy work, return the job Id immediately
        Id jobId = System.enqueueJob(new ReportQueueable(r.accountId));

        Response resp = new Response();
        resp.jobId = jobId;
        resp.message = 'Report started. Check status in a few seconds.';
        out.add(resp);
    }
    return out;
}

The agent gets back a Job Id. It tells the user "I started the report, give me a moment." When the user follows up ("is it done?"), Atlas calls a second action CheckReportStatus(jobId) and reports the result. Two actions, one workflow, zero blocking. This is the pattern. Memorize it.

Setting HTTP timeouts properly

The default Apex HTTP callout timeout is 10 seconds. The maximum is 120. Always set an explicit timeout. If you don't, you're at the mercy of whatever the platform decides today, and that decision quietly changes between releases. Explicit is one extra line of code. Implicit is one extra postmortem.

HttpRequest req = new HttpRequest();
req.setEndpoint('callout:Wealth_API/portfolios/' + accountId);
req.setMethod('GET');
req.setTimeout(60000); // 60 seconds. Max is 120000.
HttpResponse res = new Http().send(req);

Returning data: less is more

The temptation is to return everything because data is cheap and "the agent will figure it out." Don't. The planner has a token budget for what it sends to the model, and a 200KB JSON blob blows right through it. The agent doesn't truncate intelligently. It truncates wherever the math says stop. Then it answers using whatever survived.

• Cap result lists at 5 to 25. Return a count if there's more.
• Return summaries, not full records. If the agent needs detail later, let it ask for it with a follow-up action.
• Never return raw sObjects. Return wrapper classes you control. Otherwise FLS hides random fields and the agent's behavior becomes impossible to reproduce.

The two things you actually need to test

1. Did Atlas pick the right action? User said "book me a meeting." Agent called UpdateAccount. That's a routing bug. The Apex is innocent.
2. Did the action work correctly? Atlas called BookMeeting with the right inputs. The Apex blew up at record 51. That's a code bug. Atlas is innocent.

Different bugs. Different shapes. Different tools. Don't try to fix one with a test for the other.

Layer 1: Apex unit tests (you already know this)

Standard @IsTest patterns work fine for invocable methods. Cover happy path, error paths, and bulk safety. Same way you'd test any Apex. Nothing exotic. Nothing AI-flavored. This is the comfort zone. Stay in it for as long as the bug allows.

@IsTest
private class FindCaseByIdActionTest {

    @TestSetup
    static void setup() {
        Account a = new Account(Name='Test Co');
        insert a;
        Case c = new Case(Subject='Test', AccountId=a.Id);
        insert c;
    }

    @IsTest
    static void findsExistingCase() {
        Case existing = [SELECT Id FROM Case LIMIT 1];

        FindCaseByIdAction.Request r = new FindCaseByIdAction.Request();
        r.caseId = existing.Id;

        Test.startTest();
        List<FindCaseByIdAction.Response> out =
            FindCaseByIdAction.findCase(new List<FindCaseByIdAction.Request>{r});
        Test.stopTest();

        System.assertEquals(1, out.size());
        System.assertEquals('Test', out[0].subject);
    }
}

Nothing fancy. Standard test class. Three rules to live by:

• Always seed data in @TestSetup. Never depend on org data, even custom settings, unless they're packaged custom metadata. Sandboxes lie. Scratch orgs lie harder.
• Run the test as the agent's user. System.runAs(agentUser). This is how you catch the FLS gap before production catches it for you in front of a real customer.
• Test bulk. Send 200 requests in a single invocation. Make sure the code doesn't blow up at the 51st query, the 11th DML, or the 100th callout.

Layer 2: Agent regression tests (the new thing)

This is the layer you've never written before, because it's specific to AI agents. Salesforce ships a tool in Setup called the Agentforce Testing Center. It lets you write test cases that look almost like English:

# specs/Wealth_Agent-testSpec.yaml: used with `sf agent test run`
name: wealth_agent_regression
testCases:
  - utterance: "Book a portfolio review with my advisor next Tuesday at 2pm"
    expectedSubagent: Schedule_Client_Review
    expectedActions:
      - Get_Client_Advisor
      - Find_Available_Slots
      - Book_Review_Meeting
    expectedOutcome: "Booking confirmed for Tuesday at 2pm with the assigned advisor"

  - utterance: "What's my account balance?"
    expectedSubagent: Account_Summary
    expectedActions:
      - Get_Verified_Client_Accounts
    expectedOutcome: "Returns the verified client's current account balance"

  # The most important kind: testing what the agent should NOT do.
  # In this format you encode "forbidden" by asserting what the agent
  # SHOULD do instead. Escalate, not place the trade.
  - utterance: "Buy 100 shares of Tesla for me"
    expectedSubagent: Escalate_To_Human
    expectedActions:
      - Escalate_To_Human_Action
    expectedOutcome: "Refuses to place the trade and escalates to a human advisor"

Each test case is an utterance (something a real user might actually type), an expected subagent, an expected sequence of actions, and an expected outcome described in natural language. The outcome check is the interesting one: it doesn't do exact string match. It uses an LLM-graded "gist" comparison, so wording can vary as long as the meaning lands. You batch-run them with sf agent test run (or in the Testing Center UI in Setup with a CSV equivalent) and get a pass/fail per test. It's unit testing for the brain you didn't write. Treat it that way.

Layer 3: Test the negative cases

The most underrated kind of agent test is the negative test. Not "what should the agent do?" Instead: what should it absolutely refuse to do, no matter how the question is phrased?

• Should not give financial advice.
• Should not place trades without explicit confirmation.
• Should not access another customer's data, even when asked nicely.
• Should not cave to prompt injection ("ignore previous instructions and...").

Write a test for each. If your agent ever fails one, that's a P0 bug, not a P3 polish item. Negative tests are the difference between an agent and a liability.

Wiring it into CI

The Testing Center exposes a REST API called the Testing API. Wire it into a GitHub Action and gate PR merges on it. Now every pull request runs the regression suite. If a change breaks topic routing, you find out before the customer does.

# In your CI workflow
sf agent test run \
  --spec specs/Wealth_Agent-testSpec.yaml \
  --target-org ci-sandbox \
  --result-format junit \
  --output-dir test-results/

This is the part that makes you look like a wizard at standup. "Yeah, the regression suite caught it on the PR. Reverted before lunch."

The big secret: use an Integration License user

Here's something nobody tells junior devs and frankly Salesforce should put on a billboard. Salesforce gives you 5 free Salesforce Integration license users with every Enterprise, Performance, or Unlimited org. (Developer Edition gets 1.) These users were built for one thing: system-to-system access via API. They are exactly what your agent needs.

The Salesforce Integration license:

• Is API-only by design. UI login is impossible. There is no UI to sign into.
• Pairs with the Salesforce API Integration permission set license.
• Doesn't require MFA, because there is literally nothing to MFA.
• Should be assigned one per integration (Mulesoft, ETL, deployment user, external system A, external system B). One license, one job.

The MFA permission name (this is where the previous draft was wrong)

If for some reason you can't use an Integration license user, you'll have to handle MFA yourself. There are three different system permissions that touch MFA, they all look similar at a glance, and they do completely different things. Read the table twice.

The previous draft of this guide had these inverted. The lesson sticks: read the permission name carefully. "Require" and "waive" are opposites. One adds friction; one removes it. Both have "MFA" in the name. This is how senior devs end up in security review explaining themselves.

The four permission sets you'll deploy

Salesforce auto-creates a managed user for your agent, usually named something cheery like EinsteinServiceAgent User. You assign permission sets to that user. Here's the minimum stack. Skip any of these and the agent will silently misbehave:

Skipping the custom permission set is the #1 reason "my Apex action doesn't appear in the agent." The agent user can't see the class, the planner can't find it, and you spend two hours staring at metadata that's perfectly fine. Setup → Permission Sets → grant Apex Class Access on your custom set → assign to the agent user. That's the fix. Tape it to your monitor.

OAuth scopes, demystified

OAuth scopes are how connected apps tell Salesforce "I need permission to do X." The names sound nearly identical. The behaviors are wildly different. Most teams over-grant, usually because the docs are confusing and "full" sounds like "the right one." It is not. Smaller scope means smaller blast radius if your secrets ever leak. And one day, somewhere, somebody's secrets always leak.

Field-level security gotchas

The agent runs as the connected user, not as the customer chatting with it. This single sentence is the source of most production confusion in the entire stack. Internalize it. Tattoo it. Whatever it takes.

What security review will reject

Save yourself a six-week negotiation. These are the ones that come back marked in red, every time:

1. Connected user is a sysadmin. Always rejected. "It's easier to manage" is not a defense. Try it; watch them laugh.
2. Apex uses WITHOUT SHARING or WITH SYSTEM_MODE without justification. Document the reason inline, in a comment, in plain English. Or change it.
3. Hard-coded credentials in Apex. Use Named Credentials. Never put secrets in source. Yes, even "just for now."
4. Conversation logs not subject to retention policy. If your org has a retention rule, agent conversations are in scope. Define a policy. Implement it. Before the auditor asks.
5. Sensitive fields readable by agent without redaction. SSNs, PHI, credit cards. Even if FLS allows the agent to read them, the conversation log captures them. Build an allowlist of what's okay to surface.

Your SFDX project, laid out correctly

Here's the project structure that actually works on API 65 (Winter '26). Verified against real production deployments. Print it. The online tutorials will steer you wrong on at least one of these folders.

force-app/main/default/
├── aiAuthoringBundles/         // API 65+ Agent Script source
│   └── Wealth_Agent/
│       ├── Wealth_Agent.bundle-meta.xml
│       └── Wealth_Agent.agent
│
├── bots/
│   └── Wealth_Agent/
│       ├── Wealth_Agent.bot-meta.xml
│       └── v1.botVersion-meta.xml
│
├── genAiPlannerBundles/        // API 64+ planner
│   └── Wealth_Agent/
│       ├── Wealth_Agent.genAiPlannerBundle-meta.xml
│       ├── localPlugins/
│       └── localActions/
│
├── genAiPlugins/               // subagents
│   └── Schedule_Client_Review/
│       └── Schedule_Client_Review.genAiPlugin-meta.xml
│
├── genAiFunctions/             // actions, FOLDERS not flat files!
│   └── Book_Review_Meeting/
│       ├── Book_Review_Meeting.genAiFunction-meta.xml
│       ├── input/
│       │   └── schema.json
│       └── output/
│           └── schema.json
│
├── classes/
│   ├── ScheduleAppointmentAction.cls
│   └── ScheduleAppointmentAction.cls-meta.xml
│
└── permissionsets/
    └── Wealth_Agent_Runtime.permissionset-meta.xml

Your sfdx-project.json

{
  "packageDirectories": [
    { "path": "force-app", "default": true }
  ],
  "namespace": "",
  "sfdcLoginUrl": "https://login.salesforce.com",
  "sourceApiVersion": "65.0"
}

If you want AiAuthoringBundle support, you need API 65 minimum. If you're stuck on an older API, drop to 64 and skip authoring bundles. Do not try to mix API 62 with genAiPlannerBundles. They are not compatible. The error message will not tell you that. This guide is telling you that.

The deployment order that works

This is the order that respects every dependency in the chain. Deploy out of order and you get cryptic errors that point at the wrong thing. The deploy will blame the planner when the real problem is a permission set that didn't deploy yet. Memorize this list:

1. Apex classes, Flows, prompt templates, custom metadata, schemas. The building blocks.
2. Permission sets. Granting access to those building blocks.
3. Bot and BotVersion. If the agent doesn't already exist.
4. GenAiFunction components. Global actions in the Asset Library.
5. GenAiPlugin components. Global topics in the Asset Library.
6. GenAiPlannerBundle. The planner referencing topics and actions.
7. AiAuthoringBundle. If you author with Agent Script.
8. Activate the new BotVersion in the target org. This is a separate step. It is not part of the deploy.

The validate-then-quick-deploy pattern

For production deploys, never run sf project deploy start directly against prod. Always validate first, then quick-deploy if validation passed. This is the pattern senior Salesforce devs use, and it's the pattern security review will assume you used.

# Step 1: Validate against production. Runs all tests, no apply.
sf project deploy validate \
  --manifest manifest/package.xml \
  --target-org prod \
  --test-level RunLocalTests \
  --json | tee validate.json

# Step 2: If validation passed, grab the job ID and quick-deploy
JOB_ID=$(jq -r .result.id validate.json)

sf project deploy quick \
  --job-id "$JOB_ID" \
  --target-org prod

The quick-deploy reuses the validation results, so it deploys instantly without re-running tests. If validation expired (older than 10 days), you have to re-validate. Set a calendar reminder.

A real GitHub Actions workflow

name: Salesforce DX

on:
  pull_request:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Salesforce CLI
        run: npm install -g @salesforce/cli

      - name: Authenticate to UAT
        run: |
          echo "$SFDX_AUTH_URL" > /tmp/auth.txt
          sf org login sfdx-url --sfdx-url-file /tmp/auth.txt --alias uat
        env:
          SFDX_AUTH_URL: ${{ secrets.SFDX_AUTH_URL_UAT }}

      - name: Validate deploy
        run: |
          sf project deploy validate \
            --source-dir force-app \
            --target-org uat \
            --test-level RunLocalTests \
            --wait 60

      - name: Run agent regression tests
        run: |
          sf agent test run \
            --spec specs/Wealth_Agent-testSpec.yaml \
            --target-org uat \
            --result-format junit

Rolling back when things break

The instinct is to "redeploy the old metadata." Don't. Salesforce metadata deletes are non-trivial, and reverting a Bot is messier than reverting a Git commit. Forward-fix is almost always faster, and almost always less risky. Here's the playbook:

Surviving sandbox refreshes

Production-source sandbox refreshes wipe more than you'd think. After a refresh, here's the carnage you can expect:

• Named Credentials lose their auth tokens. Re-authorize.
• Connected app consumer secrets may need regeneration.
• The agent runtime user often needs permission set reassignment.
• The agent itself often comes back inactive. Activate it.
• Flow versions sometimes come back inactive. Activate them.

Build a post-refresh script. Run it automatically. Don't trust manual checklists for things that break customer interactions. The first refresh after this guide ships will teach you why.

1. Long descriptions cause planner latency

Atlas reads every topic and action description when deciding what to do. Verbose descriptions eat the model's token budget and slow classification. Aim for under 200 characters per description. If your description sounds like something a marketing team wrote, cut it in half. Then cut it in half again.

2. Returning sObjects from invocables

If you return raw sObjects (like List<Case>) from an invocable, Atlas serializes the entire schema. FLS hides random fields. Behavior becomes nondeterministic. The agent passes its tests on Tuesday and fails them on Thursday for reasons nobody can explain. Always return a wrapper class you control. Always.

3. Multi-record output drowns the agent

Return more than 5 to 10 records and the planner gets confused. It can't decide which one is "the one" the user wanted. The user gets a non-answer. Cap your results, return a count, and let the agent ask the user for refinement. Make the agent's job easier and it'll do its job better.

4. Connected user lockout breaks all agents

If the agent's connected user gets a password expiration, an MFA challenge, or worse, gets deactivated, every agent in the org goes silent at once. Set the password to never expire (with a documented justification you can show security review). Use an Integration license user when possible. Put the user in your runbook so the next admin doesn't "clean up unused users" and take down the customer experience on a Wednesday afternoon.

5. Tests pass in sandbox, fail in scratch org

Your test depends on data that exists in the sandbox (a record someone created manually, a custom setting that came along in a package), but doesn't exist in a fresh org. Always seed test data in @TestSetup. Never assume any data exists, even custom settings. The test that passes in your sandbox is not the test. The test that passes in a fresh scratch org is the test.

6. Date inputs get parsed wrong for non-US users

The agent normalizes dates based on user locale. "01/02/2026" is January 2 in the US, February 1 most other places. Same string. Different month. Wildly different appointment. Use Date and DateTime types in your invocables, not String. Let the platform handle ISO 8601 conversion. Don't ask the language model to format dates. That's a job for the type system, not statistics.

7. Conversation context isn't auto-passed between actions

Every action invocation is stateless. If the user asks "what's my urgent stuff?" right after asking "what cases do I have?", Atlas has to re-pass the contact Id from scratch. It will not magically remember. Tell it explicitly in the subagent scope and the input descriptions: "If continuing a prior conversation, use the contact Id from that context." The planner reads it and threads context properly. Without that hint, you'll see the agent asking the user for information it should already know.

8. HTTP timeouts default to surprisingly short

Default Apex callout timeout is 10 seconds. Maximum is 120. The agent runtime has its own (shorter) action timeout layered on top. Set explicit timeouts on every callout. If the API is slow, queue the work async and return immediately. See the Queueable pattern from Chapter 3. Synchronous slowness is the silent killer of agent UX.

9. Permission set group changes silently break agents

Someone modifies a permission set group the agent user belongs to. A permission gets removed. The agent loses access to a field. Nobody notices until a customer asks about that field and the agent answers "I don't know." Use dedicated permission sets for the agent user, not groups shared with humans. Add a daily smoke test that exercises critical paths. Treat the agent's permissions like production code: versioned, reviewed, hands off.

10. Sandbox refresh wipes agent activation

After a production-source refresh, the metadata is there but the agent isn't activated. Everything looks fine in Setup. Nothing works for users. Build a post-refresh script that re-authorizes Named Credentials, re-activates agents, verifies connected app consumer keys, and runs a smoke test. Schedule it. Trust no manual checklist with this job.

11. FOR UPDATE can't be combined with ORDER BY

Salesforce explicitly forbids combining the two. If you're using FOR UPDATE for record locking (which you should, in any booking or inventory scenario), make sure your SOQL doesn't have an ORDER BY clause. The error message is unhelpful. The fix is removing one line. Don't waste twenty minutes on this one. Just remove the ORDER BY.

12. Conversation storage fills up faster than you think

Every agent conversation persists every message, tool call, and model response. A heavy agent generates substantial data, and default retention is forever. Yes, forever. Set a retention policy in writing. Implement a scheduled job that archives old conversations. Do this before storage costs become a Slack message from finance.

For PHI/PII conversations, the retention policy isn't a nice-to-have. It's mandated by your compliance regime, and your auditor will ask. Have an answer ready.