Managing Agents

Agents are AI assistants that handle conversations, answer questions, and collect structured data automatically. This guide covers how to create, configure, and manage agents in Gnosari.

Agent List Page

The agent list (/gnosaris) provides a centralized view of all your AI agents.

View Modes

Mode	Description	Use Case
Grid View	Card-based layout with visual previews	Browsing and comparing agents visually
Table View	Compact row-based layout	Quickly scanning many agents

Toggle between views using the view mode buttons in the top-right corner of the list page.

Search and Filtering

Search: Enter keywords in the search bar to filter agents by name or description. Search is real-time and case-insensitive.

Agent List Columns

The table view displays the following columns (verified against app/types/domains/agent.ts):

Column	Description	Source Field
Name	Agent display name	`name`
Description	Brief summary of agent purpose	`description`
Capabilities	Icon badges showing enabled capabilities	`configuration.manager`, `configuration.reasoning`, `configuration.multimodal`, `configuration.allow_delegation`
Access Level	Public, Private, or Password Protected	`access_level`
Created	Creation timestamp	`created_at`
Actions	Quick action buttons	—

Capability Badges:

Manager (crown icon): Agent can manage other agents
Reasoning (brain icon): Advanced multi-step reasoning enabled
Multimodal (image icon): Can understand images and vision
Delegation (network icon): Can delegate tasks to other agents

Per-Agent Actions

Each agent in the list has quick action buttons:

Action	Icon	Description
Chat	Message bubble	Open a chat session with the agent
Edit	Pencil	Open the advanced configuration form
Embed	Code brackets	View embed code for the widget
Delete	Trash	Permanently delete the agent (confirmation required)

Row Click: Clicking anywhere on an agent row (outside action buttons) opens the agent detail view.

Creating Agents

There are two paths for creating agents:

1. Build Wizard (Recommended)

Path: /build → Select Purpose → Customize

The Build Wizard is a 4-step conversational flow powered by an AI agent that creates your agent through natural conversation:

Purpose: Select from 9 pre-configured agent types (Lead Collector, Customer Support, etc.)
Auth: Login or register (auto-skips if already authenticated)
Customize: Chat with the Build Wizard to configure your agent
Success: View your created agent and next actions

Key Features:

No form-based data collection — everything via chat
Agent creation happens automatically via MCP (Model Context Protocol)
Build Wizard uses Gnosari Manager MCP to create agents on your behalf
Conversation completion triggers automatic transition to Success step

When to use: First-time users, quick setup, guided experience

2. Advanced Form (Power Users)

Path: /gnosaris/create

The advanced form provides full control over all agent configuration options in a traditional form interface.

When to use: Experienced users, complex multi-agent setups, precise configuration requirements

See: Agent Configuration Guide for full form documentation

Agent Capabilities

Capabilities are advanced features that enhance agent behavior. These are configured in the configuration object.

Capability	Field	Description	Default
Manager	`manager`	Agent can coordinate and manage other agents	`false`
Reasoning	`reasoning`	Multi-step reasoning and chain-of-thought processing	`false`
Multimodal	`multimodal`	Understand images, screenshots, and visual content	`false`
Allow Delegation	`allow_delegation`	Delegate sub-tasks to other specialized agents	`false`
Orchestrator	`orchestrator`	Route and coordinate workflows across multiple agents	`false`

Configuration Example:

json

{
  "configuration": {
    "manager": false,
    "reasoning": true,
    "multimodal": true,
    "allow_delegation": true,
    "orchestrator": false
  }
}

When enabled:

Manager: Agent appears in team manager dropdowns
Reasoning: Uses extended thinking tokens for complex problems
Multimodal: Accepts image uploads in chat interface
Allow Delegation: Can spawn sub-agents for specialized tasks
Orchestrator: Can route messages to appropriate team members

Access Levels

Control who can interact with your agent via the access_level field.

Access Level	Description	Use Case
PRIVATE	Only you can access the agent	Internal testing, personal assistants
PUBLIC	Anyone with the link can access	Public-facing agents, lead collection
PASSWORD_PROTECTED	Requires password to access	Client-specific agents, gated access

Setting Access:

In the Build Wizard: Configured during the "Share" step
In the Advanced Form: Set via the "Publication" section
After creation: Edit agent → Publication section

Password Protection:

Set via access_password field
Users must enter correct password before starting conversation
Password is stored hashed (not plaintext)

Publication

Agents can be published to custom URLs on the joina.chat domain.

URI and Domain

Field	Description	Example
URI	Custom path slug for agent URL	`my-support-bot`
Domain	Custom domain (if configured)	`example.com`
Published URL	Full public URL	`https://joina.chat/my-support-bot`

