App SDK

Pre-built React components for third-party integration

v1.3.1

@agentai/appsdk

v1.3.1

The official React component library for building AI agent interfaces with Agent.ai.

🎨 Pre-built Components🤖 Agent Integration🎯 Fully Typed📱 Responsive♿ Accessible

Installation

npm install @agentai/appsdk @chakra-ui/react @emotion/react

Quick Start

import { ChakraProvider } from '@chakra-ui/react';
import { AgentAIAgentPage, AgentAIButton } from '@agentai/appsdk';

export default function App() {
  return (
    <ChakraProvider>
      <AgentAIAgentPage
        agentHeaderConfig={{
          agentId: 'flux-image-generator', // Auto-fetches from API!
        }}
      >
        <AgentAIButton variant="primary">Run Agent</AgentAIButton>
      </AgentAIAgentPage>
    </ChakraProvider>
  );
}

The AgentAIAgentPage automatically includes the site header, agent info header (with auto-fetch), your content, and site footer.

Available Components (24)

Layout

AgentAIHeader

Site navigation header with auth states

AgentAIFooter

Site footer with branding and links

AgentAIPageCard

Full-page card layout container

AgentAISection

Section with title and accent underline

AgentAICard

Content card container

Agent

AgentAIAgentPage

Complete page shell for agent interfaces

AgentAIAgentHeader

Agent info display with auto-fetch API

AgentAIAgentAvatar

Agent icon with CDN optimization

Form

AgentAIButton

Styled buttons with primary, secondary, outline variants

AgentAIInput

Text inputs with label, validation, error states

AgentAISelect

Dropdown selects with search and multi-select

AgentAISwitch

Toggle switches with labels

AgentAISearchInput

Search input with suggestions and action button

Navigation

AgentAITabs

Horizontal tabbed navigation

AgentAIVerticalTabs

Vertical sidebar navigation with left/right variants

Data Display

AgentAIStatCard

Stat cards for KPIs with trends

AgentAIMetricCard

Large metric display with accent border

AgentAIStatGrid

Responsive grid for stat cards

AgentAIPill

Clickable pills/chips with color variants

AgentAITagCard

Card with grouped tags

AgentAISuggestionPills

Suggestion pills row

AgentAIDataTable

Simple data table with sorting

AgentAIBarChart

CSS-based bar chart (no external lib)

AgentAITimeline

Timeline for news/events

AgentAIAvatar

User avatars with fallback

Feedback

AgentAIAlert

Alert/notification with info, success, warning, error, auth statuses

AgentAIInfoBanner

Status banner with icon and action button

Labs & Apps

AgentAILabsHero

Hero section with search and CTA

AgentAIAppCard

App card with status badges

AgentAIAppCardGrid

Responsive grid for app cards

AgentAIFeatureCard

Featured app card with gradient

Requirements

React 18+

Hooks and concurrent features

Chakra UI 3+

Component primitives

Emotion

Required by Chakra UI

📦 NPM Package 🌐 Agent.ai 📚 Documentation

Agent.ai API SDKs

Build powerful backends with the Agent.ai Actions API. Access LLMs, web scraping, social media data, image generation, and more.

JavaScript SDK

Modern JavaScript SDK for Node.js backends and serverless functions.

npm install @agentai/agentai

npmjs →GitHub →

Python SDK

Simple and powerful Python library for Flask, FastAPI, and Django backends.

pip install agentai

PyPI →GitHub →

Quick Examples

JavaScript - Chat with LLM

const { AgentAiClient } = require('@agentai/agentai');

const client = new AgentAiClient(process.env.AGENT_API_KEY);

// Chat with an LLM
const response = await client.chat('Explain AI agents');

if (response.status === 200) {
  console.log(response.results);
}

Python - Chat with LLM

from agentai import AgentAiClient

client = AgentAiClient()  # Uses AGENTAI_API_KEY env var

# Chat with an LLM
response = client.chat("Explain AI agents")

if response['status'] == 200:
    print(response['results'])

Available API Actions

🤖 AI

LLMs, Images, Audio

🌐 Web

Scrape, Screenshot, Search

📱 Social

Twitter, LinkedIn, Instagram

📰 News

Google News, YouTube

Get your API key at agent.ai/user/integrations

Examples

Explore complete, copy-paste examples to help you get started quickly. Each example includes both a live preview and the full source code.

🎯 Frontend Examples

Agent pages, dashboards, and UI patterns

⚡ Backend Examples

Node.js and Python API integrations

🔗 Full Stack

Connect frontend with backend APIs

Frontend Examples

Simple Agent PageBeginner

A minimal agent interface with input and button

Your Prompt*

Kitchen Sink - Company Research ToolAdvanced

Custom Page with Header/FooterIntermediate

Using AgentAIHeader and AgentAIFooter with custom content

// CustomDashboard.jsx
import { ChakraProvider } from '@chakra-ui/react';
import { useState } from 'react';
import { 
  AgentAIHeader,
  AgentAIFooter,
  AgentAIPageCard,
  AgentAISection,
  AgentAIStatCard,
  AgentAIStatGrid,
  AgentAIButton,
  AgentAITabs,
  AgentAIAlert
} from '@agentai/appsdk';
import { Box } from '@chakra-ui/react';
import { LuHome, LuBot, LuSettings } from 'react-icons/lu';

export default function CustomDashboard() {
  const [user, setUser] = useState(null);
  const [activeTab, setActiveTab] = useState('home');

  // Custom login handler (e.g., OAuth)
  const handleLogin = () => {
    // Your login logic here
    setUser({
      name: 'John Doe',
      picture: 'https://avatars.githubusercontent.com/u/1?v=4',
      username: 'johndoe'
    });
  };

  const handleLogout = () => setUser(null);

  return (
    <ChakraProvider>
      {/* Header with custom auth */}
      <AgentAIHeader
        user={user}
        onLogin={handleLogin}
        onLogout={handleLogout}
        useCustomAuth={true}
        loginLabel="Sign In"
        signupLabel="Get Started"
        currentPath="/dashboard"
      />

      {/* Main Content */}
      <AgentAIPageCard
        icon={<LuHome size={20} />}
        title="My Dashboard"
        description="Welcome to your personal dashboard"
        headerAction={
          <AgentAIButton variant="secondary" size="sm">
            <LuSettings size={14} /> Settings
          </AgentAIButton>
        }
      >
        {!user ? (
          <AgentAIAlert
            status="auth"
            title="Sign in required"
            description="Please sign in to access your dashboard."
            action={{
              label: "Sign In",
              onClick: handleLogin
            }}
          />
        ) : (
          <>
            <AgentAISection title="Quick Stats" accent="blue">
              <AgentAIStatGrid columns={{ base: 2, md: 4 }}>
                <AgentAIStatCard label="AGENTS" value="12" />
                <AgentAIStatCard label="RUNS TODAY" value="156" trend={{ value: '+23%', direction: 'up' }} />
                <AgentAIStatCard label="SUCCESS RATE" value="98.5%" />
                <AgentAIStatCard label="AVG RESPONSE" value="1.2s" />
              </AgentAIStatGrid>
            </AgentAISection>

            <AgentAITabs
              tabs={[
                { value: 'home', label: 'Home', icon: <LuHome size={14} /> },
                { value: 'agents', label: 'My Agents', icon: <LuBot size={14} /> },
              ]}
              value={activeTab}
              onValueChange={setActiveTab}
              mt={5}
            >
              <AgentAITabs.Content value="home" padding={4}>
                <Text m={0}>Your home content here...</Text>
              </AgentAITabs.Content>
              <AgentAITabs.Content value="agents" padding={4}>
                <Text m={0}>Your agents list here...</Text>
              </AgentAITabs.Content>
            </AgentAITabs>
          </>
        )}
      </AgentAIPageCard>

      {/* Footer */}
      <AgentAIFooter />
    </ChakraProvider>
  );
}

Backend Examples

Node.js + Express APIBackend

Express server with Agent.ai API integration for chat and web scraping

// server.js - Node.js Express Backend
const express = require('express');
const cors = require('cors');
const { AgentAiClient } = require('@agentai/agentai');

const app = express();
app.use(cors());
app.use(express.json());

// Initialize Agent.ai client
const client = new AgentAiClient(process.env.AGENT_API_KEY);

// Chat endpoint - powers your AI assistant
app.post('/api/chat', async (req, res) => {
  try {
    const { message, model = 'gpt4o' } = req.body;
    
    const response = await client.chat(message, { model });
    
    if (response.status === 200) {
      res.json({ success: true, result: response.results });
    } else {
      res.status(response.status).json({ 
        success: false, 
        error: response.error 
      });
    }
  } catch (error) {
    res.status(500).json({ success: false, error: error.message });
  }
});

// Company research endpoint
app.post('/api/research', async (req, res) => {
  try {
    const { domain } = req.body;
    
    // Fetch company info and web content in parallel
    const [companyInfo, webContent] = await Promise.all([
      client.action('getDomainInformation', { domain }),
      client.grabWebText(`https://${domain}`)
    ]);
    
    res.json({
      success: true,
      company: companyInfo.results,
      content: webContent.results?.substring(0, 1000)
    });
  } catch (error) {
    res.status(500).json({ success: false, error: error.message });
  }
});

// News endpoint
app.get('/api/news', async (req, res) => {
  try {
    const { query, dateRange = '7d' } = req.query;
    
    const response = await client.getGoogleNews(query, { dateRange });
    
    res.json({
      success: true,
      articles: response.results?.organic_results || []
    });
  } catch (error) {
    res.status(500).json({ success: false, error: error.message });
  }
});

app.listen(3001, () => {
  console.log('API server running on port 3001');
});

// package.json dependencies:
// npm install express cors @agentai/agentai

Python + Flask APIBackend

Flask server with Agent.ai API integration for AI-powered features

# app.py - Python Flask Backend
from flask import Flask, request, jsonify
from flask_cors import CORS
from agentai import AgentAiClient
import os

app = Flask(__name__)
CORS(app)

# Initialize Agent.ai client (uses AGENTAI_API_KEY env var)
client = AgentAiClient()

@app.route('/api/chat', methods=['POST'])
def chat():
    """Chat endpoint - powers your AI assistant"""
    try:
        data = request.get_json()
        message = data.get('message')
        model = data.get('model', 'gpt4o')
        
        response = client.chat(message, model=model)
        
        if response['status'] == 200:
            return jsonify({'success': True, 'result': response['results']})
        else:
            return jsonify({'success': False, 'error': response['error']}), response['status']
    except Exception as e:
        return jsonify({'success': False, 'error': str(e)}), 500

