Agent Configuration

The advanced form (/gnosaris/create) provides full control over agent configuration. This guide documents every section and field available in the form.

Form Sections

The form is organized into 6 sections (verified against AgentFormSections.vue and AgentAdvancedForm.vue), navigated via a left sidebar. Only Essentials is required — the other 5 are marked Optional in the nav.

Section	Icon	Required	Description
Essentials	User circle	Yes	Identity (name, description, identifier, image) + instructions editor
Knowledge Base	Book	Optional	Attach knowledge sources
Personality	Heart	Optional	Attach personality traits
Chat	Chat bubble	Optional	Greeting, auto-message, suggested prompts, welcome screen, advanced overrides
Data Collection	Rectangle stack	Optional	Entity types, collection modes
Publication	Globe	Optional	URI, domain, access level, chat theme

Agent type selection is not part of this form. Purpose/type templates (pre-written instructions, traits, color theme) are chosen in the Build Wizard (/build) only — the advanced form's AgentTypeSelector component was removed. Agents created via the advanced form start from a blank Essentials section.

Integrations (tool/API connections) are not part of this form either — the section was removed. See Tools for how tools are currently configured.

Section 1: Essentials (required)

Purpose: Core identity plus the instructions that define agent behavior. This is the only required section.

Identity Fields

Field	Type	Required	Validation	Description
Name	Text	Yes	—	Display name shown in UI and chat
Description	Textarea	No	Max 500 chars	Brief summary of agent purpose
Identifier	Text	No	Unique slug	Auto-generated from name
Image URL	Text (URL)	No	Valid URL	Agent avatar (shows in chat and cards)

Instructions Editor

Type: Rich markdown editor (MarkdownEditor, mode="rich"), with a fullscreen mode and an AI-helper assist button in the card header. Required: Yes — instructions cannot be blank. Character counter: Shown below the editor; a "good detail" badge appears once instructions exceed 500 characters.

Best practices (shown as in-app tips):

Be specific about goals and boundaries
Include examples of good responses
Define what the agent should NOT do

Section completion (nav): Essentials shows complete once both name and instructions are filled — matches the form's actual validity rule (see Form Validation).

Section 2: Knowledge Base (optional)

Purpose: Give the agent access to external information via RAG.

Field: List of selected knowledge sources, added via an "Add Source" button that opens a selection modal (search + create-new link to /knowledge). Source: /api/knowledgeNav badge: Shows the count of attached sources; shows "Optional" when empty.

How it works:

Navigate to /knowledge and add sources (URLs, PDFs, etc.)
Attach sources to the agent from this section
Agent searches sources when answering questions

See: Knowledge Sources for full knowledge system documentation

Section 3: Personality (optional)

Purpose: Define communication style and tone via reusable traits.

Field: List of selected traits, added via an "Add Trait" button that opens a selection modal (search + create-new link to /traits). Source: /api/traitsNav badge: Shows the count of attached traits; shows "Optional" when empty.

How traits work:

Each trait adds behavioral instructions to the agent
Multiple traits combine (agent follows all selected traits)

See: Traits Documentation

Section 4: Chat (optional)

Purpose: Configure everything about the in-conversation experience. This section merges what used to be three separate sections (Suggested Prompts, Welcome Screen, Chat Experience) into one, made up of three sub-cards plus two collapsibles.

A banner at the top of the section explains that these fields override the chat theme's defaults — leave them blank to inherit the theme.

Sub-card: Greeting & Auto Message

Field	Type	Description
Greeting	Textarea	Agent's first message when chat loads. Overrides the theme default.
Auto Message (toggle)	Switch	Enables an automatic follow-up message
Message	Textarea	Auto-message text (shown when toggle enabled), max 500 chars
Delay	Number	Milliseconds to wait before sending (default: 3000)

Field location: configuration.chat_ui.greeting, configuration.chat_ui.autoMessage.{enabled,message,delay}

Sub-card: Suggested Prompts

Field: Array of prompt objects, managed via SuggestedPromptEditor (inline add/edit/delete). Purpose: Conversation-starter buttons shown below the empty chat state. Field location: configuration.chat_ui.suggestedPrompts / configuration.chat_ui.suggestedPromptsEnabled

Sub-card: Welcome Screen

Field	Type	Max Length	Description
Title	Text	100 chars	Welcome headline shown before the first message
Description	Textarea	500 chars	Brief introduction or instructions

A live preview of the empty state renders below the fields (EmptyStatePreview), using the agent's name and avatar. A "Clear" button resets both fields back to the theme default.

Field location: configuration.chat_ui.emptyTitle, configuration.chat_ui.emptyDescription

Collapsible: Advanced Features (collapsed by default)

Field	Type	Description
Smart Follow-Up Prompts	Toggle	Enables AI-suggested follow-up prompts after each response (`configuration.chat_ui.followUpPrompts.enabled`)

Enabling this toggle also adds suggest_followups to configuration.emits automatically.

Collapsible: UI & Behavior Overrides (collapsed by default, badged "Advanced")

UI Overrides (all toggles):

Field	Field Location
Show Header	`chat_ui.showHeader`
Show New Chat in Nav	`chat_ui.showNewChatInNav`
Show Agent Selector	`chat_ui.showAgentSelector`
Hide Welcome	`chat_ui.hideWelcome`

Behavior Overrides:

Field	Type	Field Location
Enable Attachments	Toggle	`chat_ui.enableAttachments`
Enable Model Selection	Toggle	`chat_ui.enableModelSelection`
Max Message Length	Number	`chat_ui.maxMessageLength`

