Agentforce Architecture — Salesforcepedia

Agentforce Concepts

📘 Architecture Patterns & Reference

Hybrid reasoning, blueprint hierarchy, the deterministic sandwich pattern, RAG strategy, and best practices. Some sections differ between models — use the switcher to show the version relevant to you.

Showing: Classic Model — configure everything in the Agentforce Builder UI, no code files required.

🧠 Hybrid Reasoning 📄 Authoring 🏗️ Blueprint 🥪 Sandwich 📦 State 🔀 Routing ⚙️ Execution Flow 📚 RAG 🏆 Best Practices 🗺️ Overview

🧠

Hybrid Reasoning Model

Agentforce blends probabilistic LLM flexibility with deterministic rule-based control

🎲 Probabilistic Reasoning LLM / Flexibility

What: Uses Large Language Models for natural language and intent
Where: Within Instructions and initial language comprehension
When: For Behavior — tone, conversation flow, unpredictable inputs
Adapts to varied user inputs naturally
Generates fluid, contextual responses
Routes requests to appropriate subagents

🔒 Deterministic Execution Rules / Control

What: Hard-coded, predictable, rules-based software logic
Where: Within Agentforce Script and Actions
When: For Control — mandatory sequences, calculations, DB updates
Enforces sensitive business rules
Handles complex calculations reliably
Manages explicit state transitions

💡 The Core Mental Model

LLM = Behavior. Code = Control. Every design decision in Agentforce comes back to this. If the outcome must be predictable and traceable — use code. If the input is open-ended and human — use the LLM. This distinction drives every design decision in Agentforce.

📄

Authoring in Builder

Configure everything visually in the Agentforce Builder UI — no code files required

⚠️ Two Valid Models — Know the Difference

Classic Model Original / Widely Available

→ Configure everything in Agentforce Builder UI
→ Instructions: free-text field, natural language only
→ Actions: Flows, Apex, Prompt Templates — separate configs
→ Sandwich is a design pattern, enforced via Flows
→ No code in the agent definition itself

Agent Script Newer / Evolving

→ Single text file per subagent (editable in Builder or VS Code)
→ Instructions: | pipe lines — same concept, now in code
→ Actions, variables, logic all in one place
→ Sandwich is enforced in code via before_reasoning: / after_reasoning:
→ Requires Agent Script-enabled org / Agentforce DX

💡 Both models express the same architectural patterns. What matters is your reasoning — why deterministic here, why LLM there — not whether you use before_reasoning: or a Flow. Master the pattern, then the syntax follows.

Authoring in Builder UI

In the Classic Model, you configure everything through the Agentforce Builder visual interface — no code files, no syntax to learn.

Agent Profile — name, persona, channels, system prompt
Subagents — classification description, scope, 1–3 instructions in a text field
Actions — each configured separately: Flow, Apex, or Prompt Template
Instructions field — plain English, 1–3 guidelines per subagent

How Instructions Work

In the Classic Model, instructions are plain text written in the Builder UI. The LLM reads them as behavioral guidelines.

Written as natural language — "Always invoke X before Y"
Use "always" / "never" sparingly — they carry heavy weight
Reference Action API names exactly for correct matching
Keep to 1–3 per subagent — more creates noise and confusion
Cannot enforce execution order — use Flows for mandatory sequences

The LLM reads instructions as context — it interprets them probabilistically. For deterministic enforcement, the logic must live in a Flow or Apex action.

What is Agent Script?

Agent Script is the unified file format that powers each subagent. It replaces separate Flows, Instructions text, and configuration screens with a single readable file that combines:

Configuration — subagent name, description, variables
Business logic — deterministic rules with -> (arrow operator)
LLM instructions — natural language prompts with | (pipe operator)
Actions — defined tools the agent can invoke

Three Ways to Author Agent Script

Chat with Agentforce — describe your agent in plain English; Agentforce Builder generates the script automatically
Canvas View — visual block editor in Builder; use / to add expressions and @ to reference resources
Script View — direct code editor with syntax highlighting (recommended for production)

Also available: Agentforce DX — VS Code extension with full Agent Script language support for local development.

Key Syntax — The Two Operators

Agent Script has exactly two special operators that control whether a line is deterministic or sent to the LLM:

Operator	Meaning	Example
`->`	Start a logic + prompt block — deterministic code before the LLM gets context. Think of it as "here's what to do with code first."	`-> run @actions.validate_identity`
`\|`	A natural language prompt line — passed directly to the LLM. These are instructions to the AI, not code.	`\| Ask the customer to confirm the charge amount and date before proceeding.`

Shorter instructions = more reliable. The LLM reads everything; less noise means better decisions.

Minimal Script Skeleton

subagent: name: Report_Fraud description: | Handles unrecognized charges and fraud disputes. variables: customer_id: mutable string = "" identity_verified: mutable boolean = False subagent.actions: - action: validate_identity target: flow://Validate_Customer_Identity_Flow subagent.reasoning: instructions: -> if @variables.identity_verified == False run @actions.validate_identity set @variables.identity_verified = @outputs.verified end | Ask the customer to describe the suspicious charge. | Confirm the exact amount and date before opening a dispute.

🏗️

Agent Blueprint / Architecture

Hierarchical structure of concepts nested within Agentforce Builder

🤖

A. Agent Profile Top Level

The overarching entity. Defines the agent's identity, persona, channels, and which Subagents it contains.

🏢

B. Subagents Formerly "Topics"

