Why design AI Agent Instructions?
AI Agents are revolutionizing how businesses interact with users, automate tasks, and deliver insights. However, without a structured and governed approach to designing these agents, outcomes become unpredictable, inconsistent, or even unsafe. Poorly defined agent logic will confuse Agents, trigger the wrong automations, or breach compliance boundaries.
By using AI Agent Instruction diagrams, Salesforce architects can design modular, transparent, and governable agent behavior. These diagrams enable visual design of agent logic, enriched with contextual rules, actions, and probabilistic prompts—all while ensuring clarity, consistency, and auditability.
When to design AI Agent Instructions?
Use AI Agent Instructions when:
You’re in the early design phase of an AI Agent and need a modular view of tasks or conversations
You want to scope and prototype a specific “jobs to be done” to be followed by an Agent
You need a structured format to validate logic, identify gaps, or conduct cross-functional reviews.
You wish to generate user stories or test cases to hand off to development or AI training teams.
Prerequisites
Before you start:
Your user should have permissions to create and edit diagrams.
Design Agent Instructions
Step 1: Create a New Agent Instruction Diagram
Navigate to AI Agents in the left-hand menu.
Click New → Select Agent Instruction Design.
A new canvas will open with interface and layout optimized for agent behavior design.
Step 2: Define Agent Guardrails
From the left panel, drag the Guardrails icon onto the canvas.
Use guardrails only to define absolute “always” or “never” rules for your Agent.
Example “never” rules: Never answer questions about pricing, Never swear or insult the user.
Example “always” rules: Always remain professional, friendly, and empathetic.
These are hard boundaries, not business logic — all other logic should be handled using the instruction shapes.
Limit usage: In most cases, 1 to 3 guardrails are sufficient. Overuse dilutes clarity and defeats their purpose.
Step 3: Use Predefined Agent Instruction Shapes
Click the shape icon in the left panel. This opens a specialized component that includes three predefined shape types, each designed to capture a different mode of agent behavior:
Agent Instruction Step
Use this shape to define what the Agent is supposed to do using probabilistic reasoning. This represents the core “job to be done” where the Agent must interpret the user's or system's input, decide on intent, and act accordingly using large language models.
Example: Inform the user about available delivery slots based on their postal code.
Agent Action
This shape represents deterministic actions that the agent should trigger. Use it whenever the task involves a defined system automation, such as retrieving, updating, or triggering a flow, apex class, API, or integration.
Example: Create a case in Salesforce once the user confirms the issue type.
Prompt Template
Use this for complex interpretation or reasoning tasks that require long-form or nuanced understanding, especially when the agent must analyze unstructured input or synthesize a response.
Example: Interpret the sales transcript and extract user objections, interests, and tone.
Each shape is pre-populated with:
Default resource (e.g., System: AI Agent, System: Action, or System: Prompt Template)
Instructional prompt inside the activity box
Suggested default condition for the incoming flowline
Step 4: Capture logic
Connect your logical steps and specify the conditional logic. Flowline text should be unique and verifiable, e.g., “User provides order number”, so that the Agent knows under which conditions to perform the next step.
Look at the instruction diagram below. You can enlarge the image if you click on it. Notice how detailed, unambiguous is the text on the flowlines.
This helps us architect the instructions in a way that makes it simple for AI to understand and follow reliably.
This is not a flow. It’s guidance for a digital employee.
AI Agent Instruction diagrams are not deterministic workflows. They’re not intended to prescribe exact steps the agent must follow in every case. That’s a common misconception.
Think of this as defining a set of work instructions for a digital employee—an AI-powered team member that interprets input, uses judgment, and chooses the best course of action based on training and context.
These diagrams are your way of saying:
"Here’s what you're responsible for."
"Here’s how we expect you to behave in different scenarios."
"Here are the actions you can take—and when to take them."
"Here are the boundaries you must never cross."
This structure helps the Agent reason better, make fewer mistakes, and behave in line with your organization's expectations—even when it’s operating in a probabilistic, language-driven environment. It’s not a flowchart. It’s a blueprint for intelligent behavior.
Step 5: Generate Instructions and Govern
From the left panel:
Use the AI icon to generate Agent details
Instructions: Your entire diagram is turned into a set of textual instructions for the Agent that can be pasted directly into the Agent Builder.
Test cases: The logic from your diagram is turned into separate
Use the User story generation feature to document scope for dev teams if actions (flows, apex, external callouts) need to be built for the Agent
Step 6: Iterate
As you pass the generated instructions onto the Agent Builder in Salesforce (or other platform), and start testing, you are likely to discover some situations and behaviours where Agent is not performing as expected.
Rather than trying to manually overwrite the instructions directly in your Agent Builder, go back to your agent instruction diagram and try to figure out at what point does it fail and correct your instruction diagram to account for that case. Then re-generate instructions from the diagram, pass them to Agent Builder and try again.
By treating your Agent Design Diagram as the ultimate source of truth you gain two advantages:
You can more easily pinpoint and correct a specific area of your instructions that needs to be corrected, rather than staring at the entire text.
Every time you change your instruction diagram, we automatically take a copy of the diagram and store the instructions from that time. Therefore if you decide that your Agent was working better N iterations ago, you can easily get back to previous version of your instructions.
Summary
With Agent Instruction diagrams, you gain clarity and control over how your AI behaves. You define what the agent should do, when, and under what conditions—backed by Agent design and prompt engineering best practices and logic validation. As part of a broader Agent Interaction Map or as a standalone job-to-be-done, this diagram type accelerates responsible and transparent AI adoption in Salesforce.