Nav completion: The Chat section nav badge shows "Optional" (it never shows a numeric count); the section is marked complete once greeting, suggested prompts, or a welcome-screen field is set.

Section 5: Data Collection (optional)

Purpose: Configure what structured data the agent extracts from conversations.

Enable Toggle

A single toggle (extractionEnabled) turns entity extraction on/off and is always saved to configuration.data_collection.enabled — independent of whether any entity type is attached. When off, the section shows a disabled-state message and no entity-type panel.

Enabled with no templates yet: the section shows a warning alert instead of implying collection is running — turning the toggle on is saved immediately, but nothing is extracted until at least one entity type is attached. The agent list row's "collecting" status reflects both conditions together (enabled AND has templates), so it can never disagree with the edit form.

Entity Types (shown when enabled)

Field: Entity type selector with per-type collection-mode configuration, added via a selection modal (search + create-new link to /entity-types). Source: /api/entity-types

Collection Modes:

Mode	Behavior	Requires Custom Prompt
passive	Silent observer — extracts after conversation	No
opportunistic	Watch & probe — asks brief follow-ups	Optional
active	Ask directly — proactively asks	Optional
guided	Follow script — structured collection	Yes (required)

Validation: An entity type with collection_mode: 'guided' and no custom_prompt blocks form submission — surfaced as a validation error in the section.

Nav completion: Complete once extraction is enabled AND at least one entity type is configured.

See: Entity Types

Section 6: Publication (optional)

Purpose: Configure public access, URLs, and chat theme.

Access Level

Options: PRIVATE (default, only you), PUBLIC (anyone with the link), PASSWORD_PROTECTED (requires password).

Password Protection

Shown inline when access level is PASSWORD_PROTECTED. Minimum 4 characters (validated client-side).

Public URI + Domain

Shown when access level is not PRIVATE. A combined domain-picker + slug input with live availability checking (debounced 600ms) against checkUriAvailability. On a taken slug, the form suggests alternatives ({slug}-ai, {slug}-bot, my-{slug}).

Result: Published at {domain.base_url}/{uri} (defaults to joina.chat).

Chat Theme

Dropdown of available chat themes (optional — defaults to the built-in theme). Individual Chat-section overrides (Section 4) take precedence over theme settings.

Nav completion: Complete once access level is set AND (private OR a URI is configured).

Form Validation

Required Fields

Minimum to create or save an agent (isFormValid in useAgentAdvancedForm.ts):

Name
Instructions
No unresolved entity-type validation errors (e.g. a guided entity type missing its custom prompt)

Every other field across every other section is optional. The Save button is disabled until these conditions are met.

Section Nav Indicators

Essentials: no badge; marked complete once name + instructions are filled
Knowledge / Personality / Data Collection: numeric badge = item count; "Optional" badge when empty
Chat / Publication: always show an "Optional" badge (never a count)

Error Display

Inline errors: Shown below fields when validation fails (e.g. entity-type validation errors rendered in the Data Collection section).

Save Button

Location: Fixed footer bar (always visible) States: Disabled (required fields incomplete) / Enabled (form valid) / Loading (save in progress) Text: "Create Agent" (new) or "Save Changes" (edit)

Cancel Button

Location: Footer bar (left side) Action: Navigate to /gnosaris (discards changes)

Auto-Save

Status: Not implemented — changes are lost if you navigate away without saving.

Best Practices

Recommended Flow

Essentials — name your agent and write instructions (the only required step)
Knowledge — attach sources if the agent needs external information
Personality — attach traits to fine-tune tone
Chat — set a greeting, suggested prompts, or a welcome screen if you want to override the chat theme's defaults
Data Collection — enable extraction and configure entity types if the agent should capture structured data
Publication — set access level and, if not private, choose a public URI and theme

Performance Considerations

Each knowledge source adds latency to responses
More traits mean more nuanced behavior but slightly slower responses
Complex data-collection configuration (many guided/active entity types) adds conversational overhead

Recommendations: keep knowledge sources and traits focused rather than exhaustive; test response time before publishing.

Testing Configuration

After saving:

Navigate to the agent detail page
Click "Chat" to test the conversation
Verify knowledge retrieval works (if configured)
Test data collection — check extracted entities (if configured)
Confirm the public URL loads correctly (if published)

Next Steps

Managing Agents: Agent list and quick actions
Agent Purposes: Explore all 9 pre-configured Build Wizard types
Knowledge Sources: Set up RAG knowledge
Chat Widget: Embed on your website

Agent Configuration ​

Form Sections ​

Section 1: Essentials (required) ​

Identity Fields ​

Instructions Editor ​

Section 2: Knowledge Base (optional) ​

Section 3: Personality (optional) ​

Section 4: Chat (optional) ​

Sub-card: Greeting & Auto Message ​

Sub-card: Suggested Prompts ​

Sub-card: Welcome Screen ​

Collapsible: Advanced Features (collapsed by default) ​

Collapsible: UI & Behavior Overrides (collapsed by default, badged "Advanced") ​

Section 5: Data Collection (optional) ​

Enable Toggle ​

Entity Types (shown when enabled) ​

Section 6: Publication (optional) ​

Access Level ​

Password Protection ​

Public URI + Domain ​

Chat Theme ​

Form Validation ​

Required Fields ​

Section Nav Indicators ​

Error Display ​

Saving and Navigation ​

Save Button ​

Cancel Button ​

Auto-Save ​

Best Practices ​

Recommended Flow ​

Performance Considerations ​

Testing Configuration ​

Next Steps ​