Specialized departments with distinct expertise. The Reasoning Engine reads each subagent's Classification Description to route the user's message to the right one.

💬

C. Instructions Plain text in Builder UI

1–3 natural-language guidelines written in the Builder UI. The LLM reads them as behavioral guidance — tone, action selection, what to do/avoid. Probabilistic, not enforced as code.

⚡

D. Actions Configured separately

Each Action is configured individually in the Builder. The LLM reads the action's name and description to decide when to invoke it.

🔄

Flow Actions Deterministic

Invoke a Salesforce Flow. Use for mandatory sequences, data writes, identity checks — logic that must be deterministic.

🔧

Apex Actions Deterministic

Invoke an Apex class method. Use for complex calculations, integrations, or business rules that need full programmatic control.

✏️

Prompt Template Actions LLM-enhanced

Use an Einstein Prompt Template to generate structured AI output — summaries, drafts, classifications — grounded in Salesforce data.

🔌

MuleSoft / API Actions

Connect to external systems via MuleSoft integrations or REST APIs configured as Named Credentials.

📚

E. Data & Context RAG

Data Libraries (ADL) + Retrievers for Retrieval Augmented Generation — grounds the LLM in your org's knowledge.

🗄️

Agentforce Data Libraries (ADL)

Indexes structured data (Cases, Knowledge Articles) and unstructured data (PDFs, HTML) for vector search.

🔍

Retrievers

Bridge between the search index and the prompt — injects relevant chunks into the LLM's context at inference time.

🤖

A. Agent Profile Top Level

The overarching entity. Defines the agent's identity, persona, channels, and which Subagents it contains.

🏢

B. Subagents Formerly "Topics"

Specialized departments with distinct expertise. The Reasoning Engine reads each subagent's Classification Description to route the user's message to the right one.

📄

C. Agentforce Script One file per subagent

A single text file that combines configuration, variables, deterministic logic (->), LLM instructions (|), and action definitions. Replaces the separate screens in Classic.

⚡

D. Actions Two blocks in the script

Actions are declared inside the script file. There are two distinct blocks depending on who decides when to call them.

🔒

subagent.actions Deterministic

Called explicitly in logic blocks with run @actions.x. You control exactly when they fire. Use for mandatory steps: auth, data writes, logging.

🧠

subagent.reasoning.actions LLM Tools

Exposed to the LLM as available tools. The LLM reads each action's description and decides when to invoke it. Use for optional lookups, search, retrieval.

🔀

Action Targets

Each action points to a target: flow://Flow_API_Name, apex://ClassName.methodName, prompt://Template_Name, or MuleSoft/external API endpoints.

📚

E. Data & Context RAG

Data Libraries (ADL) + Retrievers for Retrieval Augmented Generation — grounds the LLM in your org's knowledge.

🗄️

Agentforce Data Libraries (ADL)

Indexes structured data (Cases, Knowledge Articles) and unstructured data (PDFs, HTML) for vector search.

🔍

Retrievers

Bridge between the search index and the prompt — injects relevant chunks into the LLM's context at inference time.

🥪

Deterministic Sandwich Pattern

Code handles the beginning and end — AI handles the middle

🔒 START — Flow invoked as first Action

A Flow runs deterministically before the LLM responds. Use for: identity verification, data lookups, mandatory pre-conditions, loading context from Salesforce records.

↓ Flow outputs available as context ↓

🧠 MIDDLE — Instructions field (plain text)

The LLM conversation loop. Driven by 1–3 natural-language Instructions in the Builder UI. Handles: tone, intent detection, action selection, collecting user input.

↓ instructions tell LLM what to invoke ↓

🔒 END — Flow invoked as final Action

A closing Flow handles: writes to Salesforce, audit logs, handoffs to humans, session cleanup. Must be referenced in Instructions — the LLM is told to invoke it.

How to Enforce the Sandwich in Classic

Layer	Mechanism	How enforced
🔒 START	Flow Action	Instruction: "Always invoke Validate_Customer_Identity as the first action before responding to any request."
🧠 MIDDLE	Instructions (text)	1–3 natural-language guidelines in the Builder UI. LLM interprets probabilistically.
🔒 END	Flow Action	Instruction: "After completing the request, always invoke Log_Case_Event before ending the conversation."

The key difference from Agent Script: the END layer is not code — it relies on the LLM following your instruction. For truly mandatory logic, always use a Flow.

💡 Study Tip

When asked to design an agent, always call out the sandwich explicitly: "I'd put identity verification and mandatory data lookups in a deterministic Flow before the LLM sees any context, and all writes and audit logs in a closing Flow invoked at the END layer." That language signals you understand the hybrid model regardless of which implementation you're using.

⚠️ Classic Model Limitation

In the Classic Model the sandwich is a design pattern, not a technical guarantee. The END layer depends on Instructions correctly telling the LLM which Action to invoke and in what order. If instructions are ambiguous, the LLM may skip a step. Mandatory sequences belong in Flows — not in plain-text instructions.

🔒 START — `before_reasoning:` block

Runs before the LLM sees anything. Use for: identity verification, data lookups, loading session state, enforcing hard rules.

↓ context passed to LLM ↓

🧠 MIDDLE — `reasoning.instructions:` block

The LLM conversation loop. Handles: natural language, intent detection, tool selection, conversational flow, collecting user input.

↑ returns after reasoning loop exits ↑

🔒 END — `after_reasoning:` block

