@agentai/appsdk

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

Features

• 🎨 Pre-built Components - Production-ready UI components matching Agent.ai's design system
• 🤖 Agent Integration - Built-in API fetching for Agent.ai agents
• 🎯 Fully Typed - Complete TypeScript support
• 🎛️ Themeable - Customize colors, branding, and styling
• 📱 Responsive - Mobile-first design with graceful degradation
• ♿ Accessible - WCAG 2.1 AA compliant

Installation

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

or

yarn add @agentai/appsdk @chakra-ui/react @emotion/react

or

pnpm add @agentai/appsdk @chakra-ui/react @emotion/react

Quick Start

1. Set up your App with ChakraProvider

// App.jsx
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>
  );
}

That's it! The AgentAIAgentPage automatically includes:

• Site header with navigation
• Agent header with auto-fetched agent data
• Your custom content
• Site footer

Components

Layout Components

| Component | Description | |-----------|-------------| | AgentAIHeader | Site navigation header with auth states | | AgentAIFooter | Site footer with branding and links | | AgentAIPageCard | Full-page card layout | | AgentAICard | Content card container |

Agent Components

| Component | Description | |-----------|-------------| | AgentAIAgentPage | Complete page shell for agent interfaces | | AgentAIAgentHeader | Agent info display with auto-fetch | | AgentAIAgentAvatar | Agent icon with CDN optimization |

Navigation Components

| Component | Description | |-----------|-------------| | AgentAITabs | Horizontal tabbed navigation | | AgentAIVerticalTabs | Vertical sidebar navigation |

Form Components

| Component | Description | |-----------|-------------| | AgentAIButton | Styled buttons with variants | | AgentAIInput | Text inputs with validation | | AgentAISelect | Dropdown selects | | AgentAISwitch | Toggle switches |

Display Components

| Component | Description | |-----------|-------------| | AgentAIAvatar | User avatars | | AgentAIPopover | Popover primitives |

Data Display Components (v1.3.0)

| Component | Description | |-----------|-------------| | AgentAISection | Section wrapper with colored accent underline | | AgentAIStatCard | Stat cards for KPIs and metrics | | AgentAIMetricCard | Large metric display with accent border | | AgentAIStatGrid | Responsive grid for stat cards | | AgentAIPill | Clickable pill/chip component | | AgentAITagCard | Card with grouped tags | | AgentAISuggestionPills | Suggestion pills row | | AgentAIInfoBanner | Status banner with action | | AgentAITimeline | Timeline for news/events | | AgentAIDataTable | Simple data table | | AgentAIBarChart | CSS-based bar chart | | AgentAISearchInput | Search input with suggestions |

Feedback Components

| Component | Description | |-----------|-------------| | AgentAIAlert | Alert/notification with status types | | AgentAIInfoBanner | Status banner with icon and action |

Live Data Fetching

The AgentAIAgentHeader component can automatically fetch agent data from the Agent.ai API:

import { ChakraProvider } from '@chakra-ui/react';
import { AgentAIAgentHeader } from '@agentai/appsdk';
import { Card } from '@chakra-ui/react';

function AgentDisplay() {
  return (
    <ChakraProvider>
      <Card.Root>
        {/* Just pass the agentId - data is fetched automatically! */}
        <AgentAIAgentHeader
          agentId="flux-image-generator"
          onAgentLoaded={(agent) => console.log('Loaded:', agent.name)}
          onAgentError={(error) => console.error('Error:', error)}
        />
      </Card.Root>
    </ChakraProvider>
  );
}

Or use the fetch function directly in your code:

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

async function loadAgent() {
  const agent = await fetchAgentFromAPI('flux-image-generator');
  console.log(agent.name, agent.description, agent.executions);
}

Custom Authentication

Integrate your own authentication flow (OAuth, SSO, partner APIs) with the header:

import { ChakraProvider } from '@chakra-ui/react';
import { AgentAIHeader } from '@agentai/appsdk';