@app.route('/api/research', methods=['POST'])
def research():
    """Company research endpoint"""
    try:
        data = request.get_json()
        domain = data.get('domain')
        
        # Fetch company info
        company_info = client.get_company_info(domain)
        
        # Fetch web content
        web_content = client.grab_web_text(f'https://{domain}')
        
        return jsonify({
            'success': True,
            'company': company_info.get('results'),
            'content': web_content.get('results', '')[:1000]
        })
    except Exception as e:
        return jsonify({'success': False, 'error': str(e)}), 500

@app.route('/api/news', methods=['GET'])
def news():
    """News endpoint"""
    try:
        query = request.args.get('query')
        date_range = request.args.get('dateRange', '7d')
        
        response = client.get_google_news(query, date_range=date_range)
        
        return jsonify({
            'success': True,
            'articles': response.get('results', {}).get('organic_results', [])
        })
    except Exception as e:
        return jsonify({'success': False, 'error': str(e)}), 500

@app.route('/api/generate-image', methods=['POST'])
def generate_image():
    """Image generation endpoint"""
    try:
        data = request.get_json()
        prompt = data.get('prompt')
        
        response = client.generate_image(prompt)
        
        if response['status'] == 200:
            return jsonify({'success': True, 'image': response['results']})
        else:
            return jsonify({'success': False, 'error': response['error']}), response['status']
    except Exception as e:
        return jsonify({'success': False, 'error': str(e)}), 500

if __name__ == '__main__':
    app.run(port=3001, debug=True)

# requirements.txt:
# flask
# flask-cors
# agentai

Full Stack - React + BackendComplete

Connect your App SDK frontend to your backend API

// Frontend: Using App SDK with your backend
import { useState } from 'react';
import { 
  AgentAIAgentPage,
  AgentAISearchInput,
  AgentAISection,
  AgentAIStatGrid,
  AgentAIStatCard,
  AgentAIAlert,
  AgentAIInfoBanner
} from '@agentai/appsdk';

export default function ResearchApp() {
  const [loading, setLoading] = useState(false);
  const [data, setData] = useState(null);
  const [error, setError] = useState(null);

  const handleResearch = async (domain) => {
    setLoading(true);
    setError(null);
    
    try {
      // Call YOUR backend API (not Agent.ai directly)
      const response = await fetch('/api/research', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ domain })
      });
      
      const result = await response.json();
      
      if (result.success) {
        setData(result);
      } else {
        setError(result.error);
      }
    } catch (err) {
      setError(err.message);
    } finally {
      setLoading(false);
    }
  };

  return (
    <AgentAIAgentPage
      agentHeaderConfig={{
        name: 'Company Research',
        description: 'Powered by Agent.ai API',
        version: '1.0'
      }}
    >
      <AgentAISearchInput
        placeholder="Enter a domain..."
        onSearch={handleResearch}
        actionLabel="Research"
        isLoading={loading}
      />

      {error && (
        <AgentAIAlert status="error" title="Error" description={error} mt={4} />
      )}

      {data && (
        <AgentAISection title="Results" accent="blue" mt={4}>
          <AgentAIStatGrid columns={2}>
            <AgentAIStatCard label="COMPANY" value={data.company?.name || 'N/A'} />
            <AgentAIStatCard label="INDUSTRY" value={data.company?.category?.industry || 'N/A'} />
          </AgentAIStatGrid>
        </AgentAISection>
      )}
    </AgentAIAgentPage>
  );
}

// Architecture:
// ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
// │   React     │───▶│  Your API   │───▶│  Agent.ai   │
// │  (appsdk)   │    │  (Backend)  │    │     API     │
// └─────────────┘    └─────────────┘    └─────────────┘

LLM Implementation Context

Copy and provide this context to any LLM (Claude, GPT-4, etc.) for AI-assisted implementation.

# Agent.ai App SDK - LLM Implementation Guide

## Overview
The Agent.ai App SDK provides pre-built React components for building applications that match the Agent.ai design system. All components are standalone with no external dependencies beyond Chakra UI.

## Installation
```jsx
import { 
  // Layout
  AgentAIHeader, AgentAIFooter, AgentAIPageCard, AgentAISection,
  // Form
  AgentAIButton, AgentAIInput, AgentAISelect, AgentAISwitch,
  // Navigation
  AgentAITabs, AgentAIVerticalTabs,
  // Agent
  AgentAIAgentHeader, AgentAIAgentPage, AgentAIAgentAvatar,
  // Labs/App
  AgentAILabsHero, AgentAIAppCard, AgentAIAppCardGrid, AgentAISearchInput,
  // Data Display
  AgentAIStatCard, AgentAIMetricCard, AgentAIStatGrid,
  AgentAIPill, AgentAITagCard, AgentAISuggestionPills,
  AgentAIDataTable, AgentAIBarChart, AgentAITimeline,
  // Feedback
  AgentAIAlert, AgentAIInfoBanner,
  // Display
  AgentAIAvatar, AgentAICard,
  defaultTheme
} from '@agentai/appsdk';
```

## Theme Configuration
{
  "name": "Agent.ai SDK Theme",
  "version": "1.3.1",
  "colors": {
    "primary": "#1A3643",
    "secondary": "#D96C4F",
    "background": {
      "header": "#0A1B22",
      "footer": "#ffffff",
      "page": "#ffffff",
      "card": "#f8fafc",
      "cardHover": "#f1f5f9"
    },
    "text": {
      "primary": "#1A3643",
      "secondary": "#4A5568",
      "light": "#ffffff",
      "muted": "#718096",
      "heading": "#0f172a",
      "label": "#94a3b8"
    },
    "link": {
      "default": "#0064C7",
      "hover": "#003E7B"
    },
    "border": {
      "light": "#E2E8F0",
      "default": "#CBD5E0"
    },
    "button": {
      "primary": {
        "background": "#D96C4F",
        "text": "#ffffff",
        "hover": "#d95632"
      },
      "secondary": {
        "background": "transparent",
        "text": "#ffffff",
        "border": "#ffffff",
        "hover": "rgba(255, 255, 255, 0.1)"
      }
    },
    "accent": {
      "blue": "#4f46e5",
      "purple": "#7c3aed",
      "green": "#22c55e",
      "orange": "#f97316",
      "red": "#ef4444",
      "cyan": "#06b6d4",
      "pink": "#ec4899"
    },
    "status": {
      "info": {
        "bg": "#eff6ff",
        "border": "#bfdbfe",
        "text": "#1e40af",
        "icon": "#3b82f6"
      },
      "success": {
        "bg": "#f0fdf4",
        "border": "#bbf7d0",
        "text": "#166534",
        "icon": "#22c55e"
      },
      "warning": {
        "bg": "#fffbeb",
        "border": "#fde68a",
        "text": "#92400e",
        "icon": "#f59e0b"
      },
      "error": {
        "bg": "#fef2f2",
        "border": "#fecaca",
        "text": "#991b1b",
        "icon": "#ef4444"
      },
      "auth": {
        "bg": "#fef9e7",
        "border": "#fde68a",
        "text": "#92400e",
        "icon": "#92400e"
      }
    },
    "pill": {
      "gray": {
        "bg": "#f1f5f9",
        "border": "#e2e8f0",
        "text": "#334155"
      },
      "blue": {
        "bg": "#eff6ff",
        "border": "#bfdbfe",
        "text": "#1e40af"
      },
      "green": {
        "bg": "#f0fdf4",
        "border": "#bbf7d0",
        "text": "#166534"
      },
      "orange": {
        "bg": "#fff7ed",
        "border": "#fed7aa",
        "text": "#9a3412"
      },
      "red": {
        "bg": "#fef2f2",
        "border": "#fecaca",
        "text": "#991b1b"
      },
      "purple": {
        "bg": "#faf5ff",
        "border": "#e9d5ff",
        "text": "#6b21a8"
      }
    },
    "chart": {
      "blue": "#3b82f6",
      "green": "#22c55e",
      "red": "#ef4444",
      "orange": "#f97316",
      "purple": "#8b5cf6"
    }
  },
  "fonts": {
    "heading": "Inter, Arial, Helvetica, sans-serif",
    "body": "Inter, Arial, Helvetica, sans-serif"
  },
  "spacing": {
    "headerHeight": "64px",
    "containerMaxWidth": "1280px",
    "containerPadding": "16px"
  },
  "borderRadius": {
    "sm": "4px",
    "md": "8px",
    "lg": "12px",
    "full": "9999px"
  },
  "shadows": {
    "sm": "0 1px 2px rgba(0, 0, 0, 0.05)",
    "md": "0 4px 6px rgba(0, 0, 0, 0.1)",
    "lg": "0 10px 15px rgba(0, 0, 0, 0.1)"
  },
  "branding": {
    "logoLight": "https://agent.ai/logo-2025/agent-ai-logo-2025-white.svg",
    "logoDark": "https://agent.ai/logo-2025/agent-ai-logo-new-dark.svg",
    "logoAlt": "Agent.ai"
  },
  "navigation": {
    "baseUrl": "https://agent.ai",
    "links": [
      {
        "href": "https://agent.ai/agents",
        "label": "Agent Network",
        "external": true
      },
      {
        "href": "https://agent.ai/builders",
        "label": "Builder Network",
        "external": true
      },
      {
        "href": "https://blog.agent.ai",
        "label": "Blog",
        "external": true
      },
      {
        "href": "https://agent.ai/builder/agents",
        "label": "Agent Builder",
        "external": true,
        "requiresAuth": true
      }
    ]
  },
  "userMenu": {
    "baseUrl": "https://agent.ai",
    "sections": [
      {
        "title": "Account",
        "items": [
          {
            "label": "Profile",
            "href": "https://agent.ai/human/{username}",
            "icon": "user",
            "external": true
          },
          {
            "label": "Settings",
            "href": "https://agent.ai/user/settings",
            "icon": "settings",
            "external": true
          },
          {
            "label": "Connections",
            "href": "https://agent.ai/user/connections",
            "icon": "plug",
            "external": true
          }
        ]
      },
      {
        "title": "Agents",
        "items": [
          {
            "label": "Runs",
            "href": "https://agent.ai/user/agent-runs",
            "icon": "running",
            "external": true
          },
          {
            "label": "Subscriptions",
            "href": "https://agent.ai/user/agent-subscriptions",
            "icon": "credit-card",
            "featureFlag": "agent_subscriptions_page",
            "external": true
          },
          {
            "label": "Team",
            "href": "https://agent.ai/user/team",
            "icon": "users",
            "external": true
          }
        ]
      },
      {
        "title": "Builder",
        "requiresBuilder": true,
        "items": [
          {
            "label": "Knowledge & Files",
            "href": "https://agent.ai/builder/files",
            "icon": "database",
            "external": true
          },
          {
            "label": "Snippets",
            "href": "https://agent.ai/builder/snippets",
            "icon": "code",
            "external": true
          },
          {
            "label": "Secrets",
            "href": "https://agent.ai/builder/secrets",
            "icon": "key",
            "external": true
          },
          {
            "label": "Serverless Functions",
            "href": "https://agent.ai/builder/serverless",
            "icon": "server",
            "external": true
          }
        ]
      },
      {
        "title": "Resources",
        "items": [
          {
            "label": "Community",
            "href": "https://community.agent.ai/",
            "icon": "group",
            "external": true
          },
          {
            "label": "Suggest An Agent",
            "href": "https://agent.ai/suggest-an-agent",
            "icon": "lightbulb",
            "external": true
          },
          {
            "label": "Give Feedback",
            "href": "https://agent.ai/feedback",
            "icon": "message-square",
            "external": true
          }
        ]
      }
    ]
  },
  "footer": {
    "baseUrl": "https://agent.ai",
    "description": "Agent.ai is the #1 professional network for AI agents. Here, you can build, discover, and activate trustworthy AI agents to do useful things.",
    "copyright": "© AgentAI Platform, Inc",
    "links": {
      "terms": "https://agent.ai/terms",
      "privacy": "https://agent.ai/privacy-policy"
    },
    "resources": [
      {
        "label": "Documentation",
        "href": "https://docs.agent.ai"
      },
      {
        "label": "Community",
        "href": "https://community.agent.ai"
      }
    ],
    "social": [
      {
        "platform": "twitter",
        "href": "https://x.com/AgentDotAi"
      },
      {
        "platform": "facebook",
        "href": "https://www.facebook.com/profile.php?id=61561787124174"
      },
      {
        "platform": "linkedin",
        "href": "https://www.linkedin.com/company/agentdotai/"
      }
    ]
  }
}

