Advanced Usage

This section covers advanced customization options for power users.

Colors

In Configuration → App, customize:

Setting	Description
Background	Main background color
Text	Primary text color
Hover	Hover state color
Separator	Divider line color

Icon and Font Sizes

Adjust icon size for visibility
Set base font size for readability

Collapsed width: Width when sidebar is minimized
Expanded width: Width when sidebar is open

In Configuration → App, find menu settings
Drag entries to reorder
Add spacers and separators
Save configuration

Entry Types

Type	Purpose
Link	Navigation to a page
Spacer	Vertical spacing
Separator	Horizontal divider
Theme toggle	Light/dark mode switch

Branding Assets

Light logo: assets/logo_light.png
Dark logo: assets/logo_dark.png
Light icon: assets/icon_light.png
Dark icon: assets/icon_dark.png

Chat Presets

What Presets Do

Presets bundle configuration for quick switching:

Model selection
Enabled tools
Team members
Other chat settings

Using Presets

Open Configuration → Chat
Select a preset from dropdown
Settings apply immediately

Creating Presets

Edit presets.json:

{
  "presets": [
    {
      "name": "Quick Response",
      "model": "gpt-4o-mini",
      "tools": [],
      "members": []
    },
    {
      "name": "Deep Analysis",
      "model": "gpt-4o",
      "tools": ["web_search", "calculator"],
      "members": ["researcher", "analyst"]
    }
  ]
}

Tool and Coordination Tuning

Agent Configuration Access

Open Configuration
Click Open Agent Config
Select an agent to edit

Tool Selection

Enable/disable tools per agent:

Tool	Function
Web search	Search the internet
Calculator	Perform calculations
File operations	Read/write files
Custom tools	Via MCP servers

MCP Servers

Model Context Protocol (MCP) servers provide additional tools:

In Agent Config, find MCP server list
Enable/disable servers
Configure server credentials

MCP Connector Credentials

To connect external systems, configure credentials in .env or .streamlit/secrets.toml:

Connector	Environment Variables
Notion	`NOTION_API_KEY`
Google Drive	`GOOGLE_OAUTH_CREDENTIALS` (path to JSON)
Microsoft 365	`MSAL_TENANT_ID`, `MSAL_CLIENT_ID`, `MSAL_CLIENT_SECRET`

Notion Setup

Go to Notion Integrations
Create a new integration
Copy the API key
Set NOTION_API_KEY in your secrets

Google Drive Setup

Go to Google Cloud Console
Create OAuth 2.0 credentials
Download the JSON file
Set GOOGLE_OAUTH_CREDENTIALS to the file path

Microsoft 365 Setup

Register an app in Azure AD
Note the Tenant ID and Client ID
Create a client secret
Set MSAL_TENANT_ID, MSAL_CLIENT_ID, MSAL_CLIENT_SECRET

Coordination Modes

Mode	Behavior
`direct_only`	Master agent answers directly
`delegate_on_complexity`	Delegates based on skills match
`always_delegate`	Delegates to all members
`coordinated_rag`	Source-first RAG with delegation

Stream Events

stream_events: Enable event-rich streaming
log_stream_events: Verbose event logging

Storage and Runtime Environment

Data Directory

Set HALO_DATA_DIR environment variable:

# Windows PowerShell
$env:HALO_DATA_DIR = "C:\data\halo"

# Linux/macOS
export HALO_DATA_DIR="/data/halo"

Memory Backend

Set HALO_AGENT_DB for persistent memory:

$env:HALO_AGENT_DB = "sqlite:///data/memory.db"

When enabled:

Agents use bounded history (num_history_runs=3)
User memories persist across sessions
Account page shows memory entries

Templates Directory

Set HALO_TEMPLATES_DIR for custom templates:

$env:HALO_TEMPLATES_DIR = "custom_templates"

Team Agent Setup

Member Configuration

In Agent Config, for each member:

Set enabled state
Define skills (for delegation matching)
Configure tools
Write role instructions

Skills Matching

When using delegate_on_complexity:

Agent skills are matched against prompt
Matching members receive delegation
Non-matching members are skipped

Example Skills

{
  "skills": ["research", "analysis", "medical", "writing"]
}

Knowledge and RAG

Knowledge Base

LanceDB stored in data/lancedb
Automatic indexing of sources
Vector search for retrieval

Search Types

Type	Description
Hybrid	Vector + full-text search
Vector	Vector similarity only

!!! note On Windows, vector search is used to avoid hybrid/FTS index lock issues.

Troubleshooting

"Team members not active"

Check:

Member enabled is true
Coordination mode allows delegation
Skills match the prompt

"Knowledge retrieval fails"