Agent Script: Understanding the 8 Essential Blocks in Salesforce Agentforce

💬 In plain words: An Agent Script is a collection of building blocks, where each block contains either specific data or procedural logic. There are exactly eight types of blocks available, but as a developer, you will spend the vast majority of your time working inside just four of them.

📌 Example: Let's say you are building an internal employee assistant for a company called Meridian. This agent requires a config block with agent_type explicitly set to AgentforceEmployeeAgent. It also needs a variables block to store session data like the employee's meter ID and outage status, five separate subagent blocks to handle specific tasks, and a start_agent block to act as the traffic cop.

Concept: The 8 Core Blocks

• system: This block holds the agent's general overarching instructions and message prompts. Note: The welcome and error messages inside this block are strictly required.
• config: This block stores the fundamental agent configuration parameters, defining its identity.
• variables: This block acts as the state manager, holding global values that the agent and the script utilize throughout the conversation session.
• language: This block explicitly declares which spoken or written languages the agent is configured to support.
• connection: This block describes how the agent interacts with external systems or human interfaces (like Enhanced Chat). It pairs closely with the escalate utility when a human handoff is needed.
• subagent: The workhorse block. Each subagent represents one specific specialist topic or capability. A script typically contains many of these.
• connected_subagent: (Currently in Pilot/Beta) This block allows your agent to link directly to a completely separate agent deployed elsewhere in your Salesforce org.
• start_agent: This is the Agent Router—the entry point that determines which subagent should handle the user's initial request.

Key config Parameters You Must Know:

• developer_name (Must be unique across the org)
• agent_label
• description
• company
• role
• agent_version
• agent_type
• default_agent_user
• enable_enhanced_event_logs
• user_locale

Agent Script Structure
├─ system               → Welcome + error messages (REQUIRED)
├─ config               → Identity and settings
├─ variables            → Session state management
├─ language             → Supported locales
├─ connection           → Human handoff / Enhanced Chat integration
├─ subagent             → One topic specialist (You will have many)
├─ connected_subagent   → Another agent entirely (PILOT/BETA)
└─ start_agent          → The Agent Router

🧠 Two default settings that frequently bite developers: 1. If you don't specify it, `agent_type` defaults to SERVICE. 2. The `default_agent_user` setting is completely IGNORED on employee agents.

🧭 360 Card — Blocks and Config

Rule: Always set your agent_type explicitly, and always turn on enhanced event logs while you are building.
Gain: You will never be surprised about which identity you just built, and deep trace logs are available immediately from your very first test.
Price: Enhanced logging permanently stores conversation records. You must confirm that this aligns with your company's data privacy policies.
Limits: The developer_name must be completely unique within the org, cannot exceed 80 characters, and cannot contain trailing or consecutive underscores.
Mirror (Leaving agent_type unset): If you forget to set it, the system defaults to building a Service Agent, and you will waste time wondering why the system is suddenly demanding a default_agent_user.
Later: This script file is exactly what gets committed into Git for version control. Everything discussed here is standard Salesforce metadata.

⚠ INTERVIEW TRAP:
If asked to name the script blocks, do not list a "knowledge" block. There is no such thing as a knowledge block in the base script structure. There are only eight: system, config, variables, language, connection, subagent, connected_subagent, and start_agent.

Core Q&A

Q: What exactly is Agent Script, and how does it relate to the Agent Builder UI?

🎯 Say this first: Agent Script is the underlying language that agents are written in. Clicking around in the visual Canvas view and typing code in the Script view produce the exact same metadata file.

A: The most important concept to grasp is that the Builder UI and the Script are not two separate products.

• Agent Script is a highly readable, whitespace-sensitive language that compiles directly into the metadata that the Salesforce reasoning engine consumes.
• Anything you construct visually by clicking and dragging in the Canvas view can be immediately opened and edited in the Script view—or even pulled locally into VS Code using Agentforce DX.
• Because of this architecture, agents are just ordinary Salesforce metadata. They can be pushed into source control, go through peer review, and deploy seamlessly between sandbox and production orgs via standard CI/CD pipelines.
• The script architecture is divided into eight primary blocks: system, config, variables, language, connection, subagent, connected_subagent, and start_agent.
• When configuring an agent, keep two tricky details in mind: if you omit the agent_type, it defaults to a Service Agent. Furthermore, while a default_agent_user is strictly required for a Service Agent, it is completely ignored if you are building an Employee Agent.
• As a best practice, always turn on enhanced event logs during the build phase—it is the cheapest, easiest debugging tool available to you.