Requirements:

URI must be unique across your account
URI can only contain lowercase letters, numbers, hyphens
Domain field is optional (uses joina.chat by default)

Setting via API:

json

{
  "uri": "customer-support",
  "domain_id": null
}

Custom Domains: Configure custom domains in Settings → Domains to publish agents on your own branded URLs.

Agent Traits

Traits are reusable personality and communication patterns that can be applied to agents.

Examples:

helpful: Proactively offers assistance
friendly: Warm, conversational tone
personable: Uses empathy and emotional intelligence
professional: Formal, business-appropriate language

Applying Traits:

Build Wizard: Automatically applies default traits based on purpose
Advanced Form: Select from trait library in the "Personality" section

See: Traits Documentation for full trait system details

Knowledge Sources

Agents can access external knowledge via RAG (Retrieval-Augmented Generation).

Knowledge Source Types:

Website URLs
PDF documents
DOCX files
Markdown files
API endpoints
Database queries
Cloud storage (S3, Google Drive, Dropbox)

Adding Knowledge:

Navigate to Knowledge → Sources
Add a source (URL, PDF, DOCX, etc.)
Assign source to agent via the "Knowledge Base" section

How it works:

Agent searches sources when answering questions
Semantic search returns most relevant content
Agent cites sources in responses

See: Knowledge Sources for full knowledge system documentation

Learning Objectives

Learning objectives define what the agent should learn from conversations over time.

Example Objectives:

Learn customer pain points
Identify common product questions
Track feature requests
Understand objection patterns

Configuration:

Field: learning_objective_ids (array of integers)
Assign via /learning-objectives page — the advanced form has no dedicated "Learning" section

How it works:

Agent tracks insights related to objectives during conversations
Insights stored in database and linked to sessions
Review insights via Sessions → AI Insights panel

See: Learning Objectives for full learning system documentation

Chat Theme

Customize the chat widget appearance for each agent.

Theme Options:

Pre-built themes (Light, Dark, Brand)
Custom color themes
Background patterns
Typography settings

Setting Theme:

Field: chat_theme_id (integer, nullable)
Set via Advanced Form → "Publication" section
Or create themes at /chat-themes

Per-Agent Overrides: Each agent can override global theme settings via configuration.chat_ui object.

See: Chat Themes for full theming documentation

Entity Types and Data Collection

Configure what structured data the agent should collect during conversations.

Collection Modes (defined in app/types/domains/agent.ts):

Mode	Icon	Description	Requires Prompt
Passive	Eye slash	Silent observer - extracts data after conversation ends	No
Opportunistic	Eye	Watch & probe - asks brief follow-ups when topic arises	Optional
Active	Chat bubbles	Ask directly - proactively asks for information	Optional
Guided	Clipboard list	Follow script - uses custom script for structured collection	Yes (required)

Configuration:

Field: entity_types (array of EntityTypeWithMode)
Each entry has: entity_type_id, collection_mode, custom_prompt

Example:

json

{
  "entity_types": [
    {
      "entity_type_id": 1,
      "collection_mode": "active",
      "custom_prompt": "Ask for email early in the conversation. Explain it's so we can send them resources."
    }
  ]
}

See: Entity Types for full data collection documentation, and the Collected Data Inbox for reviewing what agents capture

Tools

Tools extend agent capabilities by integrating with external services.

Tool Types:

HTTP APIs (REST, GraphQL)
MCP servers (Model Context Protocol)
Python functions
Shell commands
Database queries

Adding Tools:

Build Wizard: Select from tool library during setup
Advanced Form: no dedicated section — the "Integrations" section was removed. Tools are not currently configurable from the advanced form UI

Tool Configuration:

Field: tools (array of integers or Tool objects)
Each tool has: name, description, connection_type, url, headers, args

Security: Tools run in sandboxed environments with access controls.

See: Tool Integration for tool setup and examples

Editing Agents

Two ways to edit:

Quick Edit: Click pencil icon on agent row → Opens advanced form with all fields
Full Edit: Navigate to agent detail → Click "Edit" button

What can be edited:

All configuration fields (name, description, instructions)
Capabilities and access levels
Knowledge sources and tools
Entity types and collection modes
Publication settings (URI, domain, theme)

What cannot be edited:

Agent ID
Creation timestamp
Historical session data

Saving changes:

Changes saved immediately on form submission
No draft system — edits are live instantly
Edit history not tracked (consider version control for critical agents)

Deleting Agents

Warning: Deletion is permanent and irreversible.

What gets deleted:

