AI Chat App Tutorial

🤖 What You'll Build

A production-ready, intelligent chat application that uses Fiberwise agent activations for storing conversations. Think of it as your own personal ChatGPT, powered by the Fiberwise platform.

• Interactive Chat UI: A clean, modern interface for real-time conversations.
• Intelligent AI Agent: Powered by a flexible assistant agent you can customize.
• Conversation History: Automatically saves and retrieves chat sessions.
• One-Click Deploy: Ready to be deployed live on the Fiberwise platform.

Step 1: Get the Code

The Fiberwise platform includes example apps in the local fiber-apps/ directory. Navigate to the activation chat example project to explore its structure.

# Navigate to the fiber-apps directory (included with Fiberwise)
cd fiber-apps/activation-chat

# List the files to see the app structure
ls -la

code .

Step 2: Understanding the App's Blueprint

Before installing, let's look at the key concepts that define the application. This will help you understand what happens in the next step.

The Manifest: `app_manifest.yaml`

This is the most important file. It's the blueprint that tells Fiberwise what resources your app needs. It defines the app itself, the data models it uses, and the AI agent that powers the chat.

Project Structure

The app is built from several modern web components that handle different parts of the UI. This separation makes the code clean and easy to maintain.

activation-chat/
├── 📄 app_manifest.yaml           # ← The app's blueprint
├── 🎯 index.js                    # Main entry point, initializes the app
├── 💬 chat-app.js                 # The main component that orchestrates everything
├── 💭 chat-messages.js            # Displays the list of messages for a session
└── ... (other UI components & styles)

🏗️ App Architecture Flow

Here's the high-level architecture of how Fiberwise applications initialize and prepare for user interaction:

Step 3: Install and Run the App

Now it's time to bring the application to life. This two-step process installs the frontend dependencies and then installs the app onto the Fiberwise platform.

npm install

fiber app install ./

Installing app: Activation Chat
App installed successfully!
App ID: activation-chat
Status: Active ✓

� Technical App Loading Flow

Now let's see the detailed technical flow when you open your app in the browser:

�🔌 Provider Selection Flow

Before sending messages, users select their LLM provider. Here's how provider metadata works:

Step 4: Send Your First Message

Your chat app is now live on your Fiberwise instance. Let's send a message to see it in action and understand exactly what happens behind the scenes.

http://localhost:8000/activation-chat

// When user presses Enter or clicks send
handleSubmit() {
  const message = this.input.value.trim();
  if (message) {
    // Fire custom event that chat-app.js listens for
    this.dispatchEvent(new CustomEvent('message-sent', {
      detail: { content: message }
    }));
    this.input.value = ''; // Clear input
  }
}

async sendMessage(content) {
  // Create the activation with your message
  const activation = await FIBER.agents.activate(
    this.selectedAgentId,           // 'chatAgent' from manifest
    { prompt: content },            // Your message: "Hello, who are you?"
    { 
      chat_id: this.currentChatId,  // Links messages to this conversation
      system_prompt: this.modelSettings.systemPrompt,
      role: 'user'
    },
    {
      provider_id: this.selectedProviderId,  // Which LLM to use
      temperature: this.modelSettings.temperature
    }
  );
  
  // Add pending message to UI immediately
  this.addMessageToUI({
    content: content,
    role: 'user',
    activationId: activation.id,
    status: 'completed'
  });
  
  // Add pending AI response placeholder
  this.addMessageToUI({
    content: '',
    role: 'assistant', 
    activationId: activation.id,
    status: 'pending'
  });
}

# The agent that processes your messages
agents:
  - name: chatAgent
    agent_slug: chat-agent
    description: AI chat assistant agent
    system_prompt: |
      You are a helpful AI assistant. Be friendly and provide 
      clear, concise responses to user questions.
    
    # This agent will automatically use the connected LLM provider
    # with the context and metadata you send via FIBER.agents.activate()

// Set up real-time listener for activation updates
connectedCallback() {
  // ... other initialization ...
  
  // Listen for activation completion events
  FIBER.realtime.on('message', (message) => {
    if (message.type === 'activation_completed') {
      this.handleActivationCompleted(message);
    }
  });
}

handleActivationCompleted(message) {
  // Find the pending message in the UI
  const pendingMessage = this.messages.find(m => 
    m.activationId === message.activation_id && m.status === 'pending'
  );
  
  if (pendingMessage) {
    // Update with the AI's response
    pendingMessage.content = message.output;
    pendingMessage.status = 'completed';
    this.updateMessagesDisplay();
  }
}

Step 5: Deep Dive - How Did That Work?

What just happened when you sent that message? Let's trace the data flow from your browser to the Fiberwise platform and back.

// In chat-app.js -> sendMessage()
const activation = await FIBER.agents.activate(
  this.selectedAgentId, // The ID of our chat agent
  { prompt: content },   // The user's message as input
  { 
    chat_id: this.currentChatId, // Context to group messages
    system_prompt: this.modelSettings.systemPrompt
  },
  metadata // Additional settings like temperature
);

// In chat-app.js -> init()
FIBER.realtime.on('message', (message) => {
  // We listen for the specific event that tells us an activation is done
  if (message.type === 'activation_completed') {
    // We find the 'pending' message in the UI and update it
    // with the final output from the activation.
    this.handleActivationCompleted(message);
  }
});

