useAgUi

React hook that connects an AG-UI protocol agent endpoint to reachat. Returns the props needed by <Chat> plus session helpers, and streams responses via SSE (text/event-stream).

Imports

import { useAgUi } from 'reachat';
import type {
  AgUiEvent,
  AgUiEventType,
  AgUiMessage,
  AgUiTool,
  AgUiContext,
  AgUiToolCallInfo,
  AgUiRunAgentInput,
  UseAgUiOptions,
  UseAgUiReturn
} from 'reachat';

The AG-UI protocol types are bundled with reachat — no separate @ag-ui/core install is needed.

Options

interface UseAgUiOptions {
  agent: string;                              // Endpoint URL (POST + SSE response)
  initialSessions?: Session[];
  initialActiveSessionId?: string;
  tools?: AgUiTool[];                         // Tools to expose to the agent
  context?: AgUiContext[];                    // Extra context per run
  forwardedProps?: Record<string, unknown>;   // Passthrough props to the agent
  headers?: Record<string, string>;           // Custom request headers
  onToolCall?: (toolCall: AgUiToolCallInfo) => Promise<void> | void;
  onError?: (error: Error) => void;
  onEvent?: (event: AgUiEvent) => void;       // Fires for every parsed event
}

Return value

interface UseAgUiReturn {
  sessions: Session[];
  activeSessionId: string | undefined;
  isLoading: boolean;
  selectSession: (sessionId: string) => void;
  deleteSession: (sessionId: string) => void;
  createSession: () => void;
  sendMessage: (message: string) => void;
  stopMessage: () => void;
}

The shape mirrors the props <Chat> expects — pass them through directly.

Basic usage

import { Chat, SessionMessagePanel, SessionMessages, ChatInput, useAgUi } from 'reachat';

function App() {
  const agui = useAgUi({
    agent: 'https://my-agent.example.com/run',
    headers: { Authorization: `Bearer ${token}` },
    onError: err => console.error(err)
  });

  return (
    <Chat
      sessions={agui.sessions}
      activeSessionId={agui.activeSessionId}
      isLoading={agui.isLoading}
      onSelectSession={agui.selectSession}
      onDeleteSession={agui.deleteSession}
      onNewSession={agui.createSession}
      onSendMessage={agui.sendMessage}
      onStopMessage={agui.stopMessage}
    >
      <SessionMessagePanel>
        <SessionMessages />
        <ChatInput />
      </SessionMessagePanel>
    </Chat>
  );
}

Tools and tool calls

Expose tools to the agent and respond when it invokes one:

const agui = useAgUi({
  agent: '/api/agent',
  tools: [
    {
      name: 'searchDocs',
      description: 'Search the knowledge base',
      parameters: { query: { type: 'string' } }
    }
  ],
  onToolCall: async toolCall => {
    if (toolCall.toolCallName === 'searchDocs') {
      const args = JSON.parse(toolCall.args);
      const results = await searchKb(args.query);
      // Tool result handling — push back to your agent as needed
      console.log('searchDocs result', results);
    }
  }
});

Streaming behavior

The hook calls fetch(agent, { method: 'POST', body: JSON.stringify(input) }) and parses the SSE response, dispatching AgUiEvents. It updates the active conversation in-place when TEXT_MESSAGE_CONTENT / TEXT_MESSAGE_CHUNK deltas arrive, and accumulates TOOL_CALL_* events into AgUiToolCallInfo before firing onToolCall on TOOL_CALL_END.

Supported event types include lifecycle (RUN_STARTED, RUN_FINISHED, RUN_ERROR, STEP_*), text (TEXT_MESSAGE_*), tool calls (TOOL_CALL_*), state (STATE_SNAPSHOT, STATE_DELTA, MESSAGES_SNAPSHOT), plus RAW and CUSTOM.

Cancellation

stopMessage() aborts the in-flight fetch via AbortController. The hook also auto-aborts on unmount.

Helpers

These utilities are exported alongside the hook for advanced integrations:

• addConversationToSession(sessions, sessionId, conversation) — immutably append
• updateConversationInSession(sessions, sessionId, conversationId, response) — patch a conversation's response
• sessionsToAgUiMessages(session) — convert reachat history into AgUiMessage[]
• parseSSE(response, signal) — async generator over AgUiEvent | Error
• parseSSELine(line) — single-line SSE parser