Runs after every LLM response. Use for: executing writes, enforcing caps, logging, handoffs, session cleanup. Cannot contain | pipe lines.

Script Blocks in Code

subagent.before_reasoning: # Runs deterministically before LLM gets context -> run @actions.validate_identity set @variables.customer_id = @outputs.customer_id if @variables.customer_id == "" transition to @subagent.End_Session end subagent.reasoning: instructions: # Logic block — deterministic -> if @variables.card_blocked == True | The card has already been blocked. | Ask if the customer wants a replacement. end # Pipe lines — sent to LLM | Ask the customer which charge looks suspicious. | Confirm the amount and date before opening a case. subagent.after_reasoning: # Runs after every request — deterministic only, no | pipe -> if @variables.case_id != "" run @actions.log_case_event end

The before_reasoning: block is equivalent to placing logic at the very top of reasoning.instructions:. Use it for clarity.

When to Use Each Block

Block	Use for	Can use `\|` pipe?	Can run actions?
`before_reasoning:`	Auth checks, data loads, pre-conditions	No	Yes
`reasoning.instructions: ->`	Conditional logic inside the reasoning loop	Yes (after `->` block)	Yes
`reasoning.instructions: \|`	Prompts and instructions to the LLM	Yes — this IS the pipe	No
`after_reasoning:`	Writes, logs, transitions, cleanup	No	Yes

💡 Study Tip

When asked to design an agent, always call out the sandwich explicitly: "I'd put identity verification and mandatory data lookups in a deterministic block before the LLM sees any context, and all writes and audit logs in a deterministic block after." That language signals you understand the hybrid model.

✅ Agent Script Advantage

In Agent Script the sandwich is enforced in code. The before_reasoning: block runs unconditionally before the LLM. The after_reasoning: block runs unconditionally after every response. The LLM cannot skip either — they are not instructions, they are code execution.

📦

State Management

How state is passed between subagents and steps in the Classic Model

State Management in Classic Model

In the Classic Model there are no session variables. State is passed between subagents and actions through these mechanisms:

Action outputs — each Action returns outputs that the LLM can reference in the next step
Flow variables — data stored inside a single Flow invocation, not shared across subagents
Salesforce records — write to a record in one subagent, read it in another via a lookup Action
Session context — the LLM retains the conversation history within a session, so earlier outputs are in context

Practical Implications

Without session variables, cross-subagent state requires deliberate design:

If Subagent 1 verifies identity, Subagent 2 must re-verify — or use an Instructions cue like "if the user says they were already verified..."
Avoid re-running expensive Apex actions by writing the result to a Salesforce field and doing a cheap lookup in the next subagent
Keep subagents self-contained — each should gather what it needs at the START layer via its own Actions
The LLM conversation history carries some state, but it's unreliable for critical data — always re-fetch from the source

💡 Classic Model Equivalent

In the Classic model there are no explicit session variables — you pass data between subagents by storing values in Salesforce records or using Flow variables within a single invocation. Agent Script variables are a cleaner abstraction of the same need: don't re-fetch what you already know.

Declaration & Types

Variables are declared in a top-level variables: block, outside of any subagent. They persist across the full agent session and are shared between subagents.

# Top-level — not inside any subagent variables: # Types: mutable string | mutable boolean | mutable integer customer_id: mutable string = "" identity_verified: mutable boolean = False failed_attempts: mutable integer = 0 selected_card_id: mutable string = ""

Always initialize with a default value (= "", = False, = 0). This prevents null errors and makes the initial state explicit.

Reading, Setting, and Injecting

# Read a variable in logic if @variables.identity_verified == True ... end # Set a variable from action output run @actions.validate_identity set @variables.customer_id = @outputs.customer_id # Inject into an LLM prompt | The customer's name is {!@variables.customer_name}. | Address them by name throughout the conversation. # Conditional prompt based on variable -> if @variables.card_blocked == True | Inform the customer the card was already blocked. end

Slot Filling — Let the LLM Collect Values

Use ... as the input value for an action parameter. This tells Agentforce to let the LLM ask the user for the value and fill it automatically via @utils.setVariables.

subagent.actions: - action: open_dispute_case target: flow://Open_Fraud_Dispute_Case inputs: charge_amount: ... # LLM will ask user charge_date: ... # LLM will ask user customer_id: @variables.customer_id # already known

Slot filling replaces manual | Ask the customer for X instructions. The LLM handles the conversation and fills the slot before the action fires.

Sharing Variables Between Subagents

Since variables are top-level, any subagent can read or write them. This is how you pass state across a multi-step flow without repeating lookups.

# Subagent 1 — Report_Fraud sets this: set @variables.identity_verified = True set @variables.customer_id = @outputs.customer_id # Subagent 2 — Block_Card reads it: -> if @variables.identity_verified == True # Skip identity check — already done run @actions.get_active_cards else run @actions.validate_identity end

Always document which subagent sets a variable and which ones consume it. This is critical for debugging.

💡 Classic Model Equivalent

🔀

Routing Between Subagents

How the Reasoning Engine routes requests in the Classic Model — automatic, not coded

Routing in the Classic Model

In the Classic Model, routing between subagents is automatic and invisible — you don't write transition logic. The Reasoning Engine handles it.

The Reasoning Engine reads each subagent's Classification Description at every turn
It picks the best match based on the user's message + conversation history
You control routing by writing clear, distinct Classification Descriptions — not code
Overlapping descriptions = routing errors. Non-overlapping descriptions = clean routing