## Component Reference

### AgentAIHeader
Full-featured navigation header with logo, nav links, user authentication, dropdown menus, and responsive mobile support.

Props:
- user: { name, picture, username } | null - User object or null for logged out
- currentPath: string - Current page path for active nav highlighting
- navLinks: Array<{ href, label, external?, requiresAuth? }> - Custom nav links
- showLogin: boolean - Show login button when logged out (default: true)
- showSignup: boolean - Show signup button when logged out (default: true)
- loginUrl: string - Custom login URL (used if useCustomAuth is false)
- signupUrl: string - Custom signup URL (used if useCustomAuth is false)
- onLogout: () => void - Callback when logout is clicked
- onNavigate: (href) => void - Callback when nav link is clicked
- homeUrl: string - Logo link destination (default: /)
- logoSrc: string - Custom logo image URL
- logoAlt: string - Logo alt text
- headerHeight: string - Custom header height
- containerMaxWidth: string - Max width of header content
- theme: object - Theme overrides

Custom Authentication Props (NEW in v1.2.1):
- onLogin: () => void - Custom login handler (replaces default navigation)
- onSignup: () => void - Custom signup handler (replaces default navigation)
- useCustomAuth: boolean - When true, only use callbacks instead of URL navigation
- isAuthLoading: boolean - Show loading state on auth buttons
- loginLabel: string - Custom login button text (default: "Sign In")
- signupLabel: string - Custom signup button text (default: "Sign Up")

User Object:
```jsx
const user = {
  name: 'John Doe',       // Display name
  picture: '/avatar.jpg', // Avatar image URL
  username: 'johndoe'     // Used in profile URLs
};
```

Nav Link Object:
```jsx
const navLinks = [
  { href: '/dashboard', label: 'Dashboard' },
  { href: '/agents', label: 'Agents', requiresAuth: true },
  { href: 'https://docs.example.com', label: 'Docs', external: true }
];
```

Basic Examples:
```jsx
// Logged out
<AgentAIHeader showLogin={true} showSignup={true} />

// Logged in
<AgentAIHeader 
  user={{ name: 'John', picture: '/avatar.jpg', username: 'john' }}
  currentPath="/dashboard"
  onLogout={() => signOut()}
/>

// Custom nav links
<AgentAIHeader 
  user={user}
  navLinks={[
    { href: '/home', label: 'Home' },
    { href: '/about', label: 'About' }
  ]}
/>

// Theme customization
<AgentAIHeader 
  theme={{
    colors: { background: { header: '#1a1a2e' } },
    branding: { logoLight: '/my-logo.svg' }
  }}
/>

// Custom authentication (OAuth, partner APIs)
const { user, login, logout, loading } = useAuth();
const headerUser = user ? {
  name: user.display_name,
  picture: user.avatar_url,
  username: user.email?.split('@')[0]
} : null;

<AgentAIHeader
  user={headerUser}
  onLogin={login}
  onSignup={() => login({ screen_hint: 'signup' })}
  onLogout={logout}
  useCustomAuth={true}
  isAuthLoading={loading}
  showLogin={!loading && !user}
  showSignup={!loading && !user}
/>

// Custom button labels
<AgentAIHeader
  onLogin={handleLogin}
  onSignup={handleSignup}
  useCustomAuth={true}
  loginLabel="Log In"
  signupLabel="Get Started Free"
/>
```

Features:
- Responsive mobile menu with hamburger toggle
- User dropdown with avatar and menu sections
- Active nav state highlighting
- External link support with icon indicator
- Skip-to-content accessibility link
- Custom authentication flow support (OAuth, SSO, partner APIs)
- Loading states for auth buttons

### AgentAIFooter
Site footer with branding, resource links, and social media.
No props - all content is configured via the theme file.

Example:
```jsx
<AgentAIFooter />
```

### AgentAIButton
Styled button with multiple variants.

Props:
- variant: 'primary' | 'secondary' | 'tertiary' | 'ghost' | 'danger' | 'danger-outline' | 'link'
- size: 'xs' | 'sm' | 'md' | 'lg'
- leftIcon: ReactNode
- rightIcon: ReactNode
- isLoading: boolean
- loadingText: string
- isDisabled: boolean

### AgentAIInput
Text input with label, helper text, and validation.

Props:
- label: string
- placeholder: string
- helperText: string
- errorText: string
- size: 'sm' | 'md' | 'lg'
- isRequired: boolean
- isInvalid: boolean
- isDisabled: boolean

### AgentAISelect
Dropdown select with options.

Props:
- label: string
- placeholder: string
- options: Array<string | { value, label }>
- value: string
- onValueChange: (value: string) => void

### AgentAISwitch
Toggle switch with label and description.

Props:
- label: string
- description: string
- checked: boolean
- onCheckedChange: (checked: boolean) => void

### AgentAITabs
Horizontal tabbed navigation with icons.

Props:
- tabs: Array<{ value, label, icon?, disabled? }>
- value: string
- onValueChange: (value: string) => void

### AgentAIVerticalTabs
Vertical sidebar navigation for component lists. Supports left or right positioning.

Props:
- items: Array<{ value, label, icon?, description?, disabled? }>
- value: string
- onValueChange: (value: string) => void
- position: 'left' | 'right' (default: 'left')
- sidebarWidth: string (default: '220px')

### AgentAIPageCard
Full-page card layout for standalone pages.

Props:
- icon: ReactNode
- title: string
- description: string
- headerAction: ReactNode
- maxWidth: string (default: '1200px')

### AgentAIAvatar
User avatar with image or initials fallback.

Props:
- name: string - Used for initials fallback
- src: string - Image URL
- size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'

### AgentAIAgentHeader
Displays agent information in a header format with avatar, name, description, stats, and actions.
Used inside agent pages to show agent identity. Supports both static props and automatic live data fetching.

**Two Modes:**
1. **Static Mode** - Pass agent data directly via props
2. **Live Mode** - Pass just agentId to auto-fetch from Agent.ai API

Props (Static):
- agent: object - Agent data object (or use individual props below)
- name: string - Agent display name
- icon: string - Agent avatar/icon URL
- description: string - Agent description text
- version: string - Version number to display
- executions: number - Total execution count (shown in stats)
- approximateTime: number - Average run time in seconds
- reviewScore: number - Average review score (0-5)

