Agent Lifecycle

What it is: An agent is a conversational AI assistant that conducts conversations and collects structured data. Agents are published to public URLs and can be shared with anyone.

Why it exists: Instead of building custom chatbots from scratch, Gnosari agents provide pre-configured conversational AI with automatic data collection, knowledge integration, and public URL generation.

What is an Agent?

An agent in Gnosari is a complete conversational AI package that includes:

• Identity: Name, description, model selection
• Behavior: Instructions that define what the agent does
• Access control: Who can chat with the agent
• Data collection: What structured data to extract from conversations
• Knowledge: Domain expertise from websites/documents
• Appearance: Chat theme, greeting, personality traits
• Publishing: Public URL for sharing (joina.chat/...)

Key principle: Agents are self-contained. Everything needed to run a conversation is configured on the agent.

Agent Attributes

Core Attributes

Attribute	Purpose	Example
name	Display name	"Sales Assistant"
description	Optional description for internal use	"Qualifies leads for enterprise sales"
instructions	Agent behavior and personality	"You are a helpful sales assistant..."
model	Which LLM to use	"gpt-4", "claude-sonnet-4"
temperature	Response creativity (0.0-1.0)	0.7 (default)
reasoning_effort	Claude reasoning intensity	"low", "medium", "high"
orchestrator	Whether agent coordinates sub-agents	false (default)

Configuration Objects

Object	Purpose
access_level	Who can chat (PUBLIC, PASSWORD_PROTECTED, PRIVATE)
data_collection	Template definition + collection mode
knowledge_sources	URLs to crawl for domain knowledge
chat_theme	Branding, colors, greeting message
traits	Personality trait IDs
domain	Which domain to publish on (default: joina.chat)

Access Levels

Agents support three access levels that control who can chat:

PUBLIC

What it means: Anyone with the joina.chat link can start a conversation. No authentication required.

Use cases:

• Lead capture on marketing sites
• Customer support bots
• Product information assistants
• Event registration
• Public FAQs

Public URL pattern: joina.chat/{domain-slug}/{agent-slug}

Example:

gnosari_create(
    name="Product Demo",
    instructions="Show how our product works...",
    empty_state_title="Try our product demo",
    empty_state_description="Ask me anything about the product",
    data_collection=DataCollectionInput(
        name="Demo Lead",
        description="Capture interest from demo visitors",
        fields=[{"name": "email", "field_type": "email", "description": "Contact email", "required": True}]
    ),
    publish=True,
    uri="product-demo"
)
# Returns: CreatedAgentResult with published_url = "https://joina.chat/product-demo"

PASSWORD_PROTECTED

What it means: Anyone with the link can chat, but they must enter a password first.

Use cases:

• Internal tools for teams
• Beta access for testers
• Gated content
• Client-specific agents

Setup — create first, then set access:

result = gnosari_create(
    name="Beta Assistant",
    instructions="Internal beta testing assistant...",
    empty_state_title="Beta Program",
    empty_state_description="Provide feedback on our beta features",
    data_collection=DataCollectionInput(...)
)
gnosari_manage_access(
    gnosari_id=result.agent.gnosari_id,
    access_level="PASSWORD_PROTECTED",
    uri="beta-assistant",
    password="beta2024"
)

Users see a password prompt before entering the chat.

PRIVATE

What it means: Agent is not published to joina.chat. Only accessible via API or embedded widget with authentication.

Use cases:

• Backend integrations
• Embedded agents in logged-in apps
• Testing/staging environments

Note: Private agents don't have a public URL. Use the widget SDK with authentication or direct API access.

Agent Configuration

Model Selection

Agents support multiple LLM providers:

Model ID	Provider	Best For
gpt-4	OpenAI	General purpose, high quality
gpt-5-mini	OpenAI	Fast, cost-effective (default)
claude-sonnet-4	Anthropic	Long context, reasoning
claude-opus-4	Anthropic	Complex tasks, code

Default: gpt-5-mini (set via GNOSARI_DEFAULT_MODEL environment variable)

Temperature

Controls response randomness:

• 0.0: Deterministic, factual responses
• 0.7: Balanced creativity (default)
• 1.0: Maximum creativity and variation

Recommendation: Use 0.3-0.5 for customer support, 0.7-0.9 for creative applications.

Reasoning Effort (Claude only)

Controls Claude's extended thinking:

• low: Fast responses, minimal reasoning
• medium: Balanced (default)
• high: Deep reasoning, slower responses

Only applies to Claude models. Ignored for other providers.

Composite Creation Pattern

gnosari_create is a composite tool. In one atomic call it creates the agent, creates and assigns the data-collection template, and optionally publishes. This replaces the old multi-step create_agent → separate resource creation pattern.

Composite (Recommended)