How to Guide Routing in Classic

Classification Description — the most powerful routing tool. Write it as the exact type of message this subagent should receive
Scope: CANNOT handle — tells the engine what NOT to route here, preventing ambiguous overlap
Instructions — can include "If the customer asks to do X, tell them to Y" as a soft redirect, but this is LLM-dependent
Handoff Actions — to escalate to a human, invoke a Transfer action from Instructions. This is the only "explicit transition" in Classic

There is no deterministic "go to subagent X" in the Classic Model. Routing is always probabilistic — the engine reads, infers, and routes.

💡 Classic Model Equivalent

In the Classic model, "transitions" don't exist as a concept — routing between subagents happens automatically via the Reasoning Engine's classification step. Agent Script makes transitions explicit and controllable. The important thing is knowing when to route and why, regardless of how it's implemented.

Two Types of Transitions

Type	How to Declare	Who Decides	Returns?
Reasoning transition LLM	Defined in `reasoning.actions:` — exposed to LLM as a tool	LLM chooses when to call it based on conversation context	No — one-way via `@utils.transition to @subagent.X`
Deterministic transition Code	Written directly in `->` logic block	Code — fires unconditionally or based on an `if` condition	No — one-way, discards current prompt
Direct subagent call Returns	Use `@subagent.X` directly in a reasoning action	LLM or script calls the subagent inline	Yes — returns to caller after subagent completes

Transition Code Examples

# Reasoning transition (LLM-driven) — defined as an action subagent.reasoning.actions: - action: go_to_block_card description: Transition to the Block_Card subagent when the customer wants to block their card. target: @utils.transition to @subagent.Block_Card # Deterministic transition — in logic block -> if @variables.identity_verified == False transition to @subagent.End_Session end # Filtered — only available when condition is met subagent.reasoning.actions: - action: go_to_replacement_card description: Offer replacement after card is blocked. available when @variables.card_blocked == True target: @utils.transition to @subagent.Request_Replacement_Card

Best Practices for Transitions

Name transition actions with the go_to_ prefix: go_to_block_card, go_to_escalate_agent
Place deterministic transitions at the top of the instructions block — they act as guards and run first
Use available when to conditionally expose reasoning transitions — only show them to the LLM when they make sense
Avoid transition loops — if A can transition to B and B can transition to A, add guards to prevent infinite loops
Prefer @subagent.X (returns) over @utils.transition (one-way) when you need to continue the current flow after a helper subagent runs

Use `after_reasoning:` for End-of-Turn Transitions

The after_reasoning: block is ideal for transitions that always happen at the end of a turn — e.g., moving to a summary subagent after every response, or closing the session when a variable is set.

subagent.after_reasoning: -> # Store what the user said into a variable set @variables.last_intent = @inputs.user_message # Always transition to handoff if escalation flag is set if @variables.needs_human == True transition to @subagent.Escalate_To_Agent end

Remember: after_reasoning: cannot contain | pipe lines — only logic and transitions.

💡 Classic Model Equivalent

In the Classic model, "transitions" don't exist as a concept — routing between subagents happens automatically via the Reasoning Engine's classification step. Agent Script makes transitions explicit and controllable. For CTA design questions, the important thing is knowing when to route and why, regardless of how it's implemented.

⚙️

Execution Flow

Step-by-step reasoning engine logic when a user sends a message

Classification

Match message to Subagent via name & description

Context Assembly

Gather instructions, Script, and available actions

Deterministic Logic

Execute scripted rules before LLM evaluation

LLM Decision

Evaluate prompt: run action, ask for info, or respond

Action Execution

Run the selected action and collect results

Grounding Check

Verify answer accuracy and scope compliance

Response

Deliver final grounded answer to the customer

📚

RAG — Retrieval Augmented Generation

How Agentforce grounds responses in real data

🗄️ Agentforce Data Libraries (ADL)

Structured data: Cases, Accounts, Knowledge Articles, Salesforce objects
Unstructured data: PDFs, HTML files, plain text documents
Indexed and chunked for fast retrieval
Chunking uses HTML heading tags (H1–H6) as delimiters

🔍 Retrievers

Bridge between the search index and the LLM prompt
Run at inference time — not pre-baked into the model
Augment AI responses with contextual, up-to-date data
Spread content across multiple fields (Question, Description, Resolution) for better retrieval

🏆

Best Practices

Context engineering, instructions, actions, and RAG data curation

🧩 Context Engineering

Overload prompts trying to craft perfect words

Design a holistic system of distinct subagents and explicit rules

Start with long, complex instruction sets

Start with 1–3 key guidelines per subagent and iterate

🏢 Subagent Design

Create overlapping subagents (e.g., "Product Support" + "Troubleshooting")

Keep subagents clear, distinct, and non-overlapping

Leave scope ambiguous

Define explicit scope: what the agent CAN and CANNOT do

⚡ Actions

Use highly descriptive Action API Names — the LLM reads these to pick the right tool

Write clear Action Instructions: what it does, inputs required, when to invoke

Give explicit decision criteria when two actions are similar

Leave the LLM to guess when to use similar actions

💬 Instructions Language

Use "always" and "never" sparingly and intentionally — they carry heavy weight

Use exact action API names in instructions for correct matching

Encode complex multi-step sequences in natural language instructions

Use Agentforce Script or Flows for mandatory sequential logic

📄 RAG Data Curation

Structure HTML/text with H1–H6 headings — chunking uses these as delimiters

