AgentThreadHistory

AgentThreadHistory renders a scrollable, paginated list of past conversations for the current user. It handles loading, empty, error, and unavailable states automatically. Must be used inside AgentProvider.

Requirements

Conversation history requires the session to be created with external_owner_id. See Authentication for the server-side setup.

Usage

You can render AgentThreadHistory anywhere inside AgentProvider. The built-in toggle in AgentChat already does this for you. For a custom layout, render it directly:

import { AgentProvider, AgentThreadHistory } from '@kapaai/agent-react';

function App() {
  return (
    <AgentProvider
      getSessionToken={async () => {
        const res = await fetch('/api/session', { method: 'POST' });
        return res.json();
      }}
      projectId="your-project-id"
      integrationId="your-integration-id"
      model="kapa-agent-1.0"
    >
      <div style={{ display: 'flex', height: '100vh' }}>
        <aside style={{ width: 280 }}>
          <AgentThreadHistory
            onThreadSelected={(threadId) => {
              // The thread is already being resumed by the time this fires.
              // Use it to navigate, close a drawer, etc.
              console.log('Resumed thread', threadId);
            }}
          />
        </aside>
        <main style={{ flex: 1 }}>
          <AgentChat branding={{ title: 'AI Assistant' }} />
        </main>
      </div>
    </AgentProvider>
  );
}

Props

Prop	Type	Default	Description
onThreadSelected	(threadId: string) => void	-	Called after a thread is successfully resumed.
className	string	-	CSS class applied to the root element.

States

AgentThreadHistory renders different UI depending on the current state:

State	When
Loading	Initial fetch is in progress.
Empty	The session owner has no past threads.
Unavailable	The session was created without external_owner_id.
Error	A network or API error occurred.
List	Threads are available. Shows title, relative time, and message count per row.

Each row has a delete button that appears on hover. Clicking it shows a confirmation step. Clicking again confirms the deletion.

Integration with AgentChat

AgentChat includes a built-in history toggle button (clock icon) in the header. When clicked, the chat body is replaced by AgentThreadHistory. Clicking a thread resumes it and returns to chat view. Clicking the toggle again returns to the current chat without changing state.

The toggle is only shown when the session has external_owner_id. It is hidden when enableHistory is set to true on AgentProvider.

Disabling history

Set enableHistory={false} on AgentProvider (the default) to keep history disabled:

<AgentProvider enableHistory={false} {...otherProps}>
  <AgentChat />
</AgentProvider>

When enableHistory is not set or false:

• The history toggle in AgentChat is hidden.
• AgentThreadHistory renders the unavailable state.
• listThreads, resumeThread, and deleteThread throw HistoryDisabledError without making a network call.

Error classes

These classes are exported from @kapaai/agent-core:

Class	Thrown when
SessionWithoutOwnerError	listThreads is called but the session has no external_owner_id.
ThreadNotFoundError	resumeThread or deleteThread is called with an ID that does not exist or belongs to a different owner.
HistoryDisabledError	Any history method is called when enableHistory is false or not set.

import {
  ThreadNotFoundError,
  SessionWithoutOwnerError,
  HistoryDisabledError,
} from '@kapaai/agent-core';

For headless usage (without AgentThreadHistory), call the methods directly via useAgentChat() or the Agent class. See Conversation history in the core SDK docs.