Agent Builder
How to configure and manage agents with the Flourish Agent Builder.
Overview
The Agent Builder is where you create, configure, and manage AI agents on the Flourish Agent Platform, all from within Salesforce.
You start on a home screen of agent cards. Opening an agent shows an action bar across the top, a vertical list of tabs down the left, and the selected tab's settings in the main area. Preview, Co-build, Inspect, and Embed open as panels alongside it.
Agents Home
The home screen shows a card for every agent in your org, with a search box above the grid. Each card displays a status indicator:
| Indicator | Meaning |
|---|---|
| 🟢 Green dot | Agent is Synced with the Agent Platform |
| 🟡 Yellow dot | Agent is Local: created but not yet registered |
| ⚠️ Warning icon | Agent has a sync error: check the error banner |
A version badge (e.g. v3) appears on agents that have been registered and deployed. Click a card to open that agent; the breadcrumb at the top left returns you here.
Agent Tabs
Only one tab is visible at a time, so if you can't find a setting, check which tab you're on.
| Group | Tab | What's on it |
|---|---|---|
| Build | Basics | Name, description, nickname, chatbot title, and the Memory, Continuity, and Approach settings |
| Build | Instructions | Profile, Startup Instructions, Disclaimer |
| Build | Tools | What the agent can do |
| Build | Knowledge & Data | Trusted URLs, datasets, access grants, knowledge files, advisors |
| Build | Safety | Input and output screening |
| Manage | Sharing | Who has access to this agent |
| Manage | Advanced | Custom actions, secrets, integrations, Python packages |
The Build tabs configure the selected version. The Manage tabs apply to the agent as a whole, across every version.
Adding things: Every Add button opens a dialog with Cancel and a save button. Clicking a row in any list opens the same dialog to edit that entry.
Creating an Agent
Click + New Agent. A full-screen form asks for the agent's name, description, nickname, chatbot title, and its Memory and Approach settings, then Create Agent registers it on the Agent Platform and gives it a permanent Agent ID.
The agent does not exist until you click Create Agent. Cancelling leaves nothing behind.
Important: An agent must be registered before you can configure versions, tools, or trusted resources.
Basics
These fields apply to the agent across all versions.
| Field | Description |
|---|---|
| Agent Name | The internal name for this agent. Shown on the agents home. |
| Description | An optional internal description for your reference. |
| Agent Nickname | The name the agent uses to refer to itself in conversation (e.g. "Ava", "Coach"). |
| Chatbot Title | The title shown at the top of the chat interface when this agent is embedded. |
There is no separate Save button. These commit with Save & Sync, or with Create Agent the first time.
Memory and Continuity
Two settings sit side by side here, and they answer different questions. Memory is what the agent remembers. Continuity is where the next conversation starts. An agent can remember everything about someone and still open a fresh thread every time, and many should.
Memory
| Option | Meaning |
|---|---|
| No memory | The agent starts fresh every conversation and keeps nothing afterward. |
| Shared across everyone | One memory that every conversation adds to. What one person tells it, everyone gets. |
| Per person | Each person gets their own memory. Not available yet: it needs per-user access set up for your org first. |
Memory is set once, at creation. As soon as the agent has actually stored something, the setting locks and can't be changed, because what it already holds is filed under the setting that created it. To use a different one, create a new agent.
Two things worth knowing before you turn memory on:
- The agent can quote earlier conversations. When a new conversation starts, the previous one is filed away and stays searchable. That is the point of memory, and it will occasionally surprise someone who assumed each chat was sealed.
- Knowledge Base searches that material too, alongside the documents you uploaded.
Continuity
Available once Memory is set to something other than No memory. With no memory there is no earlier conversation to return to.
| Option | Meaning |
|---|---|
| Start fresh | Every conversation begins from scratch. Earlier ones are filed away and stay searchable. |
| Pick up where they left off | A returning person lands back in their last conversation, as long as it is recent enough. |
Choosing Pick up where they left off reveals a required Come back within field, in hours. It has to be between 1 and 720, which is 30 days. The bound is deliberate: without one, someone returning after three months would silently drop into three-month-old context.
Unlike Memory, Continuity never locks. Change it whenever.
Addressing a separate memory
An agent set to Shared across everyone does not have to keep one memory for the whole org. Whatever calls it can name a group, such as a class, an account, a case, or a household, and that name gets its own separate memory. Nothing is set up in advance: the same name always reaches the same memory, and a name you have never used simply starts one.
That name comes from whatever is calling the agent, not from this screen. On the Chatbot component it is the Group Key property; from a Flow it is the Group Key input on the Daemon action. A record ID or an account number is usually the right thing to pass.
Approach
Approach decides how much thinking the agent does before it answers.
| Option | Meaning |
|---|---|
| Fast | Quickest and cheapest. Good for short lookups and simple, well-defined answers. |
| Balanced | A middle setting. Handles multi-step work without the cost of the top tier. |
| Thorough | Most capable and most expensive. Best for complex reasoning and long tool chains. |
New agents start on Balanced. Agents built before this setting existed have no value stored and are still running on Thorough, which is what their dial shows. If one of those does something straightforward, such as answering from one document, looking up a record, or following a short script, moving it to Balanced or Fast is usually the easiest cost saving available.
This affects the agent's reasoning only. The reply the user reads is written by a separate model either way, so raising the setting does not make every response proportionally more expensive.
Versions
Once an agent is registered, you can manage multiple versions of its configuration. Versions let you iterate on a configuration without affecting what users currently experience.
Version Statuses
| Status | Description |
|---|---|
| Draft | Work in progress. Safe to edit and iterate. |
| Deployed | The active version that users experience. |
| Archived | No longer active. Kept for historical reference. |
Working With Versions
Use the Version picker in the action bar to switch between versions or select + New Version to start fresh from the current configuration.
Use the Status picker to change a version's status (for example, to promote a draft to deployed).
When you're ready to push changes, click Save & Sync. This writes the current form state to the Agent Platform and saves the Basics fields and local settings along with it.
Instructions
Profile
The Profile field is the agent's core system prompt. Use it to define the agent's purpose, personality, expertise, behavioral guidelines, and tone.
Example:
You are a helpful Salesforce admin assistant. Your goal is to help users understand their org configuration, resolve common issues, and learn best practices. Always be concise and cite specific Salesforce documentation where relevant.
Startup Instructions
Startup Instructions run automatically when a new conversation begins, before the user types anything. Use this to greet users, set context, or fetch relevant data up front.
Example:
Greet the user warmly. Ask what they need help with today. If a record ID is present in the context, look up the relevant account and briefly summarize it for the user.
Startup instructions are optional. If left blank, the agent waits for the user to speak first.
Disclaimer
An optional short disclaimer shown below the chat interface. Supports markdown-style links using [link text](url) syntax.
Example:
This agent may make mistakes. See our Privacy Policy.
Tools
Tools extend what the agent can do during a conversation. Toggle each tool on or off depending on your agent's purpose.
Available Tools
| Group | Tool | Description |
|---|---|---|
| Core | Code | Execute Python in a sandboxed environment |
| Core | AI-Enabled Code | Allow code and AI to work together (requires Code) |
| Core | Advisor Agents | Delegate tasks to a specialist advisor agent |
| Core | Web Tools | Search and fetch content from the internet |
| Salesforce | Salesforce Data | Look up and work with your Salesforce records: find, create, update, and delete data. Stays within the limits you set in Access Grants. |
| Salesforce | Salesforce System | Full, unrestricted access to your entire Salesforce org. Ignores Access Grants, so only turn this on for agents you completely trust. |
| Knowledge | Knowledge Base | Search and answer questions from the knowledge files you've uploaded. |
| Files | File Generation | Create files people can download (spreadsheets, images, slide decks, and more). |
| Files | File Upload | Let people attach files to their messages in the chat. Off by default. |
Note: Enabling AI-Enabled Code automatically enables Code as a prerequisite. Disabling Code automatically disables AI-Enabled Code.
Note: Salesforce Data and Salesforce System do their work through the Code tool, so turning either one on automatically turns on Code.
Choosing between Salesforce Data and Salesforce System: Use Salesforce Data for almost everything. It can read and change records, and it respects the per-object limits you set in Access Grants. Choose Salesforce System only when an agent genuinely needs to reach the whole org, for example an admin assistant that manages setup. Because it ignores Access Grants, enabling it asks you to confirm first.
Note: File Upload sits with the other capabilities but works differently underneath. It's a Salesforce-only chat setting rather than an Agent Platform tool, so it applies to the agent across every version rather than to the selected one. It saves with Save & Sync like everything else.
Safety
Safety controls let you screen the agent's inputs and outputs before they're processed or returned.
Safety Types
| Type | Description |
|---|---|
| None | No safety check applied. |
| Prompt | A custom prompt evaluates input or output. The agent blocks messages that fail the evaluation. |
| Agent | A dedicated safety agent (identified by its Agent ID) performs the evaluation. |
You can configure Input Safety (screens what the user sends) and Output Safety (screens what the agent returns) independently.
Knowledge & Data
The trusted resources on this tab are attached to a specific version and define what data and systems the agent can access during a conversation.
Note: Deleting a trusted resource requires confirmation. A browser dialog will ask you to confirm before the resource is removed.
Trusted URLs
Web pages you want the agent to be able to read. Add the address, describe what is on the page, and the agent can draw on it.
| Field | Description |
|---|---|
| URL | The full web address, starting with https://. Plain http:// is refused: the agent reads whatever comes back and acts on it, so the connection has to be one nobody can tamper with in transit. |
| Description | Plain-language description of what the page contains. This is shown directly to the agent. |
| Priority | 1-100. Higher priority sources are given precedence when several could answer. |
| Enabled | Toggle to enable or disable the URL without deleting it. |
Trusted URLs and Datasets are the same thing underneath: a trusted URL is a dataset whose platform is Web. They are separate sections because adding a web page and writing a data query are different jobs. If you have used this builder before, any web dataset you added previously now appears here instead of under Datasets. Nothing moved on the platform, and nothing needs re-saving.
Datasets
Datasets provide the agent with data to reason over. Each dataset has a platform, a source, and a description that tells the agent what the data contains. For web addresses, use Trusted URLs above.
| Field | Description |
|---|---|
| Platform | The data source (Salesforce, Box, Cloudflare, Google Maps). Web addresses go under Trusted URLs instead. |
| Source | A SOQL query or file path, depending on the platform. |
| Description | Plain-language description of the data. This is shown directly to the agent. |
| Priority | 1-100. Higher priority datasets are given precedence when multiple sources are available. |
| Env Override | Pin this resource to a specific environment. Leave blank to inherit the session environment. |
| Enabled | Toggle to enable or disable the dataset without deleting it. |
Example: Salesforce dataset
| Field | Value |
|---|---|
| Platform | Salesforce |
| Source | SELECT Id, Name, Type, AnnualRevenue FROM Account WHERE OwnerId = '{{{_RECORDID}}}' |
| Description | Accounts owned by the current user, including revenue and type |
| Priority | 80 |
Access Grants
Access grants control what the agent is permitted to do on a given platform. An agent with the Salesforce Data tool enabled still needs an access grant to determine which objects it can look up, create, update, or delete.
Note: Access grants apply to the Salesforce Data tool. They do not limit Salesforce System, which always has full access to the entire org. If an agent has both Salesforce System and access grants turned on, the builder shows a banner reminding you that the grants no longer apply.
| Field | Description |
|---|---|
| Platform | The platform to grant access on. |
| Scope | The objects or resources in scope, e.g. Contact, Account or * for all. |
| Permissions | A combination of read, create, update, and delete. |
| Env Override | Pin to a specific environment, or leave blank for the session default. |
| Enabled | Toggle to enable or disable without deleting. |
Knowledge Files
Knowledge files are uploaded documents the agent can read. Supported formats include PDF, Word, Excel, plain text, Markdown, HTML, and common image types.
Uploading a file and making it searchable are two different things. Building a searchable index costs money and, for a spreadsheet, buys nothing a search could use. So documents and code are indexed automatically, while spreadsheets, data files and images are stored without an index. That is a normal, finished state, not a failure.
| Status | Meaning |
|---|---|
| Stored | The file is uploaded and usable. The agent's Code tool can read it by filename, but a search will not find it. Normal for spreadsheets, data files and images. |
| Indexing... | A searchable index is being built. |
| Searchable | The agent can find this file by searching. |
| Not searchable | Indexing finished but produced nothing to search. Rebuild it. |
| Error | The index build failed. Hover the badge for the reason. |
Each row offers the one thing its status allows: Make searchable on a stored file, Stop indexing on a searchable one, and Retry on a failed build. Making a file searchable asks for confirmation first, because that is the direction that costs money.
If a file will only ever be read by the Code tool, which is how a large spreadsheet should be used, leave it Stored. Indexing it does not help.
Files are limited to 50 MB each. The Knowledge Base tool must be enabled before searching works at all.
Deleting removes the file from this version, not from the agent. Another version still using it keeps working, and the document is erased once no version references it. That is what makes versions usable as experiments. A spinner appears on the row while the deletion is in progress.
Advisors
Advisors allow your agent to consult other registered agents as specialist sub-agents during a conversation. This is useful for routing complex questions to domain experts without building a single monolithic agent.
| Field | Description |
|---|---|
| Agent | The advisor agent to consult (selected from registered agents in your org). |
| Description Override | Optional. Overrides the advisor agent's own description, which is useful for clarifying the advisor's role in context. |
| Additional Instructions | Optional. Extra instructions prepended to the advisor's own prompt when consulted. Write in second person addressing the specialist, e.g. "Only answer from your uploaded documents." |
| Enabled | Toggle to enable or disable without removing. |
The Advisor Agents tool must be enabled for advisors to be used.
Sharing
The Sharing tab lists everyone with access to this agent. (The Share button in the action bar jumps straight here.) Click Add people / agents to grant access, or the ✕ on a row to revoke it.
A grant pairs a grantee with a role:
| Grantee | Meaning |
|---|---|
| Person | A specific Salesforce user. |
| Team / Org | Everyone in an org. Defaults to your own. |
| Everyone | Public access. |
| Another Agent | Lets that agent consult this one. |
| Role | Meaning |
|---|---|
| Owner | Full control, including sharing and deletion. |
| Editor | Can change the agent's configuration. |
| User | Can chat with the agent. |
| Viewer | Can see the agent but not change it. |
| Advisor | Consult-only. The only role an agent grantee can have. |
Two rules the builder enforces: another agent can only be given Advisor, and you cannot revoke the last owner.
Advisors take two steps. For agent X to consult agent Y, Y must grant X the Advisor role here, and X must list Y under Knowledge & Data › Advisors. Setting up only one side won't work.
Advanced
Advanced settings for developers building integrations.
Custom Actions
Custom Actions define structured commands your agent can send to the host application during conversations. Each action becomes a tool the agent can call, and the host receives typed events it can handle programmatically.
| Field | Description |
|---|---|
| Action Type | A lowercase identifier (letters, digits, underscores). For example: search, navigate, filter_by_type. |
| Description | Required. Tells the agent when to use this action. This text is shown to the model in its tool catalog. |
| Properties | Optional parameter definitions. Each property has a Name, Type (string, integer, number, boolean, or array), Description, and a Required checkbox. |
| Enabled | Toggle to enable or disable the action without deleting it. |
Actions are stored locally until you click Save & Sync, which pushes them to the Agent Platform.
Receiving an action is developer work: the chatbot delivers it to the host page as an agentaction event, or as a postMessage when embedded in an iframe. See Handling Agent Actions in the Chatbot documentation.
Secrets
Secrets are environment variables injected into the agent's run_code scripts at runtime. Values are encrypted at rest and never displayed after saving.
| Field | Description |
|---|---|
| Environment Variable | The variable name, using uppercase letters and underscores (e.g. SFDC_ACCESS_TOKEN). |
| Secret Value | Write-only. The encrypted value is never shown after saving. The form shows a lock icon and dots instead. |
| Description | What this secret is for. |
| Enabled | Toggle to enable or disable without deleting. |
Secrets are managed directly on the server (not batched like Custom Actions). Creating, updating, or deleting a secret takes effect immediately.
Python Packages
If the agent's Code tool needs specific Python packages, list them here, one per line. These are made available whenever the agent runs code.
Example:
scipy
matplotlib
pandas
Action Bar
The right side of the action bar provides several utilities.
Preview
Opens a fly-in chat panel connected to the agent's currently deployed version. Use this to test how the agent responds to real user input.
The panel header shows the current Conversation ID once a session is established. Two buttons appear next to it:
- 🔍 Inspect: switches to the Inspect panel with that conversation pre-loaded, so you can see the full message history, token usage, and reasoning steps.
- 🔄 New conversation: clears the current conversation and starts fresh. Without this, the preview resumes the previous conversation when you re-open the panel.
The conversation is automatically cleared when you switch to a different agent or version.
Note: Preview connects to the deployed version, not the draft you're editing. Click Save & Sync first if you want to test recent changes.
Co-build
Opens a fly-in panel with a built-in AI assistant that can help you configure the agent. The co-build assistant has context about the agent you're editing (its current prompt, tools, resources, and recent changes) and can make changes directly on your behalf. For example:
- "Write a professional system prompt for a contract review assistant"
- "Enable Salesforce Data and add a read grant for Contact and Opportunity"
- "Add a dataset for all open cases owned by the current user"
- "Add a crack_joke action with an optional topic property"
Changes made by the co-build assistant appear in the form immediately. Review them and click Save & Sync when ready.
The co-build panel also shows a Conversation ID in the header with the same inspect and new-conversation controls as the Preview panel.
Inspect
Opens a fly-in panel for inspecting real conversation history. Paste a Conversation ID and click Load to view the full message history for that conversation, including assistant reasoning steps, token usage, and latency.
The Inspect panel has two tabs:
- Messages: the full conversation turn-by-turn, with search and previous/next navigation.
- Chunks: the data chunks retrieved from trusted resources during the conversation. Useful for debugging how the agent found the information it used.
Tip: The fastest way to inspect a conversation is to use the 🔍 Inspect button in the Preview or Co-build panel header. It switches to Inspect with the conversation already loaded.
Embed
Opens a modal for generating an HTML embed snippet that lets you put the chatbot on any external website. See Embedding on External Websites in the Chatbot documentation for full details.
The Embed button appears only for registered agents when the embed site URL is configured in your org's FL_Intelligence__mdt settings.
Two embed modes are available:
- Bubble: a floating chat button in the corner of the page that expands into a chat panel. You can customize the button color.
- Inline: an iframe embedded directly in the page flow that auto-resizes to fit its content.
A Test mode toggle adds a data-test flag to the snippet: the chatbot stays hidden on the live site until someone visits with ?testflchatbot=1 in the URL, so you can validate the embed in production before launching it for everyone.
The generated snippet is a single script tag pointing at the centrally hosted embed script, so fixes reach embedded sites without re-pasting. Click Copy to Clipboard to copy the snippet, then paste it into your website's HTML.
Import / Export
- Export copies the current version's configuration as JSON to your clipboard.
- Import opens a modal where you can paste a JSON config to overwrite the current form fields. The agent's Name and Agent ID are never overwritten by an import.
Force Pull
Re-fetches the agent's latest state from the Agent Platform and reloads the version list. Use this if the sync status looks stale or if another user has made changes.
Copy Agent ID
Copies the agent's Agent ID to your clipboard. You'll need this ID to embed the agent in the Chatbot component or reference it from other systems.
Sync Status Badge
The badge in the action bar reflects the agent's current sync state:
| Badge | Meaning |
|---|---|
| Local | The agent exists only in Salesforce, not yet registered. |
| Synced | The agent and its deployed version match the Agent Platform. |
| Pending Sync | Local changes have been made that haven't been pushed yet. |
Typical Setup Flow
- Click + New Agent, fill in the name and description, choose the Memory setting (it locks once the agent stores anything), and pick an Approach.
- Click Create Agent. The Agent Platform assigns a permanent ID.
- Select a version (create a new one or use the existing draft).
- On Instructions, write the Profile and Startup Instructions.
- On Tools, enable what the agent needs (including File Upload if people should be able to attach files).
- On Safety, configure the screening rules.
- On Knowledge & Data, add datasets, access grants, knowledge files, and advisors.
- Optionally, on Advanced, configure custom actions, secrets, integrations, and Python packages.
- Click Save & Sync.
- Set the version status to Deployed. The agent is now live.
- On Sharing, grant access to the people, teams, or agents that need it.
- Use the Preview panel to test, the Inspect panel to debug, and create new versions to iterate.
- Use Embed to put the chatbot on an external website if needed.