Spread long content across multiple Salesforce fields (Question, Description, Resolution)

Cram all content into a single long-text field

Use unstructured blobs of text without headings

⚖️ Hybrid Reasoning

Use Instructions for tone, behavior, and flexible conversation

Use Agentforce Script for deterministic, mandatory, or sensitive business logic

Use LLM instructions to handle calculations or database writes

Use hard-coded rules for open-ended conversational responses

⚡ Action Design

Use highly descriptive Action API names (e.g., Validate_Customer_Identity) — the LLM reads these to pick the right tool

Write clear Action descriptions: what it does, what inputs it needs, and exactly when to invoke it

Use double underscores (__) in Action API names — they conflict with Salesforce custom field notation

Configure two similar actions without explicit decision criteria — the LLM will guess which to use

Variables, Transitions, and Agent Script-specific best practices — switch to Agent Script to view them.

🧩 Context Engineering

Overload prompts trying to craft perfect words

Design a holistic system of distinct subagents and explicit rules

Start with long, complex instruction sets

Start with 1–3 key guidelines per subagent and iterate

🏢 Subagent Design

Create overlapping subagents (e.g., "Product Support" + "Troubleshooting")

Keep subagents clear, distinct, and non-overlapping

Leave scope ambiguous

Define explicit scope: what the agent CAN and CANNOT do

⚡ Actions

Use highly descriptive Action API Names — the LLM reads these to pick the right tool

Write clear Action Instructions: what it does, inputs required, when to invoke

Give explicit decision criteria when two actions are similar

Leave the LLM to guess when to use similar actions

💬 Instructions Language

Use "always" and "never" sparingly and intentionally — they carry heavy weight

Use exact action API names in instructions for correct matching

Encode complex multi-step sequences in natural language instructions

Use Agentforce Script or Flows for mandatory sequential logic

📄 RAG Data Curation

Structure HTML/text with H1–H6 headings — chunking uses these as delimiters

Spread long content across multiple Salesforce fields (Question, Description, Resolution)

Cram all content into a single long-text field

Use unstructured blobs of text without headings

⚖️ Hybrid Reasoning

Use Instructions for tone, behavior, and flexible conversation

Use Agentforce Script for deterministic, mandatory, or sensitive business logic

Use LLM instructions to handle calculations or database writes

Use hard-coded rules for open-ended conversational responses

📦 Variables

Always initialize variables with a default value ("", False, 0) — prevents null errors and makes state explicit

Use variables to share state between subagents instead of re-running the same lookup actions

Use slot filling (set input to "...") to let the LLM collect required action inputs naturally from the user

Store sensitive data (passwords, full card numbers) in session variables

🔀 Transitions

Prefix all transition actions with "go_to_" — makes routing intent clear to both you and the LLM

Place deterministic transitions at the TOP of the instructions block — they act as early-exit guards

Use "available when" to hide transitions from the LLM until the right conditions are met

Create transition loops without explicit guards — A to B to A will spin forever

⚡ Action Design

Set filter_from_agent: True on actions whose output feeds other actions only — keeps LLM context clean

Use "available when" on reasoning actions to gate tools by variable state — only show the LLM what's relevant

Chain reasoning actions by adding "run @actions.next" after the first — forces deterministic follow-up steps

Use double underscores (__) in action API names — they conflict with Salesforce custom field notation and break parsing

🗺️

Full Architecture Overview

End-to-end diagram from user message to grounded response

Real-World Example

🏦 Banking Agent — Fraud & Card Management

A customer contacts the bank's chat to report an unrecognized charge, block their card, and request a replacement. Agent Profile, Subagents, RAG, and the Conversation are the same in both models. Only the Sandwich implementation differs.

Showing: Classic Model — Instructions + Actions in the Builder UI, no code in the agent definition.

🤖 Agent Profile

Name, channel, persona — the top-level identity of the agent

Agent Name

Clara — Security Assistant

Agent User (Identity)

clara.agent@bank.com (dedicated Service user)

Channels

Embedded Service (web banking), WhatsApp Messaging

System Prompt / Persona

You are Clara, a security assistant for BankCorp. You help customers report fraud, block cards, and request replacements. You are empathetic and efficient. You never invent information — all answers must come from verified data or system results. You do not negotiate pricing, process refunds, or close accounts.

🏢 Subagents

Classification description, scope, instructions, and actions for each subagent

Subagent 1 — Report_Unrecognized_Charge

"I see a charge I didn't make" / "There's a suspicious transaction"

Classification Description

The customer is asking about a charge, transaction, or movement on their card that they don't recognize, didn't authorize, or consider suspicious or fraudulent.

Scope

CAN Handle

Look up recent transactions
Open a fraud dispute case
Explain the dispute resolution process
Escalate to card blocking if customer requests it

CANNOT Handle

