Agent Script

Agent Script is the configuration language used to define, declaratively, the behavior of an AI agent within the Salesforce ecosystem. Instead of writing imperative logic step by step, the developer or administrator describes what the agent should do: its general instructions, the topics or tasks it knows how to handle, the actions it can execute and the limits it must not cross. It is the layer that translates a business intent ("answer stock questions and route complaints to a human") into a specification that the platform's reasoning engine can interpret and execute.

The central idea is the separation between the what and the how. The team defines the script (the rules, the topics, the available tools), and the language model, together with the orchestration engine, decides in real time what to answer and which action to invoke in each conversation. It is an approach related to prompt engineering, but structured and versionable like code, not like loose text.

In the context of building agents on Salesforce, Agent Script is part of the toolkit we cover in Salesforce Developers: it defines the behavior contract that is then connected to the platform's data, actions and security guards.

Why Agent Script exists

Before AI agents, automating an interaction meant programming every possible branch: if the user says X, reply Y; if they ask for Z, run this query. That approach, typical of a decision-tree chatbot, becomes unmanageable as soon as conversations branch out. Agent Script flips the model: instead of coding every path, you define a behavioral framework (instructions, topics and permitted actions) and delegate to the language model the decision of what to do on each turn. That brings it closer to the agentic AI paradigm, where the system reasons about goals instead of following a rigid script.

The practical motivation is twofold. First, speed of construction: an agent that used to require weeks of flow development can be specified in hours by describing its purpose and its tools. Second, governability: because it is a declarative, versionable specification, what the agent can and cannot do is made explicit, which is critical when it is going to touch customer data or execute real operations.

How it works, piece by piece

An agent script is usually organized around a few configuration blocks. Although the exact syntax evolves with the platform, the conceptual components are stable:

• Instructions (a structured system prompt): the agent's role, its tone and its business rules. This is where you define the personality and the policies ("never promise discounts", "always ask for the order number before checking the status").
• Topics: the agent's areas of competence. Each topic groups a set of related tasks and the actions that resolve them. They let the agent know, when a query comes in, which domain it is operating in.
• Actions: the tools the agent can invoke through tool calling. They can be a Salesforce Flow, an Apex class, a call to an external API or a knowledge search. Each action declares what information it needs and what it returns.
• Guards and limits: the conditions for escalating to a human (through a human handoff), the data the agent must not expose and the validations that protect against unwanted behavior.

At run time, the reasoning engine (the Atlas Reasoning Engine) takes the user's message, identifies the relevant topic, decides whether it needs to run an action to answer, invokes it, receives the result and builds the response. The script is the map; the engine is what travels it.

Agent Script vs a Flow or Apex

The most common confusion is what each tool is for within Salesforce. The difference is one of level of abstraction:

The key is that they do not compete; they complement each other. Agent Script defines the agent and, within it, declares actions that are often Flows or Apex methods. The agent decides when to call them; the Flow executes the exact logic. A good design leaves the conversation and the reasoning in Agent Script, and delegates to Flow or Apex everything that must be deterministic and auditable, such as creating a case, calculating a price or recording a transaction.

A concrete example (LATAM)

Picture a consumer goods distributor in Argentina that takes orders over WhatsApp. Its AI agent, defined with Agent Script, has three topics: checking stock, placing an order and handling complaints. In the stock topic, the agent invokes an action that queries the inventory system; when a customer asks, "do you have the 2.25-liter soda available at the Avellaneda warehouse?", the script tells the agent it is in the stock topic, it runs the query and replies with the real figure. If the customer moves on to complain about a late delivery, the script detects that it is a sensitive complaint and triggers the handoff to a human representative. None of that required programming every possible sentence: the behavior was described and the actions were connected.

Common mistakes when writing Agent Script

• Vague instructions: saying "help the customer" without narrowing the scope produces an agent that improvises too much. Precise instructions reduce the risk of hallucination.
• Too many topics or actions in a single agent: an overloaded script confuses the model about which tool to use. Focused, well-bounded agents work better.
• Not defining the handoff: an agent without an escalation path to a human frustrates the user in the cases it cannot resolve.
• Confusing Agent Script with a loose prompt: it is not just text; it is a specification that must be tested, versioned and reviewed like any other software artifact.

Handled with that discipline, Agent Script becomes the piece that makes an AI agent on Salesforce predictable, governable and fast to iterate, without giving up the flexibility of natural language.