@portmento/agent-ui

React UI components for embedding Portmento agents into your web application.

Installation

npm install @portmento/agent-ui
# or
pnpm add @portmento/agent-ui
# or
yarn add @portmento/agent-ui

Quick Start

Wrap your app with PortmentoProvider and drop in PortmentoChat:

import { PortmentoProvider, PortmentoChat } from "@portmento/agent-ui";

export default function App() {
  return (
    <PortmentoProvider
      publishableKey="pk_live_your_key"
      getToken={async () => {
        // Return your user's auth token (e.g. from Auth0, AD, Cognito etc.)
        return await getAuthToken();
      }}
    >
        <PortmentoChat />
    </PortmentoProvider>
  );
}

PortmentoProvider

The provider handles authentication and connects to the Portmento runtime. It must wrap any component that uses PortmentoChat or usePortmentoChat.

Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | publishableKey | string | Yes | Your Portmento publishable key (pk_live_...) | | getToken | () => Promise<string> | Yes | Async function that returns the current user's auth token | | headers | Record<string, string> | No | Extra headers forwarded on every request (e.g. tenant ID) |

Example with custom headers

<PortmentoProvider
  publishableKey="pk_live_your_key"
  headers={{ "X-Company-Id": "your-company-uuid" }}
  getToken={async () => {
    const session = await Auth.currentSession();
    return session.getIdToken().getJwtToken();
  }}
>
  {children}
</PortmentoProvider>

PortmentoChat

A ready-to-use chat UI. Must be rendered inside PortmentoProvider.

<PortmentoChat />

The component fills its container — give the parent a defined height.

Props

| Prop | Type | Description | |------|------|-------------| | theme | PortmentoChatTheme | Customise colors, fonts, and border radius | | components | object | Override individual UI slots | | fallback | ReactNode | Shown when the chat fails to connect | | className | string | CSS class on the root element | | style | CSSProperties | Inline styles on the root element |

Theming

<PortmentoChat
  theme={{
    primaryColor: "#6366f1",
    backgroundColor: "#ffffff",
    textColor: "#111827",
    userMessageBackground: "#6366f1",
    userMessageColor: "#ffffff",
    assistantMessageBackground: "#f3f4f6",
    assistantMessageColor: "#111827",
    inputBackground: "#f9fafb",
    fontFamily: "Inter, sans-serif",
    borderRadius: "12px",
    fontSize: "14px",
  }}
/>

Custom components

Replace any part of the chat UI with your own components:

<PortmentoChat
  components={{
    Header: () => <div className="chat-header">Support</div>,
    UserMessage: ({ content }) => <div className="my-bubble user">{content}</div>,
    AssistantMessage: ({ content, isLoading }) => (
      <div className="my-bubble assistant">{content}</div>
    ),
    Input: ({ onSubmit, isLoading }) => (
      <MyCustomInput onSend={onSubmit} disabled={isLoading} />
    ),
    TypingIndicator: () => <span>Agent is thinking…</span>,
  }}
/>

usePortmentoChat (hook)

Access the chat state directly to build a fully custom UI.

import { usePortmentoChat } from "@portmento/agent-ui";

function MyChat() {
  const { messages, sendMessage, isLoading, stop, error, retry, canRetry } =
    usePortmentoChat();

  return (
    <div>
      {messages.map((msg) => (
        <div key={msg.id} className={msg.role}>
          {msg.content}
        </div>
      ))}
      {isLoading && <button onClick={stop}>Stop</button>}
      {error && (
        <div>
          {error}
          {canRetry && <button onClick={retry}>Retry</button>}
        </div>
      )}
      <input
        onKeyDown={(e) => {
          if (e.key === "Enter") sendMessage(e.currentTarget.value);
        }}
      />
    </div>
  );
}

Return values

| Field | Type | Description | |-------|------|-------------| | messages | PortmentoMessage[] | All messages in the conversation | | sendMessage | (text: string) => Promise<void> | Send a user message | | isLoading | boolean | True while the agent is running | | stop | () => void | Abort the current agent run | | error | string \| null | Current error message, if any | | retry | () => Promise<void> | Retry the last failed message | | canRetry | boolean | Whether a retry is available | | clearError | () => void | Dismiss the error state | | messageStatus | Record<string, MessageStatus> | Per-message status (sending, sent, failed) | | getMessageStatus | (id: string) => MessageStatus \| undefined | Status for a specific message |

Options

const chat = usePortmentoChat({
  statusClearDelay: 2000, // ms before "sent" status is removed (default: 1500, 0 to disable)
});

Types

type PortmentoMessage = {
  id: string;
  role: "user" | "assistant";
  content: string;
  createdAt?: Date;
};

type MessageStatus = "sending" | "sent" | "failed";

type PortmentoChatTheme = {
  primaryColor?: string;
  backgroundColor?: string;
  textColor?: string;
  userMessageBackground?: string;
  userMessageColor?: string;
  assistantMessageBackground?: string;
  assistantMessageColor?: string;
  inputBackground?: string;
  inputColor?: string;
  fontFamily?: string;
  borderRadius?: string;
  fontSize?: string;
};

Requirements

• React 18+
• The SDK is ESM-only

Acknowledgements

This SDK uses CopilotKit Core for underlying AGUI integration.

License

This package is proprietary. See license.