Agent configuration and settings
Associated learning insights
Chat theme overrides
Publication URLs

What is preserved:

Historical sessions (sessions remain accessible)
Collected entity data (entities remain in database)
Knowledge sources (sources not deleted)

Deletion flow:

Click trash icon on agent row
Confirmation dialog appears
Enter agent name to confirm
Click "Delete Permanently"

Cannot delete if:

Agent is part of an active team
Agent has active scheduled tasks
Agent is referenced by automation workflows

Agent List API Fields

The agent list endpoint (/api/agents) returns agents with the following structure (verified against app/types/domains/agent.ts):

typescript

interface ExtendedAgent {
  id: number
  name: string
  description: string
  identifier?: string
  image_url?: string
  instructions?: string

  // Configuration
  configuration?: {
    manager?: boolean
    reasoning?: boolean
    multimodal?: boolean
    allow_delegation?: boolean
    orchestrator?: boolean
    chat_ui?: AgentChatUIConfig
  }

  // Access control
  access_level?: 'PRIVATE' | 'PUBLIC' | 'PASSWORD_PROTECTED'
  access_password?: string

  // Publication
  uri?: string | null
  domain_id?: number | null
  domain?: DomainMinimal | null

  // Theme
  chat_theme_id?: number | null
  chat_theme?: ChatThemeMinimal | null

  // Related entities
  traits?: any[]
  knowledge?: any[]
  learningObjectives?: any[]
  entity_types?: EntityTypeWithMode[]

  // Timestamps
  created_at?: string
  updated_at?: string

  // Legacy fields (deprecated)
  suggested_prompts?: SuggestedPromptsConfig | null
  empty_state_title?: string | null
  empty_state_description?: string | null
}

Key API Fields:

identifier: Auto-generated unique slug (different from uri)
image_url: Agent avatar image
traits: Array of trait objects (not just IDs)
entity_types: Full objects with collection_mode and custom_prompt

Best Practices

Naming Agents

Use clear, descriptive names (avoid generic names like "Agent 1")
Include purpose in name: "Customer Support Bot" not "Bot"
Keep names under 50 characters for readability

Writing Instructions

Be specific about agent goals and behavior
Include examples of good responses
Define boundaries (what agent should NOT do)
Keep instructions under 2000 characters for optimal performance

Configuring Capabilities

Enable Reasoning for complex problem-solving tasks
Enable Multimodal if agent needs to understand screenshots/images
Enable Delegation for multi-step workflows requiring specialization
Don't enable all capabilities — each adds latency and cost

Access Levels

Use PRIVATE during development and testing
Switch to PUBLIC only when ready for production
Use PASSWORD_PROTECTED for client-specific agents

Knowledge Sources

Start small — add 5-10 key documents, not 1000
Test search quality before deploying agent
Update knowledge regularly (set up scheduled re-indexing)

Performance

Agents with fewer tools respond faster
Limit knowledge sources to avoid slow response times
Disable unused capabilities
Use caching for frequently accessed knowledge

Next Steps

Build Wizard Guide: Step-by-step wizard walkthrough
Agent Configuration: Deep dive into advanced form
Agent Purposes: Explore 9 pre-configured types
Knowledge Sources: Set up RAG knowledge sources
Chat Widget: Embed agent on your website

Managing Agents ​

Agent List Page ​

View Modes ​

Search and Filtering ​

Agent List Columns ​

Per-Agent Actions ​

Creating Agents ​

1. Build Wizard (Recommended) ​

2. Advanced Form (Power Users) ​

Agent Capabilities ​

Access Levels ​

Publication ​

URI and Domain ​

Agent Traits ​

Knowledge Sources ​

Learning Objectives ​

Chat Theme ​

Entity Types and Data Collection ​

Tools ​

Editing Agents ​

Deleting Agents ​

Agent List API Fields ​

Best Practices ​

Naming Agents ​

Writing Instructions ​

Configuring Capabilities ​

Access Levels ​

Knowledge Sources ​

Performance ​

Next Steps ​

Managing Agents

Agent List Page

View Modes

Search and Filtering

Agent List Columns

Per-Agent Actions

Creating Agents

1. Build Wizard (Recommended)

2. Advanced Form (Power Users)

Agent Capabilities

Access Levels

Publication

URI and Domain

Agent Traits

Knowledge Sources

Learning Objectives

Chat Theme

Entity Types and Data Collection

Tools

Editing Agents

Deleting Agents

Agent List API Fields

Best Practices

Naming Agents

Writing Instructions

Configuring Capabilities

Access Levels

Knowledge Sources

Performance

Next Steps