function App() {
  const { user, login, logout, loading } = useAuth(); // Your auth hook

  // Transform your user object to SDK format
  const headerUser = user ? {
    name: user.display_name,
    picture: user.avatar_url,
    username: user.email?.split('@')[0],
  } : null;

  return (
    <ChakraProvider>
      <AgentAIHeader
        user={headerUser}
        onLogin={login}                    // Your custom login handler
        onSignup={() => login({ hint: 'signup' })}
        onLogout={logout}
        useCustomAuth={true}               // Use callbacks, not URL navigation
        isAuthLoading={loading}            // Show loading state
        showLogin={!loading && !user}
        showSignup={!loading && !user}
        loginLabel="Log In"                // Custom button text
        signupLabel="Get Started"
      />
    </ChakraProvider>
  );
}

Custom Auth Props

| Prop | Type | Description | |------|------|-------------| | onLogin | () => void | Custom login handler | | onSignup | () => void | Custom signup handler | | useCustomAuth | boolean | Use callbacks instead of URL navigation | | isAuthLoading | boolean | Show loading state on auth buttons | | loginLabel | string | Custom login button text | | signupLabel | string | Custom signup button text |

Theming

Customize the theme by passing a theme object:

import { ChakraProvider } from '@chakra-ui/react';
import { AgentAIHeader, AgentAIFooter, defaultTheme } from '@agentai/appsdk';

const customTheme = {
  ...defaultTheme,
  colors: {
    ...defaultTheme.colors,
    primary: '#your-brand-color',
  },
  branding: {
    name: 'Your Company',
    logoLight: '/your-logo.svg',
  },
};

function App() {
  return (
    <ChakraProvider>
      <AgentAIHeader theme={customTheme} />
      <main>{/* Your content */}</main>
      <AgentAIFooter theme={customTheme} />
    </ChakraProvider>
  );
}

Theme Structure

{
  "colors": {
    "primary": "#d96c4f",
    "background": {
      "header": "#0A1B22",
      "page": "#f5f5f5"
    }
  },
  "branding": {
    "name": "agent.ai",
    "logoLight": "/logo-light.svg",
    "logoDark": "/logo-dark.svg"
  },
  "navigation": {
    "links": [...]
  },
  "footer": {
    "description": "...",
    "resources": [...]
  }
}

Complete Example

// App.jsx - Root component with ChakraProvider
import { ChakraProvider } from '@chakra-ui/react';
import ImageGeneratorAgent from './ImageGeneratorAgent';

export default function App() {
  return (
    <ChakraProvider>
      <ImageGeneratorAgent />
    </ChakraProvider>
  );
}

// ImageGeneratorAgent.jsx - Agent page component
import { useState } from 'react';
import { 
  AgentAIAgentPage,
  AgentAIInput,
  AgentAIButton 
} from '@agentai/appsdk';

export default function ImageGeneratorAgent() {
  const [prompt, setPrompt] = useState('');
  const [isRunning, setIsRunning] = useState(false);
  const [user, setUser] = useState(null); // or your auth state

  const handleLogout = () => {
    setUser(null);
    // Your logout logic
  };

  const handleRun = async () => {
    setIsRunning(true);
    try {
      // Your agent execution logic here
      console.log('Running with prompt:', prompt);
    } finally {
      setIsRunning(false);
    }
  };

  return (
    <AgentAIAgentPage
      headerConfig={{
        user: user,
        onLogout: handleLogout,
      }}
      agentHeaderConfig={{
        agentId: 'flux-image-generator', // Auto-fetches agent data!
      }}
    >
      <AgentAIInput
        label="Image Description"
        placeholder="Describe the image you want to generate..."
        value={prompt}
        onChange={(e) => setPrompt(e.target.value)}
        isRequired
      />
      
      <AgentAIButton
        variant="primary"
        onClick={handleRun}
        isLoading={isRunning}
        loadingText="Generating..."
      >
        Generate Image
      </AgentAIButton>
    </AgentAIAgentPage>
  );
}

Documentation

Full documentation is available at agent.ai/appsdk.

Requirements

• React 18+
• Chakra UI 3+
• Emotion (required by Chakra UI)

License

MIT © Agent.ai

Links

• Documentation
• GitHub
• NPM
• Agent.ai