Agentforce Architecture Guide — Summer '26

The first Agentforce project most architects meet arrives disguised as a chatbot request. Someone wants a bot bolted onto an existing flow. That framing is the trap. An agent that reasons about goals and picks its own actions is a different architectural animal from a Flow, and building one as though it were a scripted bot produces something that works in the demo and falls over in production. This guide covers how the pieces actually fit together.

What makes Agentforce different

Traditional Salesforce automation (Flows, Apex triggers, scheduled jobs) follows deterministic logic. Given input A, the automation always produces output B. Every path is explicitly coded or configured.

Agentforce agents are non-deterministic reasoning systems. They interpret natural language input, determine which actions are most appropriate to take to achieve the stated goal, execute those actions, interpret the results, and decide whether to continue or respond. The path from input to output is not fixed. It depends on the LLM’s reasoning at runtime.

That distinction changes how you build and verify. You cannot unit test an agent the way you test a trigger, because the same input can produce a different action sequence on two runs. You cannot enumerate every path the way you would for a decision tree. The uncertainty is inherent to LLM reasoning; the job is to design around it with guardrails and behavioural tests rather than trying to eliminate it.

The architecture components

Agents and Topics

An agent is the top-level AI entity. It has a name, a role description, and a set of Topics. Topics scope the agent’s capability — a Service Agent might have topics for Case Management, Order Status, and Knowledge Search. The agent uses its role description and available topics to determine which topic applies to a given user input.

Actions

Actions are the capabilities an agent can invoke during reasoning. Salesforce provides standard actions — query records, create records, send emails. Custom actions extend this with business-specific logic via Apex or Flow.

// Summer '26: Custom Agent Action in Apex
public class CheckOrderStatusAction {
@InvocableMethod(
label='Check Order Status'
description='Returns the current status and estimated delivery date for a given order number'
)
public static List<OrderStatusResult> checkStatus(
List<OrderStatusRequest> requests
) {
// Query order, call external fulfillment API if needed
// Return structured result the agent uses in its response
}
}

The label and description do real work here. The LLM reads them during reasoning to decide whether this action fits the current step, so a vague description like “handles orders” gets the action skipped or misfired. Write descriptions that state exactly what the action returns and when to use it.

Summer ‘26 architecture updates

Multi-agent orchestration (Beta)

The most architecturally significant Summer ‘26 addition is multi-agent orchestration. A primary agent can delegate specialist tasks to sub-agents, each configured for a specific domain. A Billing Agent handles payment queries. A Technical Agent handles product support. A primary Service Agent routes incoming conversations to the appropriate specialist.

The beta status means implementation details may change. Treat current multi-agent configurations as exploratory rather than production-critical.

Dynamic prompt grounding

Prompt Templates can now reference related records up to 3 levels deep — for example, Contact → Account → Parent Account. This enables richer context in agent responses without requiring custom action code to assemble related record data.

Agent Testing Framework

The Agent Testing Framework allows you to define expected agent behaviour as test cases. Specify a conversation input, the expected topic classification, the expected actions invoked, and the expected response characteristics. The framework evaluates the agent against these expectations automatically.

Architectural principles for Agentforce

Design actions to be atomic and composable. Each action should do one thing well. The agent composes multiple actions to achieve complex goals. An action that does too much reduces the agent’s flexibility.

Make action inputs and outputs explicit. The LLM uses input field labels and descriptions to correctly populate action parameters. Poorly labelled inputs lead to incorrect action invocations.

Use guardrails proactively. Define what the agent should not do as clearly as what it should do. Guardrails are your primary safety mechanism.

Expect and test for edge cases. The non-deterministic nature of LLM reasoning means your agent will encounter inputs you did not anticipate. The Agent Testing Framework helps, but production monitoring is essential.