Resolve the dispute or issue refunds
Access accounts the customer doesn't own
Block the card (that's Subagent 2)
Make promises about resolution timelines

Instructions

1. Always ask the customer to confirm the exact amount and approximate date of the charge before invoking Open_Fraud_Dispute_Case. Do not open the case with incomplete data.

2. If the customer cannot remember the exact amount, invoke Get_Recent_Transactions to show the last 10 movements and ask them to identify the suspicious one(s).

3. After successfully opening the case, always share the case number and inform the customer of the next steps using Get_Dispute_Resolution_Info.

Actions

API Name	Type	What It Does	When to Invoke
Validate_Customer_Identity	Flow	Confirms authenticated user is the cardholder. Returns `verified` and customer ID.	Always — first action
Get_Recent_Transactions	Apex	Queries last 10 card transactions. Returns date, merchant, amount.	When customer can't recall exact charge details
Open_Fraud_Dispute_Case	Flow	Creates a Case with Type = "Fraud Dispute". Returns Case Number.	After customer confirms amount and date
Get_Dispute_Resolution_Info	Prompt Template + ADL	Retrieves resolution timeline from Knowledge Base by card type.	Immediately after case is created

Subagent 2 — Block_Card

"Block my card" / "I lost my card" / "Someone stole my card"

Classification Description

The customer wants to block, freeze, cancel, or deactivate their card — because it was lost, stolen, or they detected fraud and want to prevent further charges.

Scope

CAN Handle

Block a debit or credit card immediately
Confirm which card was blocked
Inform about impact on linked services
Offer to start a replacement request

CANNOT Handle

Unblock cards (requires branch verification)
Block full accounts or other products
Block a card without customer's explicit confirmation

Instructions

1. Never invoke Block_Card_Immediately without first asking the customer to confirm the last 4 digits of the card to block. Blocking is irreversible via this channel.

2. If the customer is arriving from a fraud report (identity already verified), do not re-ask for identity — the session variable identity_verified will be true.

3. After confirming the block, always ask: "Would you like me to start the process for a replacement card?" — do not assume they want one.

Actions

API Name	Type	What It Does	When to Invoke
Validate_Customer_Identity	Flow	Reusable action. Skipped if `identity_verified = true` in session.	Only if not already verified
Get_Customer_Active_Cards	Apex	Returns active cards: last 4 digits, card type, network.	Always — so customer can confirm which to block
Block_Card_Immediately	Apex	Sends real-time block request to core banking API. Returns confirmation timestamp.	Only after customer confirms last 4 digits
Log_Card_Block_Event	Flow	Creates audit record: card ID, timestamp, channel, reason.	Always — immediately after block succeeds

Subagent 3 — Request_Replacement_Card

"I need a new card" / "Send me a replacement" / "When does my new card arrive?"

Classification Description

The customer wants to request a new card to replace one that was blocked, lost, stolen, or damaged. They may also be asking about the status of a replacement already requested.

Scope

CAN Handle

Create a replacement card request
Confirm or update the shipping address
Check status of an existing replacement request

CANNOT Handle

Upgrade card type or change credit limit
Issue a card for a new product (that's sales)
Create a duplicate if one is already active

Instructions

1. Always invoke Get_Replacement_Card_Status before creating a new request. If an active request already exists, show its status instead of creating a duplicate.

2. Always confirm the shipping address on file with the customer before invoking Create_Replacement_Card_Request. Ask if they want to use the address on file or a different one.

3. After creating the request, always provide the tracking reference number and estimated delivery timeframe from Get_Card_Delivery_Terms.

Actions

API Name	Type	What It Does	When to Invoke
Get_Replacement_Card_Status	Apex	Checks if a replacement already exists. Returns status and delivery date if found.	Always — first action
Get_Customer_Address_On_File	Apex	Returns the registered mailing address for confirmation.	Before creating the request
Create_Replacement_Card_Request	Flow	Submits replacement to card ops system. Returns tracking reference number.	After address is confirmed
Get_Card_Delivery_Terms	Prompt Template + ADL	Retrieves delivery timeline by card type and region from Knowledge Base.	After request is created

🥪 Deterministic Sandwich

Classic Model — sandwich as a design pattern, enforced via Flows and Instructions

Subagent 1 — Report Fraud

🔒 START (Flow)
Invoke Validate_Customer_Identity Flow. If verification fails → end session. Store customer_id in Flow variable passed as action output.

↓ action output passed as context to LLM ↓

🧠 MIDDLE (LLM — Instructions)
"If the customer cannot recall the charge, invoke Get_Recent_Transactions. Confirm amount and date before opening a dispute."

↑ LLM collects confirmed data ↑

🔒 END (Flow)
LLM invokes Open_Fraud_Dispute_Case Flow (with confirmed params). LLM then invokes Get_Dispute_Resolution_Info.

Subagent 2 — Block Card

🔒 START (Flow)
Invoke Get_Customer_Active_Cards Apex Action. If identity not yet verified, invoke Validate_Customer_Identity first.

↓ card list returned to LLM ↓

🧠 MIDDLE (LLM — Instructions)
"Never invoke Block_Card_Immediately without explicit confirmation of last 4 digits. If arriving from fraud report, do not re-ask for identity."

↑ LLM gets explicit confirmation ↑

🔒 END (Flow)
LLM invokes Block_Card_Immediately. Then LLM must invoke Log_Card_Block_Event. Both enforced via Instructions ordering.

Subagent 3 — Replacement

🔒 START (Flow)
Invoke Get_Replacement_Card_Status. If active request found, Instructions tell LLM to show status and stop. Invoke Get_Customer_Address_On_File.

↓ status + address passed to LLM ↓

🧠 MIDDLE (LLM — Instructions)
"Always confirm address before creating request. If a replacement already exists, show status instead of creating duplicate."

↑ LLM gets address confirmation ↑

🔒 END (Flow)
LLM invokes Create_Replacement_Card_Request Flow. Then invokes Get_Card_Delivery_Terms. Returns tracking + ETA.

⚠️ Limitación del Classic Model

En el Classic Model el sandwich es un patrón de diseño, no una garantía técnica. El END layer depende de que las Instructions indiquen correctamente al LLM qué action invocar y en qué orden. Si las instrucciones son ambiguas, el LLM podría saltarse un paso. El Agent Script elimina esta fragilidad poniendo el END en código.

Subagent 1 — Report_Unrecognized_Charge

variables: customer_id: mutable string = "" identity_verified: mutable boolean = False case_id: mutable string = "" subagent.actions: - action: validate_identity target: flow://Validate_Customer_Identity_Flow - action: open_fraud_dispute_case target: flow://Open_Fraud_Dispute_Case_Flow subagent.reasoning.actions: - action: get_recent_transactions description: Retrieve the last 10 card transactions for the customer. Invoke when the customer cannot recall the exact charge amount or date. target: apex://TransactionController.getRecent - action: get_dispute_resolution_info description: Retrieve fraud dispute resolution timeline from the knowledge base. Invoke after a case is opened to inform the customer of next steps. target: prompt://Dispute_Resolution_Info_Template - action: go_to_block_card description: Transition to Block_Card subagent when the customer also wants to block their card. available when @variables.case_id != "" target: @utils.transition to @subagent.Block_Card subagent.before_reasoning: -> run @actions.validate_identity set @variables.customer_id = @outputs.customer_id set @variables.identity_verified = @outputs.verified if @variables.identity_verified == False transition to @subagent.End_Session end subagent.reasoning: instructions: -> if @variables.customer_id != "" | The customer has been verified. Their ID is {!@variables.customer_id}. end | Ask the customer to describe the suspicious charge. | If they cannot recall the amount, use {!@actions.get_recent_transactions} to show recent transactions. | Confirm the exact amount and date before proceeding with the dispute. subagent.after_reasoning: -> if @variables.case_id != "" run @actions.get_dispute_resolution_info end

Subagent 2 — Block_Card

subagent.actions: - action: validate_identity target: flow://Validate_Customer_Identity_Flow - action: block_card_immediately target: apex://CardController.blockCard - action: log_card_block_event target: flow://Log_Card_Block_Audit_Flow subagent.reasoning.actions: - action: get_customer_active_cards description: Return a list of active cards (last 4 digits, type, network). Always invoke first so the customer can identify which card to block. target: apex://CardController.getActiveCards - action: go_to_replacement_card description: Transition to Request_Replacement_Card after card is successfully blocked. available when @variables.card_blocked == True target: @utils.transition to @subagent.Request_Replacement_Card subagent.before_reasoning: -> if @variables.identity_verified == False run @actions.validate_identity set @variables.identity_verified = @outputs.verified end run @actions.get_customer_active_cards set @variables.active_cards = @outputs.cards subagent.reasoning: instructions: | Show the customer their active cards and ask which one to block (confirm last 4 digits). | Never block the card without explicit confirmation of the last 4 digits. | After confirming the block, ask: "Would you like me to request a replacement card?" subagent.after_reasoning: -> if @variables.confirmed_card_id != "" run @actions.block_card_immediately run @actions.log_card_block_event set @variables.card_blocked = True end

Subagent 3 — Request_Replacement_Card

subagent.actions: - action: get_replacement_card_status target: apex://CardController.getReplacementStatus - action: get_customer_address_on_file target: apex://CustomerController.getAddress - action: create_replacement_card_request target: flow://Create_Replacement_Card_Request_Flow subagent.reasoning.actions: - action: get_card_delivery_terms description: Retrieve delivery timeline by card type and region. Invoke after creating the replacement request to inform the customer of ETA. target: prompt://Card_Delivery_Terms_Template subagent.before_reasoning: -> run @actions.get_replacement_card_status if @outputs.replacement_active == True | Inform the customer a replacement request already exists. | Show status: {!@outputs.status} — estimated delivery: {!@outputs.delivery_date}. transition to @subagent.End_Session end run @actions.get_customer_address_on_file set @variables.address_on_file = @outputs.address subagent.reasoning: instructions: | Show the customer their address on file: {!@variables.address_on_file}. | Ask if they want to use this address or provide a different one. | Only proceed with the replacement request after address is confirmed. subagent.after_reasoning: -> if @variables.shipping_address != "" run @actions.create_replacement_card_request set @variables.tracking_ref = @outputs.tracking_reference run @actions.get_card_delivery_terms end

Session Variables — Flow Across Subagents

Variable	Type	Set By	Read By
`customer_id`	mutable string	Report_Unrecognized_Charge	All subagents
`identity_verified`	mutable boolean	Any subagent that runs validate_identity	Block_Card — skips re-verification if True
`case_id`	mutable string	Report_Unrecognized_Charge	Unlocks go_to_block_card transition
`card_blocked`	mutable boolean	Block_Card after successful block	Unlocks go_to_replacement_card transition
`tracking_ref`	mutable string	Request_Replacement_Card	LLM uses to confirm tracking number to customer

📚 RAG / Data Strategy

Knowledge Base structure, article fields, and Retriever wiring per subagent

Knowledge Article Structure (HTML for best chunking)

<h1>Fraud Dispute Process</h1> <h2>Resolution Timelines by Card Type</h2> <h3>Debit Card — 5 business days</h3> <h3>Credit Card — 10 business days</h3> <h2>What Happens After You File</h2> <h2>International Charges</h2> <h1>Replacement Card Policy</h1> <h2>Standard Delivery — 5–7 business days</h2> <h2>Express Delivery — 1–2 business days (fee applies)</h2> <h2>Impact on Recurring Payments</h2>

Salesforce Knowledge Article Fields — spread content, never one blob

Field	Content
Title	Short, keyword-rich: "Fraud Dispute — Credit Card Resolution Timeline"
Summary	One sentence: what this article answers
Question	The exact customer question this article answers
Answer	The policy answer in plain language
Exceptions	Edge cases, international rules, fee exceptions
Last Reviewed	Date — Retriever can deprioritize stale content

Retriever Wiring per Subagent

Subagent	Retriever Scope	Action That Triggers It
Report_Unrecognized_Charge	Fraud Dispute articles only	Get_Dispute_Resolution_Info
Block_Card	Card blocking impact — recurring payments, linked services	Surfaced proactively in LLM MIDDLE layer
Request_Replacement_Card	Replacement delivery terms, address change policy	Get_Card_Delivery_Terms

💬 End-to-End Conversation Flow

The full customer interaction — annotated with which component runs at each message

👤 Customer: Hi, I see a $250 charge from "AMZN*123" that I didn't make.

→ Routes to
Report_Unrecognized_Charge

🤖 Clara: I'm sorry to hear that. Let me pull up your recent transactions. [runs Get_Recent_Transactions] I can see a charge of $250 from AMZN*123 on May 15th. Can you confirm this is the one you'd like to dispute?

⚡ Apex: Get_Recent_Transactions
🧠 LLM synthesizes result

👤 Customer: Yes, that's the one. Please dispute it.

Confirmation received ✓

🤖 Clara: Done! I've opened dispute case #FR-2026-88423. [runs Open_Fraud_Dispute_Case] Our team will review it within 5 business days. [runs Get_Dispute_Resolution_Info from ADL] Would you also like to block your card to prevent any further charges?

🔒 Script: Open_Fraud_Dispute_Case
📚 RAG: resolution terms
→ Transition to Block_Card

👤 Customer: Yes, please block it.

→ Routes to Block_Card
identity_verified = true ✓

🤖 Clara: I can see your Visa card ending in 4821. Can you confirm these are the last 4 digits of the card you'd like to block?

🔒 Script: Get_Customer_Active_Cards
🧠 LLM: confirmation step

👤 Customer: Yes, 4821.

Explicit confirmation ✓

🤖 Clara: Your card ending in 4821 has been blocked. [runs Block_Card_Immediately + Log_Card_Block_Event] Would you like me to request a replacement card sent to your address on file?

🔒 Script: Block + Log
→ Transition to
Request_Replacement_Card

🎉 Example Complete!

You've reviewed the full Banking Agent configuration — from Agent Profile to a live conversation.

Hybrid Reasoning · Blueprint Hierarchy · Classic & Script Models · Best Practices

📘 Architecture Patterns & Reference

Hybrid Reasoning Model

🎲 Probabilistic Reasoning LLM / Flexibility

🔒 Deterministic Execution Rules / Control

Authoring in Builder

Authoring in Builder UI

How Instructions Work

What is Agent Script?

Three Ways to Author Agent Script

Key Syntax — The Two Operators

Minimal Script Skeleton

Agent Blueprint / Architecture

A. Agent Profile Top Level

B. Subagents Formerly "Topics"

C. Instructions Plain text in Builder UI

D. Actions Configured separately

Flow Actions Deterministic

Apex Actions Deterministic

Prompt Template Actions LLM-enhanced

MuleSoft / API Actions

E. Data & Context RAG

Agentforce Data Libraries (ADL)

Retrievers

A. Agent Profile Top Level

B. Subagents Formerly "Topics"

C. Agentforce Script One file per subagent

D. Actions Two blocks in the script

subagent.actions Deterministic

subagent.reasoning.actions LLM Tools

Action Targets

E. Data & Context RAG

Agentforce Data Libraries (ADL)

Retrievers

Deterministic Sandwich Pattern

🔒 START — Flow invoked as first Action

🧠 MIDDLE — Instructions field (plain text)

🔒 END — Flow invoked as final Action

How to Enforce the Sandwich in Classic

🔒 START — before_reasoning: block

🧠 MIDDLE — reasoning.instructions: block

🔒 END — after_reasoning: block

Script Blocks in Code

When to Use Each Block

State Management

State Management in Classic Model

Practical Implications

Declaration & Types

Reading, Setting, and Injecting

Slot Filling — Let the LLM Collect Values

Sharing Variables Between Subagents

Routing Between Subagents

Routing in the Classic Model

How to Guide Routing in Classic

Two Types of Transitions

Transition Code Examples

Best Practices for Transitions

Use after_reasoning: for End-of-Turn Transitions

Execution Flow

RAG — Retrieval Augmented Generation

🗄️ Agentforce Data Libraries (ADL)

🔍 Retrievers

Best Practices

🧩 Context Engineering

🏢 Subagent Design

⚡ Actions

💬 Instructions Language

📄 RAG Data Curation

⚖️ Hybrid Reasoning

⚡ Action Design

🧩 Context Engineering

🏢 Subagent Design

⚡ Actions

💬 Instructions Language

📄 RAG Data Curation

⚖️ Hybrid Reasoning

📦 Variables

🔀 Transitions

⚡ Action Design

Full Architecture Overview

🔒 START — `before_reasoning:` block

🧠 MIDDLE — `reasoning.instructions:` block

🔒 END — `after_reasoning:` block

Use `after_reasoning:` for End-of-Turn Transitions