🤖 Agent Builder
📖 How to configure and manage agents with the Flourish Agent Builder.
Overview
The Agent Builder is a Lightning Web Component that provides a full interface for creating, configuring, and managing AI agents on the Flourish Agent Platform — all from within Salesforce.
The layout 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 creates the agent externally and assigns it a permanent Agent ID (UUID).
⚠️ 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. |
If you change the name or description, a Save button will appear inline. Identity changes are saved separately from the version config.
Versions
Once an agent is registered, you can manage multiple versions of its configuration. Versions allow you to 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 (e.g. 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.
Configuration Form
The configuration form is divided into the following sections.
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.
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 are run automatically when a new conversation begins — before the user types anything. Use this to greet users, set context, or fetch relevant data before the conversation starts.
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 will wait for the user to speak first.
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 | Run Code | Execute Python in a sandboxed environment |
| Core | Web Tools | Search and fetch content from the internet |
| Core | Consult Agent | Delegate tasks to a specialist advisor agent |
| 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 |
| Knowledge | Knowledge Base | AI search and RAG over uploaded knowledge files |
Credential Status
Each tool shows a small status indicator reflecting whether the required credentials are configured for your org and environment:
- 🟢 Green dot — credentials are configured and ready.
- 🔴 Red dot — one or more required credentials are missing.
Hover over the dot to see which credential keys need to be set up.
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 is used to evaluate input or output. The agent will block messages that fail the evaluation. |
| Agent | A dedicated safety agent (identified by its UUID) 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.
Datasets
Datasets provide the agent with data to reason over. Each dataset has a platform, a source, and a description that is passed to the LLM so it understands what the data contains.
| Field | Description |
|---|---|
| Platform | The data source platform (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 LLM. |
| 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:
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 (RAG). 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 50MB each. The Knowledge Base tool must be enabled for the agent to use them.
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 in the LLM prompt — useful for clarifying the advisor's role in context. |
| Enabled | Toggle to enable or disable without removing. |
The Consult Agent tool must be enabled for advisors to be used.
Required Packages
List any Python packages the agent's Run Code tool needs, one per line. These are installed in the agent's sandboxed execution environment.
scipy
matplotlib
pandas
Action Bar Utilities
The right side of the action bar provides several utility actions.
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.
Preview connects to the deployed version, not the draft you're editing. 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 configuration 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"
Changes made by the co-build assistant appear in the form immediately. Review them and click Save & Sync when ready.
Inspect
Opens a fly-in panel for inspecting real conversation history. Paste a Conversation ID (UUID) and click Load to view the full message history for that conversation, including assistant think steps, token usage, and latency.
The Inspect panel has two tabs:
- Messages — the full conversation turn-by-turn. Supports search with previous/next navigation.
- Chunks — the data chunks retrieved from trusted resources during the conversation, useful for debugging RAG behavior.
Import / Export
- Export copies the current version's configuration 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 external UUID to your clipboard. This is the ID used 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. |