@amodalai/react

React components, hooks, and clients for a deployed Amodal agent.

Install

npm install @amodalai/react

Requires React and React DOM 18 or 19.

Hosted app

For an app served on the agent's origin with the default team login:

import { AmodalProvider, AmodalChat } from '@amodalai/react';
import '@amodalai/react/style.css';

export function App() {
  return (
    <AmodalProvider runtimeUrl={window.location.origin}>
      <AmodalChat />
    </AmodalProvider>
  );
}

The hosted login cookie authenticates same-origin requests. Use an absolute runtime URL. Direct runtime access is suitable only for callers trusted to access the agent's sessions across scopes.

Embed in another app

import { ChatWidget } from '@amodalai/react/widget';
import '@amodalai/react/widget/style.css';

export function AgentChat({ getAppToken }: { getAppToken: () => Promise<string> }) {
  return <ChatWidget serverUrl="https://app.example.com/api/agent" getToken={getAppToken} position="floating" />;
}

getAppToken supplies your application token to the proxy. Your backend must authenticate each request and authorize its scope, session, and operation. Keep runtime credentials on the backend, including short-lived scoped tokens; token scope alone does not isolate session access. The user prop does not authenticate a caller.

API

• AmodalProvider configures clients for data, action, session, and event hooks.
• AmodalChat renders inline chat. It inherits the provider's URL; pass its getToken separately for bearer authentication.
• ChatWidget supports floating, inline, right, and bottom layouts.
• RuntimeClient, SdkClient, and ChatClient provide imperative access.

See the React reference, chat reference, and embedding guide.

License

MIT