Props (Live Data - auto-fetch):
- agentId: string - Agent ID to fetch (triggers automatic API call)
- apiHost: string - API host URL (default: https://api.agent.ai)
- accessToken: string - Optional access token for auth requests
- refetchInterval: number - Optional auto-refetch interval in ms
- onAgentLoaded: (agent: Agent) => void - Callback when data loads
- onAgentError: (error: Error) => void - Callback on fetch error

Props (Display):
- showStats: boolean - Show execution stats (default: true)
- showActions: boolean - Show action button row (default: true)
- showFollowButton: boolean - Show follow/star button
- showTeamButton: boolean - Show add to team button
- isFollowing: boolean - Current follow state
- isTeamMember: boolean - Current team membership state
- onFollow, onUnfollow, onTeamAdd, onTeamRemove - Callbacks

Props (Subscribe/Trial):
- showSubscribe: boolean - Show subscribe button
- subscribePrice: string - Monthly price (e.g., "$9.99")
- onSubscribe: () => void - Subscribe button callback
- showTrialInfo: boolean - Show trial runs info
- runsRemaining, trialLimit: number - Trial run data

Static Example:
```jsx
<AgentAIAgentHeader
  name="Research Assistant"
  icon="/agent-icon.png"
  description="An AI-powered research assistant"
  version="2.1"
  executions={15420}
  approximateTime={45}
  reviewScore={4.8}
/>
```

Live Data Example:
```jsx
// Just pass agentId - data is fetched automatically!
<AgentAIAgentHeader
  agentId="flux-image-generator"
  onAgentLoaded={(agent) => console.log('Agent loaded:', agent)}
/>

// With auto-refetch every 30 seconds
<AgentAIAgentHeader
  agentId="flux-image-generator"
  refetchInterval={30000}
/>

// With custom API host
<AgentAIAgentHeader
  agentId="my-agent"
  apiHost="https://custom-api.example.com"
  accessToken={userToken}
/>
```

### AgentAIAgentPage
A complete page shell for agent implementations with site header, agent header, body, and site footer.
Uses config objects for cleaner prop organization.

Config Props:
- headerConfig: object - Props passed to AgentAIHeader (user, onLogout, currentPath, navLinks, etc.)
- footerConfig: object - Props passed to AgentAIFooter
- agentHeaderConfig: object - Props passed to AgentAIAgentHeader (name, icon, description, executions, etc.)

Visibility Props:
- showSiteHeader: boolean - Show AgentAIHeader (default: true)
- showSiteFooter: boolean - Show AgentAIFooter (default: true)
- showAgentHeader: boolean - Show agent header (default: true)

Layout Props:
- children: ReactNode - Your agent implementation content
- cardFooter: ReactNode - Footer inside card (not site footer)
- maxWidth: string - Container max width (default: '960px')
- minHeight: string - Minimum page height (default: '100vh', use 'auto' for embedded)
- backgroundColor: string - Card background color (default: 'white')
- pageBackgroundColor: string - Page background color override
- cardBorderColor: string - Card border color (default: '#e2e8f0')
- cardBorderRadius: string/object - Card border radius
- bodyPadding: string/object - Card body padding

Helper Components:
- AgentAIAgentPageSection: For grouping content with consistent spacing
- AgentAIAgentPageForm: Form wrapper with proper styling
- AgentAIAgentPageResults: Container for displaying results

Example:
```jsx
<AgentAIAgentPage
  headerConfig={{
    user: currentUser,
    onLogout: handleLogout,
    currentPath: '/agent/my-agent'
  }}
  agentHeaderConfig={{
    name: 'My Custom Agent',
    icon: '/agent-icon.png',
    description: 'Your agent description',
    version: '1.0',
    executions: 1000
  }}
>
  <AgentAIInput label="Query" />
  <AgentAIButton type="submit">Run Agent</AgentAIButton>
</AgentAIAgentPage>

// Without site header/footer
<AgentAIAgentPage
  showSiteHeader={false}
  showSiteFooter={false}
  agentHeaderConfig={{ name: 'Agent' }}
>
  {children}
</AgentAIAgentPage>
```

### AgentAIAgentAvatar
Displays agent icons with CDN optimization and graceful fallback handling.
Tries Cloudflare CDN first, then original URL, then default icon.

Props:
- src: string - Image URL (supports CDN optimization)
- alt: string - Alt text for accessibility
- size: 'sm' | 'md' | 'lg' | 'xl' | object - Predefined or custom size
- borderWidth: string - Border width (default: '6px')
- borderColor: string - Border color (default: 'white')
- showBorder: boolean - Show border (default: true)
- transform: string - CDN transform parameters

Example:
```jsx
<AgentAIAgentAvatar
  src="https://example.com/agent-icon.png"
  size="md"
  alt="Agent Name"
/>
```

### AgentAILabsHero
A hero section for mini-apps/labs pages with search functionality and call-to-action.
Used for landing pages showcasing apps or tools.

Props:
- label: string - Top label text (default: "AGENT.AI LABS")
- title: string - Main heading text
- subtitle: string - Subtitle/description
- showSearch: boolean - Toggle search input (default: true)
- searchPlaceholder: string - Search input placeholder
- onSearch: (query: string) => void - Search submit callback
- ctaLabel: string - CTA button text
- ctaHref: string - CTA link URL
- onCtaClick: () => void - CTA click callback
- helperText: string - Helper text before links
- helperLinks: Array<{ label, href, prefix?, suffix? }> - Inline links in helper text
- showSparkles: boolean - Show sparkle decoration (default: true)
- backgroundColor: string - Card background (default: white)
- labelColor: string - Label color (default: #3b82f6)
- maxWidth: string - Max container width (default: 1200px)

Example:
```jsx
<AgentAILabsHero
  label="AGENT.AI LABS"
  title="Launch mini-apps built for instant utility"
  subtitle="A curated set of opinionated tools that feel consistent, fast, and fun."
  searchPlaceholder="Search an app or workflow"
  onSearch={(query) => handleSearch(query)}
  ctaLabel="Explore apps"
  onCtaClick={() => navigate('/apps')}
  helperText="Try "
  helperLinks={[
    { label: 'DadJoke.ai', href: '/apps/dadjoke', suffix: ' for playful prompts or ' },
    { label: 'Teamwork', href: '/apps/teamwork', suffix: ' for workflows.' }
  ]}
/>

// Without search
<AgentAILabsHero
  label="FEATURED"
  title="Discover amazing agents"
  subtitle="Hand-picked by our team"
  showSearch={false}
  ctaLabel="Browse all"
  ctaHref="/agents"
/>
```

### AgentAIAppCard
Cards for displaying mini-apps with status badges (NEW, BETA, COMING SOON, etc.).
Includes hover effects, disabled states, and action links.

Props:
- title: string - Card title
- description: string - Card description text
- icon: ReactNode - Optional icon element
- status: 'new' | 'beta' | 'coming-soon' | 'alpha' | 'live' | 'deprecated' - Badge type
- statusLabel: string - Custom badge text override
- href: string - Card link URL
- onClick: () => void - Click callback
- actionLabel: string - Action link text (default: "Launch app")
- isExternal: boolean - Open link in new tab
- isDisabled: boolean - Disable card interactions
- backgroundColor: string - Card background (default: white)
- showArrow: boolean - Show arrow icon (default: true)
- variant: 'default' | 'compact' | 'featured' - Card size variant

Status Badge Colors:
- new: Green (#22c55e)
- beta: Orange (#f97316)
- coming-soon: Cyan (#06b6d4)
- alpha: Purple (#8b5cf6)
- live: Blue (#3b82f6)
- deprecated: Gray (#6b7280)

Example:
```jsx
<AgentAIAppCard
  title="DadJoke.ai"
  description="Use AI to generate pun-believably bad jokes for any topic."
  status="new"
  href="/apps/dadjoke"
  actionLabel="Launch app"
/>

// Disabled coming soon
<AgentAIAppCard
  title="Company Research"
  description="Drop in a company domain for a synthesized dossier."
  status="coming-soon"
  isDisabled
/>
```

### AgentAIAppCardGrid
Responsive grid container for organizing app cards.

Props:
- columns: number | { base?, md?, lg? } - Grid columns (default: { base: 1, md: 2 })
- gap: number | string | { base?, md? } - Grid gap (default: { base: 4, md: 6 })

Example:
```jsx
<AgentAIAppCardGrid columns={{ base: 1, md: 2, lg: 3 }} gap={4}>
  <AgentAIAppCard title="App 1" status="new" href="/app1" />
  <AgentAIAppCard title="App 2" status="beta" href="/app2" />
  <AgentAIAppCard title="App 3" status="live" href="/app3" />
</AgentAIAppCardGrid>
```

### AgentAIFeatureCard
A larger gradient card variant for featured content and call-to-action.

Props:
- title: string - Card title
- description: string - Card description
- icon: ReactNode - Icon element
- href: string - Link URL
- onClick: () => void - Click callback
- actionLabel: string - Action text (default: "Learn more")
- backgroundColor: string - Background (supports CSS gradients)
- textColor: string - Text color (default: white)

Example:
```jsx
import { LuSparkles } from 'react-icons/lu';

<AgentAIFeatureCard
  title="Build Your Own Agent"
  description="Create custom AI agents with our intuitive builder. No code required."
  actionLabel="Get started"
  href="/builder"
  icon={<LuSparkles size={32} />}
  backgroundColor="linear-gradient(135deg, #3b82f6 0%, #8b5cf6 100%)"
/>
```

### AgentAIAlert
Notification alerts for messages, warnings, and actions.
Supports multiple status types with automatic styling and optional action buttons.

Props:
- status: 'info' | 'success' | 'warning' | 'error' | 'auth' - Alert type/color scheme
- title: string - Alert title
- description: string - Alert description text
- children: ReactNode - Custom content
- action: { label, onClick?, href?, icon?, variant? } - Action button config
- icon: ReactNode - Custom icon override
- showIcon: boolean - Show status icon (default: true)
- isDismissible: boolean - Show dismiss button
- onDismiss: () => void - Dismiss callback

Status Colors:
- info: Blue (#3b82f6)
- success: Green (#22c55e)
- warning: Yellow/amber (#f59e0b)
- error: Red (#ef4444)
- auth: Special cream/yellow for login prompts

Example:
```jsx
// Auth/login prompt (matches Agent.ai design)
<AgentAIAlert
  status="auth"
  title="Sign in required"
  description="Use your Agent.ai login to generate reports."
  action={{
    label: "Login to continue",
    onClick: handleLogin,
    icon: <FiLogIn size={14} />
  }}
/>

// Simple status alerts
<AgentAIAlert status="success" title="Success!" description="Action completed." />
<AgentAIAlert status="error" title="Error" description="Something went wrong." />

// Dismissible
<AgentAIAlert
  status="info"
  title="New feature"
  description="Check out our dashboard."
  isDismissible
  onDismiss={() => setVisible(false)}
/>
```

### AgentAISection
Section wrapper with title and colored accent underline.

Props:
- title: string - Section title
- icon: ReactNode - Optional icon before title
- accent: 'blue' | 'purple' | 'green' | 'orange' | 'red' | 'cyan' | 'pink'
- accentColor: string - Custom color override
- headerAction: ReactNode - Action in header
- spacing: number - Gap between header and content

Example:
```jsx
<AgentAISection title="Web Traffic" accent="blue">
  <YourContent />
</AgentAISection>

<AgentAISection title="HubSpot Info" accent="purple">
  <StatCards />
</AgentAISection>
```

### AgentAIStatCard / AgentAIMetricCard / AgentAIStatGrid
Cards for displaying statistics and KPIs.

AgentAIStatCard Props:
- label: string - Uppercase label text
- value: string - Main value
- subValue: string - Secondary text
- trend: { value: string, direction: 'up' | 'down' | 'neutral' }
- size: 'sm' | 'md' | 'lg'
- showAccent: boolean - Show left border
- accentColor: string - Border color

AgentAIMetricCard Props:
- label: string - Label text
- value: string - Value (negatives auto-colored red)
- accent: 'blue' | 'green' | 'red' | 'orange' | 'purple'
- size: 'md' | 'lg' | 'xl'

Example:
```jsx
<AgentAIStatGrid columns={{ base: 2, md: 4 }}>
  <AgentAIStatCard label="COMPANY" value="HubSpot" />
  <AgentAIStatCard label="ADDED" value="May 05, 2024" subValue="05:56 PM" />
  <AgentAIStatCard label="VISITORS" value="34.8M" trend={{ value: '+5%', direction: 'up' }} />
</AgentAIStatGrid>

<AgentAIMetricCard label="GROWTH" value="-5.2%" accent="red" />
```

### AgentAIPill / AgentAITagCard / AgentAISuggestionPills
Clickable pills and tag displays.

AgentAIPill Props:
- variant: 'default' | 'selected' | 'outline' | 'subtle'
- color: 'gray' | 'blue' | 'green' | 'orange' | 'red' | 'purple'
- size: 'sm' | 'md' | 'lg'
- onClick: function
- href: string
- leftIcon, rightIcon: ReactNode

Example:
```jsx
<AgentAIPill>hubspot.com</AgentAIPill>
<AgentAIPill variant="selected" color="blue">Selected</AgentAIPill>

<AgentAITagCard title="Analytics">
  <AgentAIPill color="green">Google Analytics</AgentAIPill>
  <AgentAIPill color="green">Hotjar</AgentAIPill>
</AgentAITagCard>

<AgentAISuggestionPills
  suggestions={['hubspot.com', 'anthropic.com']}
  onSelect={(value) => setValue(value)}
/>
```

### AgentAIInfoBanner
Status banner with icon and action.

Props:
- status: 'info' | 'success' | 'warning' | 'error'
- text: string - Banner message
- icon: ReactNode - Custom icon
- action: { label, onClick?, href?, variant? }
- showIcon: boolean

Example:
```jsx
<AgentAIInfoBanner
  status="success"
  text="Found in HubSpot CRM"
  action={{ label: "View in HubSpot", onClick: handleClick }}
/>
```

### AgentAITimeline
Timeline for news feeds and activity.

Example:
```jsx
<AgentAITimeline>
  <AgentAITimeline.Item
    date="November 24, 2025"
    title="HubSpot Reports Q3 Results"
    source="Business Wire"
    description="Q3 2025 results with revenue exceeding expectations..."
    icon="📰"
    accentColor="#4f46e5"
  />
</AgentAITimeline>
```

### AgentAIDataTable
Simple data table.

Props:
- columns: Array<{ key, header, width?, align?, render?, color?, bold? }>
- data: Array<object>
- compact: boolean
- striped: boolean

Example:
```jsx
<AgentAIDataTable
  columns={[
    { key: 'keyword', header: 'Keyword', width: '40%' },
    { key: 'position', header: 'Position', align: 'center' },
    { key: 'volume', header: 'Search Volume', align: 'right' },
  ]}
  data={[
    { keyword: 'hubspot', position: '#1', volume: '301,000' },
    { keyword: 'crm', position: '#2', volume: '450,000' },
  ]}
/>
```

### AgentAIBarChart
CSS-based bar chart (no external library).

Props:
- data: Array<{ label, value, color? }>
- height: number
- color: string - Default bar color
- showLabels: boolean
- showValues: boolean
- barGap: number

Example:
```jsx
<AgentAIBarChart
  data={[
    { label: 'May', value: 35000000 },
    { label: 'Jun', value: 32000000 },
    { label: 'Jul', value: 28000000 },
  ]}
  color="#3b82f6"
  height={200}
/>
```

### AgentAISearchInput
Search input with suggestions and action button.

Props:
- value, onChange - Controlled value
- onSearch: (value) => void - Search submit
- placeholder: string
- helperText: string - Shown below input
- suggestions: string[] - Suggestion pills
- suggestionLabel: string - Label before suggestions
- onSuggestionClick: (value) => void
- actionLabel: string - Button text
- isLoading: boolean - Show loading spinner

Example:
```jsx
<AgentAISearchInput
  placeholder="Enter a domain..."
  helperText="Minimum 2 characters required"
  suggestions={['hubspot.com', 'anthropic.com', 'langchain.com']}
  onSearch={(value) => runSearch(value)}
  actionLabel="Go"
  isLoading={searching}
/>
```

### AgentAICard
Content card container with optional header.

Props:
- title: string - Card title
- subtitle: string - Card subtitle
- headerAction: ReactNode - Action element in header
- padding: number | string - Card body padding (default: 4)
- variant: 'default' | 'outline' | 'elevated' - Card style

Example:
```jsx
<AgentAICard title="Settings" subtitle="Manage your preferences">
  <YourContent />
</AgentAICard>
```

### AgentAIPillGroup
Container for grouping pills with consistent spacing.

Props:
- spacing: number - Gap between pills (default: 2)
- wrap: boolean - Allow wrapping (default: true)

Example:
```jsx
<AgentAIPillGroup spacing={2}>
  <AgentAIPill>Option 1</AgentAIPill>
  <AgentAIPill>Option 2</AgentAIPill>
</AgentAIPillGroup>
```

### AgentAIMiniBarChart
Compact inline bar chart for small spaces.

Props:
- values: number[] - Array of values
- color: string - Bar color (default: #3b82f6)
- height: number - Chart height in px (default: 24)
- barWidth: number - Width of each bar (default: 4)
- gap: number - Gap between bars (default: 2)

Example:
```jsx
<AgentAIMiniBarChart 
  values={[10, 20, 15, 30, 25, 18]} 
  color="#22c55e" 
  height={20} 
/>
```

### AgentAISparkline
Horizontal dot/line chart for trend visualization.

Props:
- values: number[] - Array of values
- color: string - Dot color (default: #22c55e)
- height: number - Chart height in px (default: 20)
- dotSize: number - Dot diameter in px (default: 4)

Example:
```jsx
<AgentAISparkline values={[10, 20, 15, 30, 25]} color="#3b82f6" />
```

### AgentAIDataTableTitle
Title component for data tables with optional icon.

Props:
- children: ReactNode - Title text
- icon: ReactNode - Optional icon

Example:
```jsx
<AgentAIDataTableTitle icon={<LuSearch size={14} />}>
  Search Keyword Analysis
</AgentAIDataTableTitle>
<AgentAIDataTable columns={[...]} data={[...]} />
```

### AgentAITimelineItem
Individual item for AgentAITimeline (also accessible as AgentAITimeline.Item).

Props:
- date: string - Date string (e.g., "November 24, 2025")
- dateSubtext: string - Secondary date text
- title: string - Item title
- source: string - Source attribution (uppercase display)
- description: string - Description text
- icon: ReactNode | string - Icon or emoji
- href: string - Link URL
- onClick: () => void - Click callback
- accentColor: string - Left border color (default: #4f46e5)

## Color Palette (from appsdk-theme.json)

Primary Colors:
- primary: #1A3643 (barnacle - dark text)
- secondary: #D96C4F (terracotta - CTAs)

Status Colors:
- info: { bg: #eff6ff, border: #bfdbfe, text: #1e40af, icon: #3b82f6 }
- success: { bg: #f0fdf4, border: #bbf7d0, text: #166534, icon: #22c55e }
- warning: { bg: #fffbeb, border: #fde68a, text: #92400e, icon: #f59e0b }
- error: { bg: #fef2f2, border: #fecaca, text: #991b1b, icon: #ef4444 }
- auth: { bg: #fef9e7, border: #fde68a, text: #92400e, icon: #92400e }

Pill Colors:
- gray: { bg: #f1f5f9, border: #e2e8f0, text: #334155 }
- blue: { bg: #eff6ff, border: #bfdbfe, text: #1e40af }
- green: { bg: #f0fdf4, border: #bbf7d0, text: #166534 }
- orange: { bg: #fff7ed, border: #fed7aa, text: #9a3412 }
- red: { bg: #fef2f2, border: #fecaca, text: #991b1b }
- purple: { bg: #faf5ff, border: #e9d5ff, text: #6b21a8 }

Accent Colors:
- blue: #4f46e5
- purple: #7c3aed
- green: #22c55e
- orange: #f97316
- red: #ef4444
- cyan: #06b6d4
- pink: #ec4899

Chart Colors:
- blue: #3b82f6
- green: #22c55e
- red: #ef4444
- orange: #f97316
- purple: #8b5cf6

Background Colors:
- header: #0A1B22
- footer: #ffffff
- page: #ffffff
- card: #f8fafc
- cardHover: #f1f5f9

Text Colors:
- primary: #1A3643
- secondary: #4A5568
- light: #ffffff
- muted: #718096
- heading: #0f172a
- label: #94a3b8

Border Colors:
- light: #E2E8F0
- default: #CBD5E0

## Best Practices

1. **Chakra UI Provider**: Always wrap your app with ChakraProvider
   ```jsx
   <ChakraProvider>
     <App />
   </ChakraProvider>
   ```

2. **Text Margins**: Always set m={0} on Text components to avoid Chakra defaults
   ```jsx
   <Text fontSize="14px" m={0}>Content</Text>
   ```

3. **Theme Colors**: Use theme colors from appsdk-theme.json for consistency
   ```jsx
   <Box bg={theme.colors.background.card} color={theme.colors.text.primary}>
   ```

4. **Responsive Props**: Use object syntax for responsive values
   ```jsx
   <Grid templateColumns={{ base: '1fr', md: 'repeat(2, 1fr)', lg: 'repeat(3, 1fr)' }}>
   ```

5. **Loading States**: Use isLoading prop for buttons and inputs
   ```jsx
   <AgentAIButton isLoading={submitting} loadingText="Submitting...">
   ```

6. **Custom Auth**: For OAuth/SSO, use useCustomAuth with onLogin/onSignup callbacks
   ```jsx
   <AgentAIHeader useCustomAuth onLogin={handleOAuth} onSignup={handleSignup} />
   ```

7. **Agent Pages**: Use AgentAIAgentPage for consistent agent interfaces
   ```jsx
   <AgentAIAgentPage agentHeaderConfig={{ agentId: 'your-agent' }}>
     {/* Your agent UI */}
   </AgentAIAgentPage>
   ```

## Version
SDK Version: 1.3.1

Header

Full-featured navigation header with logo, nav links, user authentication, dropdown menus, and responsive mobile support. The header state is controlled by the user prop - pass null for logged out, or a user object for logged in.

Logged Out (user=null)

Shows Sign In and Sign Up buttons when no user is provided.

import { AgentAIHeader } from '@agentai/appsdk';

<AgentAIHeader user={null} showLogin={true} showSignup={true} />

Logged In (user object)

Shows user avatar with dropdown menu when user object is provided.

<AgentAIHeader 
  user={{ name: 'John Doe', picture: '/avatar.jpg', username: 'johndoe' }}
  currentPath="/dashboard"
  onLogout={() => handleLogout()}
/>

Custom Navigation Links

<AgentAIHeader 
  user={user}
  navLinks={[
    { href: '/dashboard', label: 'Dashboard' },
    { href: '/agents', label: 'Agents' },
    { href: 'https://docs.agent.ai', label: 'Docs', external: true },
    { href: '/settings', label: 'Settings', requiresAuth: true }
  ]}
/>

Custom Auth URLs

<AgentAIHeader 
  loginUrl="/custom-login"
  signupUrl="/custom-signup"
        showLogin={true}
        showSignup={true}
/>

Theme Customization

<AgentAIHeader 
  user={user}
  theme={{
    colors: {
      background: { header: '#1a1a2e' },
      text: { light: '#ffffff' }
    },
    branding: {
      logoLight: '/custom-logo.svg',
      logoAlt: 'My App'
    }
  }}
  homeUrl="/"
  containerMaxWidth="1400px"
/>

Props Reference

Prop

Type

Description

user

object | null

{ name, picture, username }

currentPath

string

Current page path for active nav highlighting

navLinks

array

{ href, label, external?, requiresAuth? }[]

showLogin

boolean

Show login button when logged out (default: true)

showSignup

boolean

Show signup button when logged out (default: true)

loginUrl

string

Custom login URL

signupUrl

string

Custom signup URL

onLogout

function

Callback when logout is clicked

onNavigate

function

Callback when nav link is clicked

homeUrl

string

Logo link destination (default: /)

logoSrc

string

Custom logo image URL

logoAlt

string

Logo alt text

headerHeight

string

Custom header height

containerMaxWidth

string

Max width of header content

theme

object

Theme overrides

User Object

// User object structure
const user = {
  name: 'John Doe',       // Display name
  picture: '/avatar.jpg', // Avatar image URL
  username: 'johndoe'     // Used in profile URLs
};

Nav Link Object

// Nav link structure
const navLinks = [
  { 
    href: '/dashboard',      // Link URL
    label: 'Dashboard',      // Display text
    external: false,         // Opens in new tab
    requiresAuth: false      // Only show when logged in
  }
];

Features

Responsive Mobile Menu

Hamburger menu on mobile with full navigation

User Dropdown

Avatar dropdown with profile and settings links

Active State

Highlights current page in navigation

Auth Buttons

External Links

Support for external links with icon indicator

Theme Support

Full customization via theme prop

Skip Link

Accessibility skip-to-content link

Theme Configuration

Customize components using the JSON theme configuration. Pass a theme prop to any component.

Custom Theme Example

const customTheme = {
  colors: {
    primary: '#2563EB',
    secondary: '#F59E0B',
    background: { header: '#1E40AF', footer: '#F8FAFC' }
  },
  branding: { logoLight: '/your-logo.svg', logoAlt: 'Your Brand' }
};

<AgentAIHeader theme={customTheme} />
<AgentAIFooter theme={customTheme} />

Default Theme

{
  "name": "Agent.ai SDK Theme",
  "version": "1.3.1",
  "colors": {
    "primary": "#1A3643",
    "secondary": "#D96C4F",
    "background": {
      "header": "#0A1B22",
      "footer": "#ffffff",
      "page": "#ffffff",
      "card": "#f8fafc",
      "cardHover": "#f1f5f9"
    },
    "text": {
      "primary": "#1A3643",
      "secondary": "#4A5568",
      "light": "#ffffff",
      "muted": "#718096",
      "heading": "#0f172a",
      "label": "#94a3b8"
    },
    "link": {
      "default": "#0064C7",
      "hover": "#003E7B"
    },
    "border": {
      "light": "#E2E8F0",
      "default": "#CBD5E0"
    },
    "button": {
      "primary": {
        "background": "#D96C4F",
        "text": "#ffffff",
        "hover": "#d95632"
      },
      "secondary": {
        "background": "transparent",
        "text": "#ffffff",
        "border": "#ffffff",
        "hover": "rgba(255, 255, 255, 0.1)"
      }
    },
    "accent": {
      "blue": "#4f46e5",
      "purple": "#7c3aed",
      "green": "#22c55e",
      "orange": "#f97316",
      "red": "#ef4444",
      "cyan": "#06b6d4",
      "pink": "#ec4899"
    },
    "status": {
      "info": {
        "bg": "#eff6ff",
        "border": "#bfdbfe",
        "text": "#1e40af",
        "icon": "#3b82f6"
      },
      "success": {
        "bg": "#f0fdf4",
        "border": "#bbf7d0",
        "text": "#166534",
        "icon": "#22c55e"
      },
      "warning": {
        "bg": "#fffbeb",
        "border": "#fde68a",
        "text": "#92400e",
        "icon": "#f59e0b"
      },
      "error": {
        "bg": "#fef2f2",
        "border": "#fecaca",
        "text": "#991b1b",
        "icon": "#ef4444"
      },
      "auth": {
        "bg": "#fef9e7",
        "border": "#fde68a",
        "text": "#92400e",
        "icon": "#92400e"
      }
    },
    "pill": {
      "gray": {
        "bg": "#f1f5f9",
        "border": "#e2e8f0",
        "text": "#334155"
      },
      "blue": {
        "bg": "#eff6ff",
        "border": "#bfdbfe",
        "text": "#1e40af"
      },
      "green": {
        "bg": "#f0fdf4",
        "border": "#bbf7d0",
        "text": "#166534"
      },
      "orange": {
        "bg": "#fff7ed",
        "border": "#fed7aa",
        "text": "#9a3412"
      },
      "red": {
        "bg": "#fef2f2",
        "border": "#fecaca",
        "text": "#991b1b"
      },
      "purple": {
        "bg": "#faf5ff",
        "border": "#e9d5ff",
        "text": "#6b21a8"
      }
    },
    "chart": {
      "blue": "#3b82f6",
      "green": "#22c55e",
      "red": "#ef4444",
      "orange": "#f97316",
      "purple": "#8b5cf6"
    }
  },
  "fonts": {
    "heading": "Inter, Arial, Helvetica, sans-serif",
    "body": "Inter, Arial, Helvetica, sans-serif"
  },
  "spacing": {
    "headerHeight": "64px",
    "containerMaxWidth": "1280px",
    "containerPadding": "16px"
  },
  "borderRadius": {
    "sm": "4px",
    "md": "8px",
    "lg": "12px",
    "full": "9999px"
  },
  "shadows": {
    "sm": "0 1px 2px rgba(0, 0, 0, 0.05)",
    "md": "0 4px 6px rgba(0, 0, 0, 0.1)",
    "lg": "0 10px 15px rgba(0, 0, 0, 0.1)"
  },
  "branding": {
    "logoLight": "https://agent.ai/logo-2025/agent-ai-logo-2025-white.svg",
    "logoDark": "https://agent.ai/logo-2025/agent-ai-logo-new-dark.svg",
    "logoAlt": "Agent.ai"
  },
  "navigation": {
    "baseUrl": "https://agent.ai",
    "links": [
      {
        "href": "https://agent.ai/agents",
        "label": "Agent Network",
        "external": true
      },
      {
        "href": "https://agent.ai/builders",
        "label": "Builder Network",
        "external": true
      },
      {
        "href": "https://blog.agent.ai",
        "label": "Blog",
        "external": true
      },
      {
        "href": "https://agent.ai/builder/agents",
        "label": "Agent Builder",
        "external": true,
        "requiresAuth": true
      }
    ]
  },
  "userMenu": {
    "baseUrl": "https://agent.ai",
    "sections": [
      {
        "title": "Account",
        "items": [
          {
            "label": "Profile",
            "href": "https://agent.ai/human/{username}",
            "icon": "user",
            "external": true
          },
          {
            "label": "Settings",
            "href": "https://agent.ai/user/settings",
            "icon": "settings",
            "external": true
          },
          {
            "label": "Connections",
            "href": "https://agent.ai/user/connections",
            "icon": "plug",
            "external": true
          }
        ]
      },
      {
        "title": "Agents",
        "items": [
          {
            "label": "Runs",
            "href": "https://agent.ai/user/agent-runs",
            "icon": "running",
            "external": true
          },
          {
            "label": "Subscriptions",
            "href": "https://agent.ai/user/agent-subscriptions",
            "icon": "credit-card",
            "featureFlag": "agent_subscriptions_page",
            "external": true
          },
          {
            "label": "Team",
            "href": "https://agent.ai/user/team",
            "icon": "users",
            "external": true
          }
        ]
      },
      {
        "title": "Builder",
        "requiresBuilder": true,
        "items": [
          {
            "label": "Knowledge & Files",
            "href": "https://agent.ai/builder/files",
            "icon": "database",
            "external": true
          },
          {
            "label": "Snippets",
            "href": "https://agent.ai/builder/snippets",
            "icon": "code",
            "external": true
          },
          {
            "label": "Secrets",
            "href": "https://agent.ai/builder/secrets",
            "icon": "key",
            "external": true
          },
          {
            "label": "Serverless Functions",
            "href": "https://agent.ai/builder/serverless",
            "icon": "server",
            "external": true
          }
        ]
      },
      {
        "title": "Resources",
        "items": [
          {
            "label": "Community",
            "href": "https://community.agent.ai/",
            "icon": "group",
            "external": true
          },
          {
            "label": "Suggest An Agent",
            "href": "https://agent.ai/suggest-an-agent",
            "icon": "lightbulb",
            "external": true
          },
          {
            "label": "Give Feedback",
            "href": "https://agent.ai/feedback",
            "icon": "message-square",
            "external": true
          }
        ]
      }
    ]
  },
  "footer": {
    "baseUrl": "https://agent.ai",
    "description": "Agent.ai is the #1 professional network for AI agents. Here, you can build, discover, and activate trustworthy AI agents to do useful things.",
    "copyright": "© AgentAI Platform, Inc",
    "links": {
      "terms": "https://agent.ai/terms",
      "privacy": "https://agent.ai/privacy-policy"
    },
    "resources": [
      {
        "label": "Documentation",
        "href": "https://docs.agent.ai"
      },
      {
        "label": "Community",
        "href": "https://community.agent.ai"
      }
    ],
    "social": [
      {
        "platform": "twitter",
        "href": "https://x.com/AgentDotAi"
      },
      {
        "platform": "facebook",
        "href": "https://www.facebook.com/profile.php?id=61561787124174"
      },
      {
        "platform": "linkedin",
        "href": "https://www.linkedin.com/company/agentdotai/"
      }
    ]
  }
}

v1.3.1

Current

December 8, 2024

Agent.ai App SDK v1.3.1

Release Date: December 8, 2024

Overview

This patch release updates all navigation links, user menu links, and footer links to use the full https://agent.ai base URL. This ensures that when the SDK is used on third-party domains, all links correctly navigate to agent.ai rather than the host domain.

Changes

Navigation Links

All main navigation links now use absolute URLs:

Agent Network → https://agent.ai/agents
Builder Network → https://agent.ai/builders
Agent Builder → https://agent.ai/builder/agents
Blog → https://blog.agent.ai

User Menu Links

All user dropdown menu items now use absolute URLs:

Account:

Profile → https://agent.ai/human/{username}
Settings → https://agent.ai/user/settings
Connections → https://agent.ai/user/connections

Agents:

Runs → https://agent.ai/user/agent-runs
Subscriptions → https://agent.ai/user/agent-subscriptions
Team → https://agent.ai/user/team

Builder:

Knowledge & Files → https://agent.ai/builder/files
Snippets → https://agent.ai/builder/snippets
Secrets → https://agent.ai/builder/secrets
Serverless Functions → https://agent.ai/builder/serverless

Resources:

Community → https://community.agent.ai/
Suggest An Agent → https://agent.ai/suggest-an-agent
Give Feedback → https://agent.ai/feedback

Footer Links

Footer links now use absolute URLs:

Terms → https://agent.ai/terms
Privacy → https://agent.ai/privacy-policy
Documentation → https://docs.agent.ai
Community → https://community.agent.ai

Theme Configuration

A new baseUrl property has been added to navigation, userMenu, and footer sections in the theme for documentation purposes:

{
  "navigation": {
    "baseUrl": "https://agent.ai",
    "links": [...]
  },
  "userMenu": {
    "baseUrl": "https://agent.ai",
    "sections": [...]
  },
  "footer": {
    "baseUrl": "https://agent.ai",
    ...
  }
}

Breaking Changes

None. All changes are backward compatible.

Migration

No migration needed. Links will automatically use the new absolute URLs.

v1.3.0

December 8, 2024

Agent.ai App SDK v1.3.0

Release Date: December 8, 2024

Overview

Major release adding a comprehensive suite of data display components for building dashboards, reports, and data-rich interfaces.

New Components

AgentAISection

Section wrapper with title and colored accent underline.

<AgentAISection title="Web Traffic" accent="blue">
  <YourContent />
</AgentAISection>

AgentAIStatCard / AgentAIMetricCard

Cards for displaying statistics and KPIs with optional accent borders.

<AgentAIStatCard label="COMPANY" value="HubSpot" />
<AgentAIStatCard 
  label="VISITORS" 
  value="34.8M" 
  subValue="Aug 2025"
  trend={{ value: '+5.2%', direction: 'up' }}
/>
<AgentAIMetricCard
  label="MONTH-OVER-MONTH GROWTH"
  value="-5.2%"
  accent="red"
/>

AgentAIPill / AgentAITagCard / AgentAISuggestionPills

Clickable pills, tag groups, and suggestion displays.

<AgentAIPill>hubspot.com</AgentAIPill>
<AgentAIPill variant="selected" color="blue">Selected</AgentAIPill>

<AgentAITagCard title="Analytics">
  <AgentAIPill>Google Analytics</AgentAIPill>
  <AgentAIPill>Hotjar</AgentAIPill>
</AgentAITagCard>

<AgentAISuggestionPills
  suggestions={['hubspot.com', 'anthropic.com']}
  onSelect={(value) => setInput(value)}
/>

AgentAIInfoBanner

Status banners with icons and action buttons.

<AgentAIInfoBanner
  status="success"
  text="Found in HubSpot CRM"
  action={{ label: "View in HubSpot", onClick: handleClick }}
/>

AgentAITimeline

Timeline for news feeds and activity logs.

<AgentAITimeline>
  <AgentAITimeline.Item
    date="November 24, 2025"
    title="HubSpot Reports Q3 Results"
    source="Business Wire"
    description="Q3 2025 results..."
    icon="📰"
  />
</AgentAITimeline>

AgentAIDataTable

Simple, styled data tables.

<AgentAIDataTable
  columns={[
    { key: 'keyword', header: 'Keyword' },
    { key: 'position', header: 'Position', align: 'center' },
    { key: 'volume', header: 'Search Volume', align: 'right' },
  ]}
  data={[
    { keyword: 'hubspot', position: '#1', volume: '301,000' },
  ]}
/>

AgentAIBarChart / AgentAIMiniBarChart

CSS-based bar charts - no external library needed.

<AgentAIBarChart
  data={[
    { label: 'May', value: 35000000 },
    { label: 'Jun', value: 32000000 },
  ]}
  color="#3b82f6"
  height={200}
/>

AgentAISearchInput

Search input with suggestions and action button.

<AgentAISearchInput
  placeholder="Enter a domain..."
  helperText="Minimum 2 characters required"
  suggestions={['hubspot.com', 'anthropic.com']}
  onSearch={handleSearch}
  actionLabel="Go"
  isLoading={loading}
/>

Grid Layouts

Use AgentAIStatGrid for responsive stat card layouts:

<AgentAIStatGrid columns={{ base: 2, md: 4 }}>
  <AgentAIStatCard label="VISITORS" value="34.8M" />
  <AgentAIStatCard label="GROWTH" value="+5.2%" />
</AgentAIStatGrid>

Breaking Changes

None. All changes are backward compatible.

v1.2.2

December 8, 2024

Agent.ai App SDK v1.2.2

Release Date: December 8, 2024

Overview

This release adds the AgentAIAlert component for displaying notifications, warnings, and actionable messages.

New Components

AgentAIAlert

A flexible alert/notification component with multiple status types and optional actions.

Status Types:

info - Blue, informational messages
success - Green, success confirmations
warning - Yellow/amber, warnings
error - Red, error messages
auth - Special auth-themed alert for login prompts

Basic Usage:

import { AgentAIAlert } from '@agentai/appsdk';

<AgentAIAlert
  status="warning"
  title="Warning"
  description="Please review before proceeding."
/>

With Action Button:

<AgentAIAlert
  status="auth"
  title="Sign in required"
  description="Use your Agent.ai login to generate reports."
  action={{
    label: "Login to continue",
    onClick: handleLogin,
    icon: <FiLogIn size={14} />
  }}
/>

Dismissible Alert:

<AgentAIAlert
  status="info"
  title="New feature"
  description="Check out our new dashboard."
  isDismissible
  onDismiss={() => setVisible(false)}
/>

Props:

status - 'info' | 'success' | 'warning' | 'error' | 'auth'
title - Alert title
description - Alert description text
children - Custom content
action - { label, onClick?, href?, icon?, variant? }
icon - Custom icon override
showIcon - Show status icon (default: true)
isDismissible - Show dismiss button
onDismiss - Dismiss callback

Compound Components:

For more control, use the compound component API:

<AgentAIAlert.Root status="warning">
  <AgentAIAlert.Icon />
  <AgentAIAlert.Content>
    <AgentAIAlert.Title>Warning</AgentAIAlert.Title>
    <AgentAIAlert.Description>Details here</AgentAIAlert.Description>
    <AgentAIAlert.Action label="Fix now" onClick={handleFix} />
  </AgentAIAlert.Content>
</AgentAIAlert.Root>

Bug Fixes

Fixed footer Resource links (Documentation, Community) not being visible

Breaking Changes

None. All changes are backward compatible.

v1.2.1

December 7, 2024

Agent.ai App SDK v1.2.1

Release Date: December 7, 2024

Overview

This release adds comprehensive custom authentication support to the AgentAIHeader component, enabling integration with OAuth providers, partner APIs, and custom auth flows.

New Features

Custom Authentication in AgentAIHeader

The header component now supports fully customizable authentication:

New Props:

onLogin - Custom login handler callback (replaces default navigation)
onSignup - Custom signup handler callback (replaces default navigation)
useCustomAuth - When true, only use callbacks instead of URL navigation
isAuthLoading - Show loading state on auth buttons
loginLabel - Custom text for login button (default: "Sign In")
signupLabel - Custom text for signup button (default: "Sign Up")

Example: Custom OAuth Integration

import { AgentAIHeader } from '@agentai/appsdk';

function App() {
  const { user, login, logout, loading } = useAuth();

  // Transform user object to SDK format
  const headerUser = user ? {
    name: [user.first_name, user.last_name].filter(Boolean).join(' '),
    picture: user.avatar_url || '',
    username: user.email?.split('@')[0] || 'user',
  } : null;

  return (
    <AgentAIHeader
      user={headerUser}
      onLogin={login}           // Your custom login (OAuth, etc.)
      onSignup={() => login()}  // Or separate signup flow
      onLogout={logout}
      useCustomAuth={true}      // Don't use default SDK auth URLs
      isAuthLoading={loading}   // Show spinner while checking auth
      showLogin={!loading && !user}
      showSignup={!loading && !user}
    />
  );
}

Example: URL-based with Custom Handlers

<AgentAIHeader
  user={user}
  loginUrl="/auth/login"
  signupUrl="/auth/register"
  onLogin={() => {
    // Track analytics before navigating
    analytics.track('login_clicked');
  }}
  onLogout={handleLogout}
/>

Example: Custom Button Labels

<AgentAIHeader
  user={user}
  loginLabel="Log In"
  signupLabel="Get Started"
  onLogin={handleLogin}
  onSignup={handleSignup}
  useCustomAuth={true}
/>

Bug Fixes

Fixed footer Terms and Privacy links being white instead of visible gray

Breaking Changes

None. All new props are optional and backward compatible.

Known Issues

None at this time.

v1.2.0

December 7, 2024

Agent.ai App SDK v1.2.0

Release Date: December 7, 2024

Overview

This release introduces components for building mini-apps/labs pages with searchable hero sections and status-badged app cards.

New Components

AgentAILabsHero

A hero section for mini-apps pages featuring search functionality and call-to-action:

import { AgentAILabsHero } from '@agentai/appsdk';

<AgentAILabsHero
  label="AGENT.AI LABS"
  title="Launch mini-apps built for instant utility"
  subtitle="A curated set of opinionated tools that feel consistent, fast, and fun."
  searchPlaceholder="Search an app or workflow"
  onSearch={(query) => handleSearch(query)}
  ctaLabel="Explore apps"
  onCtaClick={() => navigate('/apps')}
  helperText="Try "
  helperLinks={[
    { label: 'DadJoke.ai', href: '/apps/dadjoke', suffix: ' for playful prompts or ' },
    { label: 'Teamwork', href: '/apps/teamwork', suffix: ' for workflows.' }
  ]}
/>

Key props:

label - Top label text (e.g., "AGENT.AI LABS")
title - Main heading text
subtitle - Subtitle/description
showSearch - Toggle search input visibility (default: true)
searchPlaceholder, onSearch - Search functionality
ctaLabel, ctaHref, onCtaClick - CTA button configuration
helperText, helperLinks - Helper text with inline links
showSparkles - Show sparkle icon decoration (default: true)

AgentAIAppCard

Cards for displaying mini-apps with status badges:

import { AgentAIAppCard, AgentAIAppCardGrid } from '@agentai/appsdk';

<AgentAIAppCardGrid columns={{ base: 1, md: 2 }} gap={4}>
  <AgentAIAppCard
    title="DadJoke.ai"
    description="Use AI to generate pun-believably bad jokes for any topic."
    status="new"
    href="/apps/dadjoke"
    actionLabel="Launch app"
  />
  <AgentAIAppCard
    title="Company Research"
    description="Drop in a company domain for a synthesized dossier."
    status="coming-soon"
    isDisabled
  />
  <AgentAIAppCard
    title="Brand Assets"
    description="Fetch logos, colors, and fonts for any brand."
    status="beta"
    href="/apps/brand-assets"
  />
</AgentAIAppCardGrid>

Status badges available:

new - Green badge
beta - Orange badge
coming-soon - Cyan badge
alpha - Purple badge
live - Blue badge
deprecated - Gray badge

Key props:

title, description - Card content
status - Badge type ('new' | 'beta' | 'coming-soon' | 'alpha' | 'live' | 'deprecated')
statusLabel - Custom badge text override
href, onClick - Card action
actionLabel - Action link text (default: "Launch app")
isDisabled - Disable card interactions
isExternal - Open link in new tab
icon - Optional icon element

AgentAIAppCardGrid

A responsive grid container for app cards:

<AgentAIAppCardGrid 
  columns={{ base: 1, md: 2, lg: 3 }} 
  gap={4}
>
  {/* AgentAIAppCard items */}
</AgentAIAppCardGrid>

AgentAIFeatureCard

A larger gradient card for featured content:

import { AgentAIFeatureCard } from '@agentai/appsdk';
import { LuSparkles } from 'react-icons/lu';

<AgentAIFeatureCard
  title="Build Your Own Agent"
  description="Create custom AI agents with our intuitive builder. No code required."
  actionLabel="Get started"
  href="/builder"
  icon={<LuSparkles size={32} />}
  backgroundColor="linear-gradient(135deg, #3b82f6 0%, #8b5cf6 100%)"
/>

Key props:

title, description - Card content
icon - Icon element
href, onClick, actionLabel - Card action
backgroundColor - Background (supports gradients)
textColor - Text color (default: white)

Improvements

Theme Configuration

Logo paths now use full public URLs (https://agent.ai/...) for reliable loading in external apps

Breaking Changes

None.

Known Issues

None at this time.

v1.1.0

December 7, 2024

Agent.ai App SDK v1.1.0

Release Date: December 7, 2024

Overview

This release introduces comprehensive agent page components, providing a complete page shell for building agent interfaces that match the Agent.ai design system.

New Components

AgentAIAgentPage

A complete page shell for agent implementations that includes:

Site Header (AgentAIHeader) - Navigation with user authentication
Agent Header (AgentAIAgentHeader) - Agent info, stats, and actions
Card Body - Your custom agent implementation
Site Footer (AgentAIFooter) - Branding and resources

Uses a config-based API for cleaner prop organization:

<AgentAIAgentPage
  headerConfig={{
    user: currentUser,
    onLogout: handleLogout,
    currentPath: '/agent/my-agent'
  }}
  agentHeaderConfig={{
    name: 'My Custom Agent',
    icon: '/agent-icon.png',
    description: 'Your agent description',
    version: '1.0',
    executions: 1000,
    approximateTime: 30
  }}
>
  {/* Your agent implementation */}
</AgentAIAgentPage>

Key props:

headerConfig - Props for AgentAIHeader (site navigation)
footerConfig - Props for AgentAIFooter
agentHeaderConfig - Props for AgentAIAgentHeader
showSiteHeader, showSiteFooter, showAgentHeader - Visibility toggles
minHeight - Page min height (default: '100vh', use 'auto' for embedded)
pageBackgroundColor - Page background override
cardBorderColor - Card border color (default: '#e2e8f0')

Helper components for structuring content:

AgentAIAgentPageSection - Grouping with consistent spacing
AgentAIAgentPageForm - Form wrapper with styling
AgentAIAgentPageResults - Container for results

AgentAIAgentHeader

Displays agent information in a header format within a card:

Agent avatar/icon with CDN optimization
Agent name with version badge
Description with line clamping
Stats row (rating, execution count, estimated time)
Action buttons (follow, team, subscribe)
Trial info display
NEW: Live data fetching - Pass just agentId + fetchAgent to auto-populate

Two operation modes:

Static Mode (default):

<AgentAIAgentHeader
  name="My Agent"
  icon="/icon.png"
  executions={1000}
/>

Live Mode - Auto-fetches from Agent.ai API:

// Just pass agentId - data is fetched automatically!
<AgentAIAgentHeader
  agentId="flux-image-generator"
  onAgentLoaded={(agent) => console.log('Loaded!', agent)}
/>

Key props (Static):

agent or individual props: name, icon, description, version
executions, approximateTime, reviewScore - Stats data

Key props (Live Data):

agentId - Agent ID to fetch (triggers automatic API call)
apiHost - API host URL (default: https://api.agent.ai)
accessToken - Optional auth token for protected agents
refetchInterval - Optional auto-refetch in ms
onAgentLoaded, onAgentError - Lifecycle callbacks

Display props:

showStats, showActions - Visibility toggles
showFollowButton, showTeamButton, showSubscribe - Action buttons
onFollow, onUnfollow, onTeamAdd, onTeamRemove, onSubscribe - Callbacks
borderColor - Border color (default: '#e2e8f0')

Includes loading skeleton and error states with retry capability.

AgentAIAgentAvatar

Specialized avatar for agent icons with intelligent fallback:

1. Tries Cloudflare CDN optimized URL

2. Falls back to original URL

3. Falls back to default agent icon

Props:

src - Image URL (supports CDN optimization)
size - 'sm' | 'md' | 'lg' | 'xl' or custom object
showBorder, borderWidth, borderColor - Border options
transform - CDN transform parameters

Improvements

AgentAIHeader

Enhanced mobile responsiveness with larger touch targets
Inline user menu on mobile (no popover)
Simplified - removed enabledFeatures prop and isBuilder logic

AgentAIFooter

Simplified API - all content now configured via theme
Removed configurable description and resources props

Breaking Changes

AgentAIFooter

The following props have been removed:

description
resources

All footer content is now sourced from theme.footer configuration.

Migration Guide

AgentAIFooter

Before:

<AgentAIFooter 
  description="Custom description"
  resources={[...]}
/>

After:

// Configure via theme
<AgentAIFooter 
  theme={{
    footer: {
      description: "Custom description",
      resources: [...]
    }
  }}
/>

Known Issues

None at this time.

v1.0.0

December 7, 2024

Agent.ai App SDK v1.0.0

Release Date: December 7, 2024

Overview

Initial release of the Agent.ai App SDK - a comprehensive set of pre-built, themeable React components designed for seamless integration into third-party applications.

Components

Layout Components

AgentAIHeader - Full-width navigation header with logo, nav links, user dropdown, and responsive mobile menu. Supports logged in/logged out states.

AgentAIFooter - Site footer with branding, resource links, and social media integration. Content configured via theme.

AgentAIPageCard - Full-page card layout for standalone pages with header icon, title, description, and content area.

AgentAICard - Card container with optional header, sections, and dividers.

Navigation Components

AgentAITabs - Horizontal tabbed navigation with icons. Includes AgentAITabs.Content for tab panels.

AgentAIVerticalTabs - Vertical sidebar navigation for component lists. Supports left or right positioning.

Form Components

AgentAIButton - Styled buttons with variants (primary, secondary, tertiary, ghost, danger), sizes (xs, sm, md, lg), and states (loading, disabled).

AgentAIInput - Text inputs with label, placeholder, helper text, error states, and validation.

AgentAISelect - Dropdown selects with customizable options, labels, and validation.

AgentAISwitch - Toggle switches with label, description, and inline variant.

Display Components

AgentAIAvatar - User avatars with image support and initials fallback.

AgentAIPopover - Standalone popover primitives for tooltips and menus.

Theme Configuration

All components support theming via the appsdk-theme.json configuration file:

Color palette (primary, secondary, background, text colors)
Typography settings
Spacing and container widths
Branding (logos, company name)
Navigation links
Footer content

Features

Fully Standalone - No dependencies on internal systems. Only requires Chakra UI as a peer dependency.

LLM-Ready - Comprehensive documentation in the LLM.txt tab for AI-assisted implementation.

Production Ready - Battle-tested components used across the Agent.ai platform.

Breaking Changes

None - initial release.

Known Issues

None at this time.

@agentai/appsdk

Installation

Quick Start

Available Components (24)

Requirements

Agent.ai API SDKs

Examples

Text Generator

Company Research

LLM Implementation Context

Header

Logged Out (user=null)

Logged In (user object)

Custom Navigation Links

Custom Auth URLs

Theme Customization

Props Reference

User Object

Nav Link Object

Features

Theme Configuration

Custom Theme Example

Default Theme

Agent.ai App SDK v1.3.1

Overview

Changes

Navigation Links

User Menu Links

Footer Links

Theme Configuration

Breaking Changes

Migration

Agent.ai App SDK v1.3.0

Overview

New Components

AgentAISection

AgentAIStatCard / AgentAIMetricCard

AgentAIPill / AgentAITagCard / AgentAISuggestionPills

AgentAIInfoBanner

AgentAITimeline

AgentAIDataTable

AgentAIBarChart / AgentAIMiniBarChart

AgentAISearchInput

Grid Layouts

Breaking Changes

Agent.ai App SDK v1.2.2

Overview

New Components

AgentAIAlert

Bug Fixes

Breaking Changes

Agent.ai App SDK v1.2.1

Overview

New Features

Custom Authentication in AgentAIHeader

Bug Fixes

Breaking Changes

Known Issues

Agent.ai App SDK v1.2.0

Overview

New Components

AgentAILabsHero

AgentAIAppCard

AgentAIAppCardGrid

AgentAIFeatureCard

Improvements

Theme Configuration

Breaking Changes

Known Issues

Agent.ai App SDK v1.1.0

Overview

New Components

AgentAIAgentPage

AgentAIAgentHeader

AgentAIAgentAvatar

Improvements

AgentAIHeader

AgentAIFooter

Breaking Changes

AgentAIFooter