Agents Homepage Selection

Allow users to select an agent directly from the homepage

Homepage Agent Selection

The agents homepage selection panel allows users to select an agent directly from the homepage before starting a conversation. This provides an intuitive way to guide users to the right agent for their needs.

Overview

When enabled, this feature displays a grid of available agents on the homepage, allowing users to:

• Browse available agents with their icons and names
• Select an agent by clicking on it
• Start typing their message with the selected agent pre-configured

Prerequisites

System Requirements

• AGO platform deployed and accessible
• Admin access to configure settings

Configuration Required

• At least one active agent configured
• Agent display order configured (optional)

---

Configuration

Via Admin Interface

1. Navigate to Settings → Widget Configuration
2. Enable Display Agents Selection Panel
3. Configure the heading text (e.g., “How can we help you today?”)
4. Set agent display order (optional)
5. Click Save

Configuration Fields

Field	Type	Default	Description
display_agents_selection_panel	boolean	false	Enable/disable the panel on the homepage
display_agents_panel_in_chat	boolean	false	Enable/disable the panel in the chat when no agent is selected
text_agents_home_page	text	”Our agents”	Heading text above the grid

---

Agent Display Order

Control which agents appear and in what order:

Setting Agent Order

To set the display order for agents:

1. Navigate to AI Studio → Agents
2. Use drag-and-drop to reorder agents in the list, or
3. Edit each agent and set the Order field (lower numbers appear first)
4. Click Save

Order Logic

Order Value	Behavior
Lower numbers	Appear first
null	Appear after ordered agents
Same number	Alphabetical by name

---

Permission-Based Display

The agents panel respects user permissions:

How It Works

Anonymous vs Authenticated Users

User Type	Agents Shown
Anonymous (no JWT)	Agents linked to widget_default_permissions
Authenticated (JWT)	Agents linked to user’s permissions
Admin	All active agents

Configuring Default Permissions

1. Navigate to Settings → Widget Configuration
2. Set Default Permissions for anonymous users
3. Set Logged-in Default Permissions for authenticated users
4. Click Save

---

When the Panel is Displayed

The agents selection panel can appear in two locations, each controlled by a separate setting:

Homepage Panel

Controlled by display_agents_selection_panel. Shown when:

1. display_agents_selection_panel is set to true
2. AND no conversation has started yet (homepage view)
3. AND user has access to multiple agents

Homepage Panel Visible = display_agents_selection_panel
                         AND no_conversation_history
                         AND user_has_multiple_agents

Chat Panel

Controlled by display_agents_panel_in_chat. Shown when:

1. display_agents_panel_in_chat is set to true
2. AND no agent has been selected yet in the current session
3. AND no message is currently loading
4. AND user has access to multiple agents

Chat Panel Visible = display_agents_panel_in_chat
                     AND no_agent_selected
                     AND not_loading
                     AND user_has_multiple_agents

Note: If the user only has access to one agent, that agent is auto-selected.

---

User Experience

1. Homepage Display

When users visit the homepage, they see a grid of available agents below the main title:

Layout:

• Title: “How can we help you today?”
• Agent Grid: Cards showing available agents (Support Agent, Analytics Agent, Billing Agent, etc.)
• Message Input: Text field to type messages

Each agent card displays:

• Agent icon/avatar
• Agent name
• Agent description (if configured)

2. Agent Selection

Clicking on an agent card:

• Highlights the selected agent
• Pre-fills the agent in the message input
• Focuses the input field for immediate typing

3. Visual Feedback

• Selected agents show a highlighted border
• Agent name appears as a mention in the input
• Smooth transition animations

4. Smooth Transition

Users can immediately start typing their message after selecting an agent.

---

Agent Card Display

Card Contents

Element	Source	Fallback
Icon	agent.icon (emoji) or agent.custom_icon	Default robot icon
Name	agent.display_name	agent.name
Description	(Optional) Agent description	None

Customizing Agent Appearance

1. Navigate to AI Studio → Agents
2. Select the agent to customize
3. Configure appearance settings:
   • Display Name: User-facing name (e.g., “Customer Support”)
   • Icon: Select an emoji icon
   • Order: Display position (lower numbers first)
4. Click Save

Using Custom Icons

1. Navigate to the agent settings
2. Click Upload Custom Icon
3. Select an image file (PNG, JPG, or SVG)
4. Click Save to apply the custom icon

---

Responsive Design

The agents panel adapts to different screen sizes:

Screen Size	Grid Columns
Mobile (less than 640px)	1-2 columns
Tablet (640-1024px)	2-3 columns
Desktop (more than 1024px)	3-4 columns

---

Best Practices

Agent Organization

• Limit visible agents: Show 3-6 most relevant agents
• Clear naming: Use descriptive display names
• Distinct icons: Help users differentiate agents visually
• Logical ordering: Place most-used agents first

Heading Text

• Be welcoming: “How can we help?” is better than “Select an agent”
• Be clear: Users should understand what the options mean
• Keep it short: One line works best

Permission Setup

• Group by use case: Create permissions for different user types
• Default wisely: Anonymous users should see general-purpose agents
• Test thoroughly: Verify correct agents appear for each permission

---

Troubleshooting

Issue: Panel not appearing

Problem: Agents selection panel doesn’t show on homepage or in chat.

Solutions:

1. For the homepage panel: verify display_agents_selection_panel: true in config
2. For the chat panel: verify display_agents_panel_in_chat: true in config
3. Check user has access to multiple agents
4. Verify at least one agent is active
5. Clear browser cache

Issue: Wrong agents displayed

Problem: Users see agents they shouldn’t access.

Solutions:

1. Review permission configurations
2. Check widget_default_permissions setting
3. Verify access control rules
4. Test with user impersonation

Issue: Agent order incorrect

Problem: Agents appear in wrong order.

Solutions:

1. Verify order field is set on each agent
2. Use bulk update to set all orders at once
3. Check for duplicate order values

Issue: Icons not loading

Problem: Custom icons don’t appear.

Solutions:

1. Verify icon file was uploaded successfully
2. Check custom_icon_id is correctly assigned
3. Verify image format is supported (PNG, JPG, SVG)
4. Check network requests for 404 errors

---

Related Documentation

• Agents - Agent configuration
• Agent Permissions - Access control
• Widget Configuration - Widget settings
• Access Control Rules - Dynamic permissions