Learn how to configure your AI agent using the Flutch admin console.

Accessing Agent Settings

Log in to console.flutch.ai
Navigate to Agents in sidebar
Click on your agent
Go to Settings tab

URL format: https://console.flutch.ai/agents/{agentId}/settings

General Information

Basic Settings

Agent Name:

Display name shown in UI and chat
Can be changed anytime
Doesn't affect graph type

Description:

Brief explanation of what agent does
Shown to users in chat header
Supports markdown

Avatar:

Upload custom image (JPG, PNG)
Or use default avatar
Displays in chat UI

Status:

Active: Agent accepts messages
Inactive: Agent paused (users see maintenance message)

Graph Type Selection

Choose which graph version to use:

bash
your-company.support-agent::1.0.0  [Stable]
your-company.support-agent::2.0.0  [Beta]

Version statuses:

Stable: Production-ready, default choice
Beta: Testing phase, opt-in only
Deprecated: Old version, migration recommended

Change takes effect immediately—no redeployment needed.

Model Settings

LLM Provider Selection

Choose AI model provider:

OpenAI:

Models: gpt-4, gpt-4-turbo, gpt-3.5-turbo
Best for: General use, fast responses
Cost: $$ - $$$

Anthropic:

Models: claude-3-5-sonnet, claude-3-opus, claude-3-haiku
Best for: Long contexts, reasoning
Cost: $$ - $$$

Google:

Models: gemini-pro, gemini-1.5-pro, gemini-1.5-flash
Best for: Multimodal, cost-effective
Cost: $ - $$

Azure OpenAI:

Custom deployments
Best for: Enterprise compliance
Cost: Custom pricing

Model Parameters

Temperature (0.0 - 2.0):

0.0 - 0.3: Deterministic, factual responses
0.7 - 1.0: Balanced creativity (recommended)
1.5 - 2.0: Highly creative, unpredictable

Max Tokens:

Maximum response length
Default: 2000
Range: 100 - 8000 (model dependent)

Top P (0.0 - 1.0):

Nucleus sampling parameter
Default: 1.0
Lower = more focused responses

Frequency Penalty (-2.0 - 2.0):

Reduces repetition
Default: 0.0
Higher = less repetitive

Presence Penalty (-2.0 - 2.0):

Encourages topic diversity
Default: 0.0
Higher = more diverse topics

API Keys

Set provider API keys:

Click Add API Key for provider
Enter key (securely stored, encrypted)
Click Save
Key is validated automatically

Note: Keys are never shown again after saving (for security).

System Prompt

The system prompt defines agent behavior.

Writing Effective Prompts

Good prompt structure:

bash
You are a customer support agent for Acme Corp.

Your role:
- Answer questions about products and services
- Help troubleshoot issues
- Escalate complex problems to human agents

Guidelines:
- Be friendly and professional
- Keep responses concise (2-3 paragraphs max)
- Always cite source when referencing documentation
- If uncertain, say "Let me connect you with a specialist"

Knowledge:
- Acme offers SaaS products for project management
- Main product: Acme Tasks (task management)
- Support hours: 9 AM - 6 PM EST Monday-Friday

Variables (coming soon):

{{user.name}} - User's name
{{company.name}} - Company name
{{current_date}} - Today's date

Prompt Templates

Click Use Template to start from examples:

Customer Support: Helpful support agent
Technical Assistant: Code help and debugging
Sales Assistant: Product information and demos
Content Writer: Blog posts and articles
Data Analyst: Analyze data and create insights

Customize template after selecting.

Testing Prompts

Update system prompt
Click Save
Go to Dashboard tab
Test in chat widget on right side
Iterate and refine

Changes apply immediately to new conversations.

Tools Configuration

Enable tools (functions) for your agent.

Available Tools

Flutch supports MCP (Model Context Protocol) tools:

Web & Search:

web_search - Search the internet
web_fetch - Fetch webpage content
web_scrape - Extract structured data

Data & Files:

read_file - Read file contents
write_file - Create/update files
list_files - Browse directories

Computation:

calculator - Math calculations
python_repl - Execute Python code
sql_query - Query databases

Communication:

send_email - Send emails
send_slack - Post to Slack
create_ticket - Create support tickets

Enabling Tools

Go to Tools section in settings
Toggle tools on/off
Configure tool-specific settings
Click Save

Example: Enable web search:

Toggle web_search ON
Set max results: 5
Set search engine: Google
Save

Tool Permissions

Control what tools can do:

Read-only: Tools can't modify data
Write: Tools can create/update
Delete: Tools can remove data

Set per-tool or globally.

Knowledge Base

Connect knowledge bases for RAG (Retrieval-Augmented Generation).

Adding Knowledge Base

Go to Knowledge Base section
Click Connect Knowledge Base
Select from your KBs (or create new)
Configure RAG settings
Click Save

RAG Settings

Top K (number of documents):

How many relevant docs to retrieve
Default: 5
Range: 1-20

Similarity Threshold (0.0-1.0):

Minimum similarity score
Default: 0.7
Higher = stricter matching

Reranking:

ON: Use reranker for better results (slower, more expensive)
OFF: Use direct similarity (faster, cheaper)

Testing RAG

After connecting KB:

Ask agent a question from documentation
Check if it uses KB content (look for citations)
Adjust settings if needed

Advanced Settings

Rate Limiting

Per User:

Messages per minute: 10 (default)
Messages per hour: 100
Messages per day: 500

Global:

Total messages per minute: 1000
Burst allowance: 50

Prevents abuse and controls costs.

Timeouts

Response Timeout:

Max time for agent to respond
Default: 30 seconds
Range: 10-120 seconds

Conversation Timeout:

Auto-end idle conversations
Default: 30 minutes
Range: 5-120 minutes

Custom Headers

Add custom HTTP headers to requests:

json
{
  "X-Custom-Header": "value",
  "X-App-Version": "1.0.0"
}

Useful for tracking or passing metadata.

Webhooks

On Message Received:

URL: https://your-api.com/webhook
Method: POST
Payload: Message data

On Conversation End:

Triggered when conversation times out
Useful for analytics or cleanup

Environment Variables

Set environment-specific variables:

bash
# Example variables
CUSTOM_API_URL=https://api.example.com
FEATURE_FLAG_NEW_UI=true
DEBUG_MODE=false

Security: Use for non-sensitive config only. For secrets, use Secrets Manager.

Saving and Applying Changes

Save Button:

Click Save at bottom of page
Changes apply to new conversations immediately
Existing conversations continue with old settings

Discard Changes:

Click Discard to revert unsaved changes

Change History:

View Change Log to see past configuration changes
Useful for troubleshooting

Configuration Best Practices

Start simple: Begin with default settings
Test in private: Use visibility: private for testing
Iterate on prompt: Refine based on actual conversations
Monitor costs: Check Analytics for token usage
Version carefully: Test new versions in beta before making default
Document changes: Keep notes on what works
Use templates: Start from proven prompts

Exporting Configuration

Export settings as JSON:

bash
# Via CLI
flutch config:export <agent-id> > config.json

# Or in UI: Settings → Export Configuration

Import to another agent:

bash
flutch config:import <agent-id> --file config.json

Useful for:

Duplicating agent setup
Backing up configuration
Sharing settings across environments

Next Steps

Add Testing: Acceptance Testing
Debug Issues: Debugging Guide
Distribute Agent: Multi-channel Distribution
Monitor Performance: Measures & Analytics

Tip: Screenshot your working configuration for documentation!

Screenshots Needed

TODO: Add screenshots for:

Agent Settings page overview
Model settings panel
System prompt editor
Tools configuration
Knowledge base connection
Environment variables