@mobilabsolutions/axium-agent-sdk

https://mobilabsolutions.com/axium/

Installation

npm install @mobilabsolutions/axium-agent-sdk

Styles

The SDK ships two stylesheet variants:

Tailwindcss

If your host app already uses Tailwind:

import '@mobilabsolutions/axium-agent-sdk/styles.css';

This variant uses CSS @layer's and does not include Tailwind's preflight, since the host app should already be providing it.

Unlayered styles

If your host app uses a vanilla CSS reset or no CSS framework:

import '@mobilabsolutions/axium-agent-sdk/styles-unlayered.css';

This variant has no @layers defined, and it assumes the host app already has its own reset/preflight in place. It's important that the styles be imported next to the host styles in order for the host to take precedence.

More styling control

| Prop | Type | Default | Description | | ------- | ------- | ------- | ----------------------------------------------------------------- | | theme | Theme | — | Optional theme object (colors, typography, logos, favicon, fonts) |

Theme object

All fields are optional. Only the fields you provide will be applied.

import type { Theme } from '@mobilabsolutions/axium-agent-sdk';

const theme: Theme = {
  title: 'My App',
  tokens: {
    colors: {
      // Overrides CSS variables
      'primary-A400': '#0066cc',
      'primary-A500': '#004d99',
    },
    typography: {
      primary: 'Roboto',
      secondary: 'Lato',
    },
  },
};

Usage

import {
  AxiumAgentProvider,
  Chat,
  BlankChat,
  useChats,
  useChatLoader,
  useCreateChat,
  useDeleteChat,
} from '@mobilabsolutions/axium-agent-sdk';
import '@mobilabsolutions/axium-agent-sdk/styles.css';

function App() {
  return (
    <AxiumAgentProvider
      baseUrl="https://agent.axium.com"
      msalInstance={msal}
      scopes={['api://<agent-client-id>/.default']}
      theme={theme}
    >
      <ChatView />
    </AxiumAgentProvider>
  );
}

function ChatView() {
  const { data: chats } = useChats();
  const { chat, isLoading } = useChatLoader(chatId);
  const { create: createChat, creating } = useCreateChat({
    done: (chatId) => {
      /* navigate to chat */
    },
  });
  const { mutate: deleteChat } = useDeleteChat();

  if (isLoading) return <div>Loading...</div>;
  if (!chat) return <BlankChat onSubmit={handleSubmit} hideConnectors />;
  return <Chat chat={chat} hideConnectors />;
}

Props

AxiumAgentProvider

| Prop | Type | Default | Description | | -------------- | -------------------------- | -------- | ----------------------------------------------------------------------------------------------- | | baseUrl | string | required | Base URL for API calls (e.g. "https://agent.axium.com") | | msalInstance | IPublicClientApplication | required | MSAL instance for Bearer token auth | | scopes | string[] | required | Token scopes (e.g. ["api://<agent-client-id>/.default"]) | | theme | Theme | — | Optional theme object (colors, typography, logos) | | onAuthError | (error: unknown) => void | — | Invoked when token acquisition fails (e.g. no signed-in account). Use it to present a login UI. |

Chat

The parent container must use display: flex with a defined height (e.g. height: 100% or height: 100vh) for the chat to fill the available space correctly.

| Prop | Type | Default | Description | | ---------------- | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | | chat | ChatDetailResponse | required | Chat data from useChatLoader | | hideConnectors | boolean | false | Hide the connectors dropdown in chat input | | useFullWidth | boolean | false | Remove the default max-width constraints on conversation, input, and error/no-LLM messages so they fill the parent |

BlankChat

| Prop | Type | Default | Description | | ------------------ | ----------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------- | | onSubmit | (input: string, files?: FileUIPart[]) => Promise<boolean> | required | Message submit handler | | initialPrompt | string | — | Pre-fill the input | | hideIllustration | boolean | false | Hide the welcome illustration | | hideConnectors | boolean | false | Hide the connectors dropdown in chat input | | useFullWidth | boolean | false | Remove the default max-width constraints on illustration, input, and no-LLM message so they fill the parent |

Hooks

useCreateChat

Creates a new chat on the server. Returns { create, creating }.

When the chat is created, the done callback fires with the new chatId. You should call setIsNewChat(true) (from useActiveChat) before navigating to the chat view — this signals the Chat component to auto-submit the first message to the LLM.

const { setIsNewChat } = useActiveChat();
const { create, creating } = useCreateChat({
  done: (chatId) => {
    setIsNewChat(true);
    navigate(`/chat/${chatId}`);
  },
});

useActiveChat

Returns { isNewChat, setIsNewChat }. The Chat component watches isNewChat — when true and messages are loaded, it automatically triggers the LLM response and resets the flag. This bridges the gap between creating a chat and starting the AI generation.

useChatLoader

Loads a chat by ID. Returns { chat, isLoading }.

useChats / useDeleteChat

useChats() returns the list of conversations. useDeleteChat() returns a mutation to delete a chat by ID.

License

See LICENSE.md.