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.
The screen is divided into three areas:
- Left panel — your list of agents, with sync status indicators and a "New Agent" button.
- Main area — the configuration form for the selected agent.
- Fly-in panel — contextual side panels for Preview, Co-build, and Inspect modes (opens alongside the main area).
Agents List
The left panel shows all agents in your org. Each agent 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 next to agents that have been registered and deployed.
Creating an Agent
Click New Agent to create a new agent record. A new entry is added to the left panel with a Local sync status.
Fill in the identity fields and click Register Agent to push the agent to the Agent Platform for the first time. Registration saves your identity fields, any chat experience settings, and creates the agent externally with a permanent Agent ID.
Important: An agent must be registered before you can configure versions, tools, or trusted resources.
Identity Fields
These fields appear at the top of the main area and apply to the agent across all versions.
| Field | Description |
|---|---|
| Agent Name | The internal name for this agent. Used in the agents list. |
| 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. |
For registered agents, a Save button appears inline when you change the name or description. Identity changes are saved separately from the version configuration. For unregistered agents, identity changes are saved automatically when you click Register Agent.
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 — what 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 any chat experience settings.
Configuration Form
The configuration form is divided into collapsible sections. Click any section header to expand or collapse it. All sections are expanded by default except Developer Tools, which starts collapsed.
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
| Section | 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 | Read and write Salesforce records (CRUD) |
| Salesforce | Salesforce Schema | Inspect object models and field configuration |
| Salesforce | Salesforce Admin | Work with flows, layouts, permissions, Apex, and packages |
| Documents | Knowledge Base | AI search over uploaded knowledge files |
| Documents | File Generation | Generate downloadable files (CSV, SVG, PPTX, etc.) from scripts |
Note: Enabling AI-Enabled Code automatically enables Code as a prerequisite. Disabling Code automatically disables AI-Enabled Code.
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.
Trusted Resources
Trusted resources 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.
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.
| Field | Description |
|---|---|
| Platform | The data source (Salesforce, Box, Web, Cloudflare, Google Maps). |
| Source | A SOQL query, URL, 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 read, create, update, or delete.
| 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 that the agent can search using AI. Supported formats include PDF, Word, Excel, plain text, Markdown, HTML, and common image types.
Files go through an ingestion process after upload:
| Status | Meaning |
|---|---|
| Processing… | The file is being parsed and indexed. |
| Ready | Indexed and available for the agent to search. |
| Error | Ingestion failed — try re-uploading. |
Files are limited to 50 MB each. The Knowledge Base tool must be enabled for the agent to use them.
Deleting a knowledge file is permanent and requires confirmation. 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 — 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.
Chat Experience
The Chat Experience section controls client-side UI features in the chatbot. Unlike the version-specific settings above, these apply to the agent across all versions and are stored locally in Salesforce (they are not sent to the Agent Platform).
Chat experience settings are saved when you click Save & Sync or Register Agent.
| Setting | Description |
|---|---|
| Allow user to upload files | When enabled, users see a file attachment button in the chat input. Files are uploaded to the conversation and available to the agent via run_code scripts. Off by default. |
Developer Tools
The Developer Tools section is collapsed by default and contains 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.
On the chatbot side, actions are delivered to the host page as agentaction custom events. 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 🔍 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.
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 and fill in the name and description.
- Click Register Agent — the Agent Platform assigns a permanent ID.
- Select a version (create a new one or use the existing draft).
- Write the Profile and Startup Instructions.
- Enable the Tools the agent needs.
- Configure Safety rules.
- Add Trusted Resources (datasets, access grants, knowledge files, advisors).
- Set Chat Experience options (e.g. enable file uploads).
- Optionally configure Developer Tools (custom actions, secrets, Python packages).
- Click Save & Sync.
- Set the version status to Deployed — the agent is now live.
- 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.