// Loading previous messages for a chat session
async loadChatHistory(chatId) {
  const activations = await FIBER.agents.listActivations({
    context: { chat_id: chatId },  // Filter by chat session
    sort: 'created_at',            // Order by time
    limit: 50                      // Recent messages
  });
  
  // Convert activations to chat messages
  const messages = activations.map(activation => ({
    content: activation.output,
    role: activation.context.role || 'assistant',
    timestamp: activation.created_at
  }));
  
  this.renderMessages(messages);
}

Step 6: Understanding the Technical Implementation

Now that you've built and tested your chat app, let's dive into the technical details of how it works. This section explains the key implementation patterns you can use in your own apps.

📋 Application Manifest Structure

The app_manifest.yaml file defines your complete application. Here's the activation-chat manifest structure:

app:
  name: Activation Chat
  app_slug: activation-chat
  version: 0.0.21
  description: A chat application that uses agent activations and dynamic data as the message store
  entryPoint: index.js
  icon: fas fa-comments
  category: simple
  
  # Minimal model for session tracking only
  models:
  - name: Chat
    model_slug: chats
    description: Simple chat session container
    fields:
    - name: Chat ID
      field_column: chat_id
      type: uuid
      required: true
      is_primary_key: true
      description: Primary key used as chat_id in agent activation context
    - name: Title
      field_column: title
      type: string
      required: true
      default: New Chat

  routes:
  - path: /
    component: chat-app
    title: Chat
    icon: fas fa-comments

agents:
- name: chatAgent
  agent_type_id: llm
  version: 0.0.2

🏗️ App Entry Point Implementation

Every Fiberwise app follows a standard pattern for platform integration. Here's the complete index.js structure:

// index.js - Standard platform integration pattern
import fiber from 'fiberwise';

// Create FIBER SDK instance using modern constructor pattern
export const FIBER = new FiberWise();

/**
 * Standard initialize function for app platform integration
 * @param {Object} appBridge - AppBridge instance from platform
 * @param {Object} manifest - The application manifest
 * @returns {Promise<boolean>} Success status
 */
export async function initialize(appBridge, manifest) {
  console.log('[ActivationChat] Initializing app...');
  FIBER.initialize(appBridge, manifest);
  return true;
}

/**
 * Standard render function for app platform integration
 * @param {HTMLElement} mountPoint - Where to mount the app
 */
export function render(mountPoint) {
  console.log('[ActivationChat] Rendering app...');
  const el = document.createElement('chat-app');
  mountPoint.appendChild(el);
}

// Register the main Web Component
import './chat-app.js';

💾 Activation Context Structure

The chat app stores messages as agent activations with special context metadata. Here's how the data structure works:

// User message activation
{
  "agent_id": "chatAgent",
  "input_data": {
    "message": "Hello, how are you?"
  },
  "context": {
    "chat_id": "unique-session-identifier",
    "session_title": "Morning Chat",
    "role": "user",
    "system_prompt": "You are a helpful assistant"
  },
  "status": "completed"
}

// Assistant response activation
{
  "agent_id": "chatAgent",
  "input_data": {
    "message": "Hello, how are you?"
  },
  "output_data": {
    "text": "Hello! I'm doing well, thank you for asking."
  },
  "context": {
    "chat_id": "unique-session-identifier", 
    "session_title": "Morning Chat",
    "role": "assistant",
    "system_prompt": "You are a helpful assistant"
  },
  "status": "completed"
}

📡 Data Flow Implementation

Here are the key methods that power the chat functionality:

Message Retrieval

// Query activations by context for chat history
async loadChatHistory(chatId) {
  const activations = await FIBER.agents.getActivations(agentId, {
    context: { chat_id: chatId },
    sort: 'started_at'
  });
  
  return activations
    .filter(a => a.context?.role)
    .map(activation => ({
      role: activation.context.role,
      content: activation.context.role === 'user' 
        ? activation.input_data?.message
        : activation.output_data?.text,
      timestamp: activation.started_at,
      activationId: activation.activation_id
    }));
}

Session Management

// Discover unique chat sessions from activations
async loadSessions() {
  const activations = await FIBER.agents.getActivations(agentId);
  const sessions = new Map();
  
  activations.forEach(activation => {
    if (activation.context?.chat_id && activation.context?.session_title) {
      sessions.set(activation.context.chat_id, {
        id: activation.context.chat_id,
        title: activation.context.session_title,
        lastActivity: activation.started_at
      });
    }
  });
  
  return Array.from(sessions.values())
    .sort((a, b) => new Date(b.lastActivity) - new Date(a.lastActivity));
}

Message Sending Flow

// Complete message sending implementation
async sendMessage(message, chatId) {
  // 1. Create user message activation
  const userActivation = await FIBER.agents.activate(agentId, {
    message: message
  }, {
    chat_id: chatId,
    session_title: this.currentSession.title,
    role: 'user'
  });
  
  // 2. Create assistant activation for AI response  
  const assistantActivation = await FIBER.agents.activate(agentId, {
    message: message,
    system_prompt: this.systemPrompt
  }, {
    chat_id: chatId,
    session_title: this.currentSession.title,
    role: 'assistant'
  });
  
  // 3. Refresh chat history to show both messages
  await this.loadChatHistory(chatId);
}

📊 Conceptual Database Query

While you interact with activations through the SDK, here's the conceptual SQL that shows how message retrieval works:

-- Conceptual query for message retrieval
SELECT * FROM agent_activations 
WHERE context->>'chat_id' = 'session-identifier'
ORDER BY started_at ASC;

🏆 Congratulations!

You've successfully installed, run, and understood a production-grade AI application on Fiberwise. You now know the core pattern for building apps on the platform.