result = gnosari_create(
    name="Sales Bot",
    instructions="Qualify leads for enterprise sales...",
    empty_state_title="Talk to Sales",
    empty_state_description="Tell us about your needs and we'll be in touch",
    data_collection=DataCollectionInput(
        name="Lead Info",
        description="Capture lead contact details and interest",
        fields=[
            FieldInput(name="email", field_type="email", description="Contact email", required=True),
            FieldInput(name="company", field_type="text", description="Company name")
        ],
        mode="active"
    ),
    greeting="Hi! Tell me about your company and what you're looking for."
)
# result.agent.gnosari_id available immediately
# result.readiness shows what to configure next (knowledge, traits, publish)

The agent, data-collection template, and assignment all commit atomically. If any input is invalid, all errors are reported at once and nothing is written.

Post-Create: Add Knowledge

Knowledge sources are not part of gnosari_create — add them after creation:

gnosari_manage_knowledge(
    action="create",
    name="Product Docs",
    url="https://docs.example.com",
    gnosari_id=result.agent.gnosari_id  # creates AND assigns in one call
)

type is optional — omitting it (as above) OR passing type="website" triggers whole-site auto-resolve (sitemap → discovery fallback). See the Manage Resources reference for the full probe order, how to force sitemap/discovery explicitly, and single_page=true to load a single page only.

When to separate: Reuse the same knowledge source across multiple agents by creating it once then assigning with action="assign".

# Create once
src = gnosari_manage_knowledge(action="create", name="Shared KB", url="...", type="sitemap")

# Assign to multiple agents
gnosari_manage_knowledge(action="assign", source_ids=[src.id], gnosari_id=agent1_id)
gnosari_manage_knowledge(action="assign", source_ids=[src.id], gnosari_id=agent2_id)

Publishing

When you create a PUBLIC or PASSWORD_PROTECTED agent, it's automatically published to a joina.chat URL.

URL Generation

Pattern: https://joina.chat/{domain-slug}/{agent-slug}

Example:

• Agent name: "Product Demo Assistant"
• Account domain: "acme"
• Generated slug: "product-demo-assistant"
• Public URL: https://joina.chat/acme/product-demo-assistant

Slug generation rules:

• Lowercase
• Spaces → hyphens
• Special characters removed
• Unique within account

Domain Assignment

Agents are published to domains (subdomains of joina.chat).

Default domain: Your account's primary domain (usually your company name)

Custom domains: Use the domain parameter to publish to a specific domain:

gnosari_manage_access(
    gnosari_id=42,
    access_level="PUBLIC",
    uri="support-bot",
)
# Publishes to: joina.chat/support-bot

The publishing domain (joina.chat) is resolved server-side — there is no domain parameter and no domain-listing tool. Custom domains are not a shipped feature.

Agent Lifecycle Flow

Create → Configure → Publish → Collect Data → Monitor → Update
   ↓         ↓           ↓            ↓           ↓        ↓
[DB]    [DB+API]    [joina.chat]  [Convos]   [Dashboard] [DB]

1. Create

Call gnosari_create() with name, instructions, welcome screen fields, and data collection template. Agent is saved atomically with its template.

2. Configure

Add knowledge sources with gnosari_manage_knowledge, personality traits with gnosari_manage_traits, and adjust appearance with gnosari_manage_appearance (welcome content + a curated style_preset for visual identity). Each step is independent and idempotent.

3. Publish

Call gnosari_manage_access(access_level="PUBLIC", uri="my-agent") to publish to joina.chat/my-agent. The publishing domain is resolved automatically.

4. Collect Data

As users chat, the data collection engine extracts structured data based on the template configured at creation.

5. Monitor

Use gnosari_collected_data(action="list") and gnosari_collected_data(action="stats") to view extracted data.

6. Update

Modify agent configuration with gnosari_update(). Changes apply to new conversations immediately.

Key Behaviors

Automatic Behaviors

When you create an agent:

• Slug is auto-generated from name
• Public URL is assigned (if PUBLIC/PASSWORD_PROTECTED)
• Knowledge sources start loading (async)
• Chat theme defaults to "default" preset if not specified
• Model defaults to GNOSARI_DEFAULT_MODEL if not specified

When you update an agent:

• Only provided fields are modified
• Public URL remains stable (slug doesn't change)
• Existing conversations are unaffected
• New conversations use updated configuration

When you delete an agent:

• Agent is permanently removed
• Collected data is preserved (linked to account, not agent)
• Public URL becomes inactive
• Knowledge sources are not deleted (may be used by other agents)

Immutable After Creation

These attributes cannot be changed after creation:

• Agent ID
• Slug (and therefore public URL)
• Created timestamp

Everything else can be updated.

Related Concepts

• Data Collection: How agents extract structured data
• Knowledge System: How agents use domain knowledge
• Agent Creation Flow: Complete creation workflow