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 your org has on the Agent Platform, with a search box above the grid. The search box and the New Agent button stay in place while the grid scrolls.
The list comes from the Agent Platform rather than from Salesforce records, so it shows every agent your org owns however it was made, including ones set up by someone else and ones created outside the builder. Each card displays a status indicator:
| Indicator | Meaning |
|---|---|
| 🟢 Green dot | The agent has a deployed version and is live |
| 🟡 Yellow dot | Registered, but nothing deployed yet. Nobody can reach it until you deploy a version. |
| ⚠️ Warning icon | The last save from this org failed to sync. Open the agent and check the error banner. |
A version badge (e.g. v3) shows the agent's active version. Click a card to open that agent; the breadcrumb at the top left returns you here.
Agents are listed by name. You can open an agent from a link that names it, and the link keeps working whichever form of the ID it carries.
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, interface language, 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 | Cost | What this agent is allowed to spend in a month |
| Manage | Sharing | Who has access to this agent |
| Manage | Advanced | Custom actions, secrets, integrations, Python packages, and the runtime tools including Desktop Control |
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. Canceling 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. |
| Interface Language | The language for the chat window's own buttons and labels: Send, Restart, the composer prompt, the connection notices. Defaults to English (US). It does not change the language the agent replies in; that comes from the agent's instructions. A page that embeds this agent can override it for its own visitors, so set it to whatever most people using the agent should see. |
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, and nobody sees anyone else's. Every person has to enter their own access 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.
Choosing Per person adds a note, because it needs something of every person who uses the agent. The agent has no way to tell one person from another unless that person has entered their own Agent Platform access. Until they do, their conversations with the agent are refused rather than quietly shared with everyone else's. See Per person access below.
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.
Per person access
An agent set to Per person has to know who it is talking to, and a Salesforce login is not enough on its own. Each person enters their own Agent Platform user name and token once, and from then on every agent they open keeps a memory that is theirs.
Place the My Access component where your people will find it. In the Lightning App Builder or the Experience Builder, drag Flourish Agent Platform: My Access onto a home page, a record page, an app page, or the utility bar. A home page is usually the right answer.
| Property | Description |
|---|---|
| Title | The heading on the card. Name it after whatever your people call the assistant. Defaults to AI Assistant Access. |
| Help Text | Optional. Replaces the explanation above the fields, for organizations that hand these out in their own words. |
What the person does: type their Agent Platform user name, paste their Agent Platform token, and click Save. A dot above the fields reads Not connected yet or Connected.
- The token is never shown again. Once saved, the field says a token is stored and offers to replace it. It is stored encrypted, and nothing anywhere hands it back, including to an administrator.
- It only ever edits your own access. Putting the component on a User record page does not let an admin fill it in for someone else; whoever is looking at it edits their own.
- It does not work for a public site visitor. A public Experience site presents one guest for everybody, so there is no person to be. The component says so instead of showing a form that cannot work.
- Remove clears both, after asking. That person's conversations go back to the shared memory, and on a Per person agent they stop working.
The user names and tokens come from Flourish. Ask your Flourish contact to provision one per person who needs it.
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 |
|---|---|---|
| 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. |
| Knowledge | Web Tools | Search the internet, and read Trusted URLs and other web pages. |
| 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. |
| Files | Image Reading | Let the agent look at images people send. It opens an image only when it has a reason to, so uploads cost nothing until it does. |
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. While Salesforce System is on, Salesforce Data is marked as superseded, since it adds nothing.
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.
Tools on the Advanced tab
Four more tools live on Advanced rather than here. Three of them are turned on for you by the thing that needs them: add a knowledge file, a Trusted URL or an advisor and the tool that reads it comes on. You can still set them yourself.
| Group | Tool | Description |
|---|---|---|
| Runtime | Code | Generate and run code as needed. Turned on automatically by the capabilities that need it. |
| Runtime | AI-Enabled Code | Allow code to run AI. Requires Code. |
| Runtime | Consult Agent | Delegate to a specialist agent. Turned on automatically when you add an advisor. |
| Desktop | Desktop Control | Let the agent work on a Windows computer running the Flourish operator app. Off on new agents, and nothing turns it on for you. |
Note: Enabling AI-Enabled Code automatically enables Code as a prerequisite. Disabling Code automatically disables AI-Enabled Code.
Desktop Control
This one is different from everything else in the grid, and it is worth reading before you switch it on.
It reaches outside Salesforce. Every other tool works on your org, your documents or the web. This one works a real computer at a real desk, and what it can reach there is whatever the person sitting at that desk can reach.
You are not the one who decides what it may do. Turning it on does not give the agent a computer. Someone at the machine has to start a session, and the machine itself holds the list of what is allowed: which applications, which folders, whether the agent may drive at all. That list is set on the computer, and the agent can neither read nor change it. If nobody has started a session, the agent says so rather than doing anything.
It needs a model key. Desktop Control only works on agents running on an Anthropic model key. Add a secret named _BYOM_KEY_ANTHROPIC or _BYOM_KEY_INTERNAL on the Secrets tab first. Without one the agent refuses every attempt and explains why in the chat. The builder shows a reminder on Advanced whenever Desktop Control is on.
Setting up the computer is a separate job. The machine needs the operator app installed and enrolled against your org. That is not done from the builder; ask whoever set up your Flourish account.
A note on prompt injection. An agent reads a lot of text it did not write: web pages, documents, messages from the people it talks to. With Desktop Control on, instructions hidden in any of that reach a real computer for the first time. The machine's own rules are what stops them, which is why those rules live on the machine and not here. Give this to agents whose sources you trust.
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, Title, Email FROM Contact WHERE AccountId = [the Account's Id] |
| Description | Contacts at the Account the user is viewing. The Account's Id is sfdc_record_id in the host context. |
| Priority | 80 |
The agent reads a source as a description of what to fetch and writes the query itself, so a value from the page is named in words, as here. Nothing substitutes it into the source.
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. See below for choosing one outside 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 Consult Agent tool must be enabled for advisors to be used. Adding an advisor turns it on for you.
Choosing the advisor. The Agent dropdown lists the other agents registered in your Salesforce org. An advisor does not have to be one of them, so the list ends with An agent outside this org (enter its ID), which reveals a box for the agent's Agent ID. Whoever manages that agent can get it with Copy Agent ID in their action bar.
Either way, the other side has to agree. Listing an agent here says you want to consult it. It does not give you permission. The agent being consulted must also share itself with this one at Consult Only, on its own Sharing tab. Set up only this half and the consultation is refused while the conversation is running, with nothing on this screen to explain why. That matters most for an agent outside your org, since you cannot set the other half yourself.
Cost
The Cost tab bounds what this one agent may spend on AI in a calendar month. It appears once the agent is registered, because the limit lives with the agent on the Agent Platform.
Monthly limit in US dollars takes a whole number up to 5,000.
| What you enter | What it means |
|---|---|
| Blank | No limit of its own. The agent is bounded only by your organization's monthly cap. |
0 | This agent spends nothing at all. A deliberate off switch, not the same as blank. |
| A number | This agent stops at that amount for the month |
Blank is the one worth thinking about. An agent with no limit of its own can spend your organization's whole monthly cap, and reaching that stops every other agent, chatbot and scheduled task in the org until the 1st. One agent nobody bounded can take everything else down with it.
So set a limit before you publish anything the public can reach: a chatbot embedded on your website, or a web app on a public page. An agent only staff can reach is less exposed, but a runaway loop costs the same either way.
A per-agent limit can only tighten what the organization's cap already allows. It cannot raise it.
Limits reset at the start of each month, UTC.
Sharing
The Sharing tab lists everyone with access to this agent. (The Share button in the action bar jumps straight here.) Click Add sharing grantee to grant access, the pencil on a row to change one, or the ✕ to revoke it.
A grant pairs a grantee with a role:
| Grantee | Meaning |
|---|---|
| Org | Everyone in another organization. |
| User | One named person outside your org. |
| Agent | Lets that agent consult this one. Named by its Agent ID. |
| Everyone | Public access. |
| Role | Meaning |
|---|---|
| Full Control | Everything, including sharing and deletion. |
| Edit & Run | Can change the agent's configuration and use it. |
| Run Only | Can chat with the agent. |
| View Only | Can see the agent but not change or use it. |
| Consult Only | Can be consulted by another agent. Only an agent grantee has it, and it is the only level an agent grantee can have. |
Roles are named for what they allow rather than for who holds them, because the two are independent: an Org grantee can be Run Only, and a User grantee can have Full Control.
Two rules the builder enforces: an agent grantee can only be Consult Only, and you cannot revoke the last Full Control entry.
A third is the Agent Platform's: the entry naming the agent's owner cannot be revoked. That is the Full Control row written when the agent was created. Ownership is recorded on the agent itself, so removing the row would take nobody's access away; the platform refuses it instead, and the builder shows the refusal as an error when you try.
Changing an entry
The pencil on a row reopens it with everything filled in. Saving replaces the entry: the new access is granted first and the old one removed afterwards, so a problem partway through leaves the original access working rather than nobody with access. If the old entry cannot be removed you are told so, and both stay in the list until you revoke the stale one.
Changing who an entry is for works on any row, including the last Full Control one. Changing the role of that last one does not: add a second Full Control entry first. Otherwise you would be removing the only person who can administer the agent.
Switching the Who dropdown clears the id field, since an id for one kind of grantee is not valid for another.
Editing a row takes its share keys with it. Because the edit replaces the entry rather than altering it, any key created from that row stops working, and nothing warns you first. The row looks unchanged afterwards while every credential issued from it has stopped. If the row has keys, tell whoever holds them before you edit it, and mint replacements after.
Sharing with an agent
An agent is named by its Agent ID, not picked from a list. Whoever manages that agent can get the ID with Copy Agent ID in their action bar, and you need the org that owns it as well.
There is no dropdown here on purpose. The agents your own org registered are the ones that least need a grant, since they already reach this agent through your org's own access, so a list of them would offer the answers that do not matter while giving you no way to type the one that does.
This is one half of a pair. Granting an agent access here lets it consult this one. The other agent still has to list this one under its own Knowledge & Data > Advisors. Do only this half and nothing happens.
The Org field
Everyone in your own Salesforce org can already use every agent your org created. You do not need to share an agent with your own colleagues, and adding them here does nothing. Sharing is for reaching outside your org.
So the Org field means different things depending on who you are sharing with:
| Sharing with | Org field |
|---|---|
| Org | Required. The organization whose members should get access. |
| User | Optional. Fill it in when they belong to another organization on the Agent Platform. Leave it blank to share with someone who has no organization of their own; they are matched by the name they sign in with. |
| Agent | Required. The organization that owns the other agent. |
| Everyone | Not used. |
Nothing is filled in for you.
One thing to get right. If you are naming a person in another organization, fill in both their user id and their org. An id on its own is read as somebody with no organization, so a grant made that way looks correct in the list and never actually lets them in.
Share Keys
A share key lets another system run this agent without a Salesforce login: a partner's website, an internal service, anything with a server of its own. The key says which agent may run and at what level; everything else about the conversation still belongs to whoever presents it.
Keys live at the bottom of the Sharing tab. Create one with the key button on a sharing row. The key inherits that row's access, so the row decides what the key can do.
Not every row can have one
Two rules decide it, and the key button is grayed out when either is in the way. Hovering it tells you which.
The row has to be shared with an Org. A key acts as the organization it was shared with, so a row naming one person, one agent, or everyone has no organization for it to act as.
The role has to carry no administrative power. A key is something you hand to somebody else, so it cannot be one that could edit the agent, read its secrets or mint more keys: that is not a narrower credential than your own, it is a broader one with a smaller name. Today that means Run Only and View Only can back a key and Full Control and Edit & Run cannot.
Between them the two rules leave an Org row at Run Only or View Only as the only kind that can have a key, which is why the button is grayed on most of the list. A Consult Only row never qualifies: that level belongs only to an agent grantee, and an agent grantee has no organization.
That second rule is worked out from what the role can do rather than from a list of role names, so a role added later that carries administrative power is shut out without anyone having to remember. The button asks the Agent Platform rather than deciding for itself, which is why the reason it gives you is the real one.
The key is shown once
When you create a key, the secret appears in the dialog. That is the only time it exists anywhere you can read it. It is not stored in a recoverable form and cannot be shown again. Copy it before you close the dialog. If you lose it, revoke the key and create another; nothing else is affected.
Never put a key in a web page. It belongs on a server. Whatever holds it uses it to start a conversation and passes the page only the short-lived token it gets back. A key in page source is a long-lived credential any visitor can take.
Managing keys
Each key shows what it is for, which sharing entry it came from, when it was last used, and when it expires.
| Status | Meaning |
|---|---|
| Active | Working now. |
| Expired | Past its expiry date. Kept in the list for the record. |
| Revoked | Turned off deliberately. Kept in the list for the record. |
Set an expiry date when you create a key, or leave it blank for one that does not expire. A key expires at the end of the day you choose.
Revoking a key is not unsharing. The ✕ on a key stops that key working immediately and changes nothing else: the sharing entry stays, and any other key on it keeps working. Revoking the sharing entry instead removes the access altogether, and its keys along with it.
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.
Names beginning with FLOURISH_ are reserved for the platform's own script variables and are refused. DATABASE_URL is not reserved, so it is free for a database of your own.
Integrations
An integration is an OAuth connection the agent's code can use: a Salesforce org other than this one, or another service the Agent Platform supports. Unlike everything else on this tab, an integration belongs to the agent rather than to a version, so connecting one needs no new version and a rollback does not undo it.
Add Integration works once the agent is registered. Before that it tells you to register first.
| Field | Description |
|---|---|
| Provider | Which service to connect to. |
| Label | Optional. Your name for the connection, such as Production CRM, so a list of several is readable. |
| Env Prefix | Decides the environment variable names the agent's scripts see. The form previews them as you type: a prefix of SFDC gives SFDC_ACCESS_TOKEN and SFDC_INSTANCE_URL. |
Click Connect and you are sent to the provider to sign in and approve. The row then lists the date it connected. A connection that has lapsed shows a Reconnect button, and the delete button disconnects it.
Using your own OAuth app is optional. Leave Client ID and Client Secret blank and the connection uses the Flourish-managed app, which is the normal path. To use your own, create an External Client App in your Salesforce org with the callback URL the form shows, then paste its credentials in. A connection using your own app is marked Custom App, and reconnecting it asks for the credentials again.
With your own credentials, Login URL (My Domain) is required. It is the My Domain address of the org where your External Client App is defined, such as
https://yourorg.my.salesforce.com, with nothing after it. Consent and the token exchange happen there, not atlogin.salesforce.com.
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 panel for trying the agent out. What opens depends on the version you have selected:
- A chat panel, for an agent people reach by typing. Use it to test how the agent responds to real user input.
- The agent's own page, for a version that carries a web app. It opens in the same sandbox a visitor gets, and a picker appears at the top if the version carries more than one.
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. On a web app it reads Restart preview and reloads the page on a fresh conversation.
The conversation is automatically cleared when you switch to a different agent or version.
The panel is resizable: drag its left edge, or focus the edge and use the arrow keys. Double-click the edge to go back to the default width. A web app opens wider than a chat and each remembers its own width, so widening one does not widen the other.
Note: Preview connects to the deployed version, not the draft you're editing. Click Save & Sync first if you want to test recent changes. A web app preview is the exception in one direction: the page comes from the version you are editing, while the agent answering it is still the deployed one. The panel says so under the frame.
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 for registered agents your org owns.
Open to the public first. A website's visitors are not signed in, so the agent has to be open to the public: anyone on a page carrying the snippet can then chat with it, each as an anonymous visitor who can reach this agent and nothing else. Their chats count against a monthly limit for the agent, which the Agent Platform requires before it opens. The modal asks for that limit and opens the agent in one step, and Close to the public in the same place turns it off. The limit is the one on the Cost tab.
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, where you paste the tag. It keeps a fixed height rather than growing with the conversation; set it with
data-heightanddata-max-width.
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. See Test mode.
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 Snippet to copy it, then paste it into your website's HTML.
This modal generates chatbot snippets. To put an agent's web app on a website instead, write the tag yourself from On your own website.
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.