@evolutese/react

React components and hooks for building agent-powered UIs with the Evolutese runtime.

Installation

npm install @evolutese/react

Peer dependencies: react >= 18, react-dom >= 18. The backend must expose an SSE endpoint via @evolutese/sdk.

Setup

Wrap your app in EvoluteseProvider and point it at your backend:

import { EvoluteseProvider } from '@evolutese/react';

export default function App() {
  return (
    <EvoluteseProvider
      apiEndpoint="http://localhost:4000/api/assistant"
      tenantId="default"
    >
      <YourApp />
    </EvoluteseProvider>
  );
}

Hooks

useEvoluteseAction

Primary hook — SSE streaming, pending state, and result data in one call.

import { useEvoluteseAction } from '@evolutese/react';

function MyComponent() {
  const { execute, isPending, data, error } = useEvoluteseAction({
    onComplete: (result) => console.log('done', result),
    onError:    (err)    => console.error(err),
  });

  return (
    <button onClick={() => execute({ text: 'Create a task', tenant_id: 'default' })}>
      {isPending ? 'Running…' : 'Run'}
    </button>
  );
}

useAgent

Lower-level hook with full message history and raw SSE event log.

import { useAgent } from '@evolutese/react';

const { state, status, send, reset } = useAgent({
  endpoint: 'http://localhost:4000/api/assistant',
  tenantId: 'default',
  onComplete: (data) => console.log(data),
});

await send({ text: 'List all tasks' });
// state.messages — full chat history
// state.events   — raw SSE events
// status         — 'idle' | 'running' | 'streaming' | 'error'

Components

AgentBar

Left sidebar listing all agents and their intents. Fetches the catalog from GET /api/agents and highlights the currently active intent.

<AgentBar
  fetchAgents={async () => (await fetch('/api/agents')).json().then(d => d.agents)}
  brandName="My App"
  width={300}
  activeKey={view?.intent}
  onNavigate={(key) => handleCommand(key)}
  onClose={() => setOpen(false)}
/>

DynamicViewSlot

Center content area. Renders the right view type — table, form, or document — automatically based on the agent response. No frontend logic to write.

<DynamicViewSlot
  view={view}
  onViewChange={setView}
  onQuickCommand={handleCommand}
  quickCommands={['Create a task', 'List tasks']}
/>

CommandPanel

Chat input + message history + streaming execution trace. Supports rich SuggestionCard items (icon, description, accentColor), an onClear prop, and configurable title, header icon, placeholder, and button labels.

<CommandPanel
  messages={messages}
  onCommand={(text) => execute({ text, tenant_id: 'default' })}
  onClear={() => clearThread(threadId)}
  isLoading={isPending}
  width={384}
/>

AgentPanel

Drawer or fullscreen chat panel — an alternative to CommandPanel with a more opinionated layout. Slides in from the right in drawer mode or fills its container in fullscreen mode.

import { AgentPanel, type AgentPanelMessage } from '@evolutese/react';

const messages: AgentPanelMessage[] = [
  { type: 'system', text: 'Welcome! How can I help?' },
  { type: 'user', text: 'List all invoices' },
  { type: 'agent', text: 'Here are your invoices…', streaming: false },
];

<AgentPanel
  mode="drawer"
  open={panelOpen}
  onClose={() => setPanelOpen(false)}
  context={[{ label: 'Tenant: acme', active: true }]}
  messages={messages}
  suggestions={['Create invoice', 'List customers']}
  onSend={(text) => execute({ text, tenant_id: 'default' })}
  isLoading={isPending}
  modelLabel="gemini"
/>

Message types

| type | Fields | Rendered as | |------|--------|------------| | system | text | Muted system note | | user | text | Right-aligned user bubble | | agent | text, html?, streaming?, formLink? | Left-aligned agent bubble | | tool | name, args? | Compact tool-call badge | | result | text, ok? | Success/error result line |

Full layout

The three components are designed to compose into a standard agent UI:

import { EvoluteseProvider, AgentBar, DynamicViewSlot, CommandPanel, AgentPanel } from '@evolutese/react';

export default function Layout() {
  return (
    <EvoluteseProvider apiEndpoint="http://localhost:4000/api/assistant" tenantId="default">
      <div className="flex h-screen">
        <AgentBar fetchAgents={fetchAgents} brandName="My App" onNavigate={handleCommand} />
        <div className="flex-1">
          <DynamicViewSlot view={view} onViewChange={setView} onQuickCommand={handleCommand} />
        </div>
        <CommandPanel messages={messages} onCommand={handleCommand} isLoading={isPending} />
      </div>
    </EvoluteseProvider>
  );
}

evolutese init scaffolds this layout automatically in the generated frontend.

License

MIT