agui-react-wrapper

AGUI LangGraph Frontend

A comprehensive React component library for building chat interfaces with AG-UI LangGraph agents

📋 Table of Contents

• Overview
• Installation
• Quick Start
• Architecture
• API Reference
  • Components
  • Hooks
  • Utilities
  • Type Definitions
• Usage Examples
• Advanced Patterns
• Development Guide
• Troubleshooting
• Reference

🎯 Overview

agui-react-wrapper is a production-ready npm package that wraps the AG-UI LangGraph agent functionality into reusable React components. It provides a complete solution for integrating agent-based chat functionality into React applications.

✨ Key Features

Feature	Description
Real-time Streaming	Live message streaming from LangGraph agents with Server-Sent Events
Event Tracking	Comprehensive event tracking (runs, steps, tool calls, state changes)
Dynamic Parameters	Runtime-configurable parameters with automatic UI generation
Flexible Composition	Use components standalone or combine them for custom layouts
TypeScript Support	Full type definitions for all exports
Standalone Utilities	Non-React functions for programmatic usage
Zero Dependencies	No external styling dependencies (inline styles)

🏗️ What's Included

• Chat Interface: Full-featured chat panel with message streaming
• Event Logging: Real-time event tracking and visualization
• Parameter Management: Dynamic parameter fields with automatic input type detection
• React Hooks: Custom hooks for state management
• Utility Functions: Standalone functions for non-React environments

📦 Installation

Basic Installation

npm install agui-react-wrapper

Peer Dependencies

This package requires React 18+ and React DOM 18+:

npm install react@^18.0.0 react-dom@^18.0.0

Package Information

Property	Value
Package Name	agui-react-wrapper
Version	1.0.0
License	MIT
Main Entry	./dist/index.js
Module Entry	./dist/index.es.js
Type Definitions	./dist/index.d.ts

🚀 Quick Start

Basic Usage (Combined Component)

The simplest way to get started is using the combined ChatWithEventLog component:

import React from "react";
import { ChatWithEventLog, type AGUIConfig } from "agui-react-wrapper";

function App() {
  const config: AGUIConfig = {
    backendUrl: "http://localhost:8899/api/get_deviation_analysis",
    parameters: {
      application_id: "APP-002",
      user_email: "[e-mail]",
    },
    title: "Agent Chat",
    subtitle: "Chat with your LangGraph agent",
  };

  return <ChatWithEventLog config={config} />;
}

Standalone Components

For more control, use components separately:

import React from "react";
import { ChatPanel, EventLog, useEventLog } from "agui-react-wrapper";

function App() {
  const { eventLog, addEvent } = useEventLog();

  return (
    <div style={{ display: "flex", gap: "1rem" }}>
      <ChatPanel
        backendUrl="http://localhost:8899/api/endpoint"
        parameters={{ application_id: "APP-002" }}
        onEvent={addEvent}
      />
      <EventLog events={eventLog} />
    </div>
  );
}

🏛️ Architecture

Package Structure

agui-react-wrapper/
├── components/
│   ├── ChatPanel/          # Standalone chat interface
│   │   ├── ChatPanel.tsx
│   │   ├── MessageList.tsx
│   │   ├── MessageBubble.tsx
│   │   └── MessageInput.tsx
│   ├── EventLog/           # Standalone event log display
│   │   ├── EventLog.tsx
│   │   └── EventLogEntry.tsx
│   └── ChatWithEventLog/   # Combined component
│       └── ChatWithEventLog.tsx
├── hooks/
│   ├── useAgentChat.ts     # Chat state management
│   ├── useEventLog.ts      # Event log state management
│   ├── useEventStream.ts   # Event forwarding utilities
│   └── useParameters.ts    # Parameter state management
├── utils/
│   ├── sendMessage.ts      # Standalone message sending
│   ├── getEventIcon.ts     # Event icon mapping
│   └── getEventBadgeColor.ts # Event color mapping
├── classes/
│   └── CustomHttpAgent.class.ts # Extended HttpAgent with parameters
└── interfaces/
    └── EventLogEntry.interface.ts # Event log entry type

Data Flow Diagram

┌─────────────┐
│ User Input  │
└──────┬──────┘
       │
       ▼
┌─────────────────┐     ┌──────────────────┐
│  MessageInput   │────▶│  useAgentChat    │
└─────────────────┘     └────────┬─────────┘
                                  │
                                  ▼
                         ┌──────────────────┐
                         │ CustomHttpAgent  │
                         └────────┬─────────┘
                                  │
                                  ▼
                         ┌──────────────────┐
                         │  Event Stream    │
                         └────────┬─────────┘
                                  │
                    ┌─────────────┴─────────────┐
                    │                           │
                    ▼                           ▼
         ┌──────────────────┐      ┌──────────────────┐
         │  useEventLog     │      │  useAgentChat    │
         └────────┬─────────┘      └────────┬─────────┘
                  │                         │
                  ▼                         ▼
         ┌──────────────────┐      ┌──────────────────┐
         │   EventLog       │      │   MessageList    │
         └──────────────────┘      └──────────────────┘

Component Hierarchy

ChatWithEventLog (Combined Component)
│
├── ChatPanel
│   ├── MessageList
│   │   └── MessageBubble[] (for each message)
│   └── MessageInput
│       └── ParameterFields[] (dynamic, based on parameters)
│
└── EventLog
    └── EventLogEntry[] (for each event)

📚 API Reference

Components

ChatWithEventLog / AGUIComponent

The combined component that includes both chat and event log panels in a side-by-side layout.

Import:

import { ChatWithEventLog, AGUIComponent } from "agui-react-wrapper";
// Note: AGUIComponent is an alias for ChatWithEventLog (backward compatibility)

Props:

Prop	Type	Required	Default	Description
config	AGUIConfig	✅	-	Configuration object for the component
onParametersChange	(params: Record<string, any>) => void	❌	-	Callback when parameters are updated

Example:

<ChatWithEventLog
  config={{
    backendUrl: "http://localhost:8899/api/endpoint",
    parameters: { application_id: "APP-002" },
    showEventLog: true,
    showParameterFields: true,
    title: "My Chat",
    subtitle: "Chat with the agent",
  }}
  onParametersChange={(params) => console.log(params)}
/>

Features:

• ✅ Side-by-side layout with chat and event log
• ✅ Toggle event log visibility
• ✅ Automatic event log clearing on new runs
• ✅ Full-page wrapper with gradient background

ChatPanel

Standalone chat interface component with real-time message streaming.

Import:

import { ChatPanel } from "agui-react-wrapper";

Props:

Prop	Type	Required	Default	Description
backendUrl	string	✅	-	Backend API endpoint URL
parameters	Record<string, any>	❌	{}	Request parameters to send with each message
headers	Record<string, string>	❌	-	Custom HTTP headers
title	string	❌	-	Chat interface title
subtitle	string	❌	-	Chat interface subtitle
showParameterFields	boolean	❌	true	Show parameter input fields
onParametersChange	(params: Record<string, any>) => void	❌	-	Callback when parameters are updated
onEvent	(event: BaseEvent) => void	❌	-	Callback when events occur
compact	boolean	❌	false	Skip full-page wrapper (for custom layouts)

Example:

<ChatPanel
  backendUrl="http://localhost:8899/api/endpoint"
  parameters={{
    application_id: "APP-002",
    user_email: "[e-mail]",
  }}
  headers={{
    Authorization: "Bearer token",
  }}
  title="My Chat"
  subtitle="Chat with the agent"
  showParameterFields={true}
  onEvent={(event) => console.log("Event:", event)}
  compact={false}
/>

Features:

• ✅ Real-time message streaming
• ✅ Dynamic parameter field generation
• ✅ Auto-scrolling message list
• ✅ Customizable headers and styling
• ✅ Event emission for external integration

EventLog

Standalone event log component for displaying agent events in real-time.

Import:

import { EventLog } from "agui-react-wrapper";

Props:

Prop	Type	Required	Default	Description
events	EventLogEntry[]	✅	-	Array of event log entries to display
onEvent	(event: any) => void	❌	-	External event handler (for uncontrolled mode)
autoScroll	boolean	❌	true	Auto-scroll to bottom when new events arrive
title	string	❌	"Event Log"	Title for the event log

Example:

<EventLog events={eventLog} autoScroll={true} title="Agent Events" />

Features:

• ✅ Color-coded event badges by type
• ✅ Expandable event details (JSON view)
• ✅ Timestamp display
• ✅ Auto-scrolling to latest events
• ✅ Empty state handling

Sub-Components

MessageList

Component for displaying chat messages.

Props:

interface MessageListProps {
  messages: Message[];
  chatEndRef: React.RefObject<HTMLDivElement>;
}

MessageBubble

Individual message bubble component.

Props:

interface MessageBubbleProps {
  message: Message;
}

MessageInput

Input component with parameter fields and message input.

Props:

interface MessageInputProps {
  onSendMessage: (input: string) => void;
  parameters: Record<string, any>;
  onParametersChange: (params: Record<string, any>) => void;
  showParameterFields?: boolean;
}

Parameter Field Types:

• Strings < 100 chars: Text input
• Strings ≥ 100 chars: Textarea (6 rows)
• Numbers: Number input
• Keys containing "email": Email input
• Other types: Textarea (2 rows)

EventLogEntry

Individual event log entry component.

Props:

interface EventLogEntryProps {
  entry: EventLogEntry;
}

Hooks

useAgentChat

Hook for managing agent chat state and execution.

Import:

import { useAgentChat } from "agui-react-wrapper";

Signature:

function useAgentChat(
  options: UseAgentChatOptions,
  callbacks?: RunAgentCallbacks
): UseAgentChatReturn;

Parameters:

Parameter	Type	Required	Description
options	UseAgentChatOptions	✅	Configuration options
callbacks	RunAgentCallbacks	❌	Additional event callbacks

Options Interface:

interface UseAgentChatOptions {
  backendUrl: string;
  parameters: Record<string, any>;
  headers?: Record<string, string>;
  onEvent?: (event: BaseEvent) => void;
}

Returns:

Property	Type	Description
messages	Message[]	Array of chat messages
sendMessage	(input: string) => Promise<void>	Function to send a message
clearMessages	() => void	Function to clear all messages
chatEndRef	React.RefObject<HTMLDivElement>	Ref for auto-scrolling

Example:

const { messages, sendMessage, clearMessages, chatEndRef } = useAgentChat({
  backendUrl: "http://localhost:8899/api/endpoint",
  parameters: { application_id: "APP-002" },
  headers: { Authorization: "Bearer token" },
  onEvent: (event) => console.log(event),
});

Features:

• ✅ Automatic message state management
• ✅ Agent instance lifecycle management
• ✅ Event forwarding
• ✅ Auto-scrolling to latest message

useEventLog

Hook for managing event log state.

Import:

import { useEventLog } from "agui-react-wrapper";

Signature:

function useEventLog(autoScroll?: boolean): UseEventLogReturn;

Parameters:

Parameter	Type	Required	Default	Description
autoScroll	boolean	❌	true	Enable auto-scrolling

Returns:

Property	Type	Description
eventLog	EventLogEntry[]	Array of event log entries
addEvent	(event: BaseEvent) => void	Function to add an event
clearEventLog	() => void	Function to clear all events
eventLogEndRef	React.RefObject<HTMLDivElement>	Ref for auto-scrolling

Example:

const { eventLog, addEvent, clearEventLog, eventLogEndRef } = useEventLog(true);

Features:

• ✅ Event array management
• ✅ Automatic event entry creation
• ✅ Auto-scrolling support
• ✅ Event type mapping

useEventStream

Hook that creates event callbacks to forward all events to a handler function.

Import:

import { useEventStream } from "agui-react-wrapper";

Signature:

function useEventStream(
  addEvent: (event: BaseEvent) => void
): RunAgentCallbacks;

Parameters:

Parameter	Type	Required	Description
addEvent	(event: BaseEvent) => void	✅	Function to handle events

Returns:

Property	Type	Description
RunAgentCallbacks	RunAgentCallbacks	Complete callback object for agent events

Example:

const { addEvent } = useEventLog();
const eventCallbacks = useEventStream(addEvent);

// Use with sendMessage or agent.runAgent
await sendMessage({
  url: "...",
  input: "Hello",
  callbacks: eventCallbacks,
});

Features:

• ✅ Comprehensive event forwarding
• ✅ Memoized callback object
• ✅ Compatible with all agent event types

useParameters

Hook for managing dynamic parameters state.

Import:

import { useParameters } from "agui-react-wrapper";

Signature:

function useParameters(
  initialParameters?: Record<string, any>,
  onParametersChange?: (params: Record<string, any>) => void
): UseParametersReturn;

Parameters:

Parameter	Type	Required	Default	Description
initialParameters	Record<string, any>	❌	{}	Initial parameter values
onParametersChange	(params: Record<string, any>) => void	❌	-	Callback when parameters change

Returns:

Property	Type	Description
parameters	Record<string, any>	Current parameter values
setParameters	(params: Record<string, any>) => void	Function to set all parameters
updateParameter	(key: string, value: any) => void	Function to update a single parameter

Example:

const { parameters, setParameters, updateParameter } = useParameters(
  { application_id: "APP-002" },
  (params) => console.log("Parameters changed:", params)
);

Features:

• ✅ Parameter state management
• ✅ Change notifications
• ✅ Individual parameter updates

Utilities

sendMessage

Standalone function to send a message to an AG-UI agent endpoint without React.

Import:

import { sendMessage } from "agui-react-wrapper";

Signature:

async function sendMessage(
  options: SendMessageOptions
): Promise<SendMessageResult>;

Options:

Option	Type	Required	Description
url	string	✅	Backend API endpoint URL
input	string	✅	Message text to send
parameters	Record<string, any>	❌	Request parameters
headers	Record<string, string>	❌	Custom HTTP headers
onEvent	(event: BaseEvent) => void	❌	Event callback
callbacks	RunAgentCallbacks	❌	Additional event callbacks
messages	Message[]	❌	Initial message history

Returns:

Property	Type	Description
answer	string	Final answer text from the agent
result	any	Full result from the agent run
newMessages	Message[]	New messages from the agent

Example:

import { sendMessage } from "agui-react-wrapper";

const result = await sendMessage({
  url: "http://localhost:8899/api/endpoint",
  input: "Hello, agent!",
  parameters: {
    application_id: "APP-002",
    user_email: "[e-mail]",
  },
  headers: {
    Authorization: "Bearer token",
  },
  onEvent: (event) => {
    console.log("Event:", event);
  },
  callbacks: {
    onTextMessageContentEvent: ({ event }) => {
      console.log("Content delta:", (event as any).delta);
    },
  },
});

console.log("Final answer:", result.answer);
console.log("Result:", result.result);
console.log("New messages:", result.newMessages);

Features:

• ✅ Non-React usage
• ✅ Promise-based API
• ✅ Full event callback support
• ✅ Returns final answer and result

getEventIcon

Utility function to get an icon for an event type.

Import:

import { getEventIcon } from "agui-react-wrapper";

Signature:

function getEventIcon(eventType: string): string;

Returns:

Event Type	Icon
RUN events	"▶"
STEP events	"▸"
TOOL events	"⚙"
TEXT_MESSAGE events	"💬"
STATE events	"📊"
Other events	"•"

getEventBadgeColor

Utility function to get color scheme for an event type badge.

Import:

import { getEventBadgeColor } from "agui-react-wrapper";

Signature:

function getEventBadgeColor(eventType: string): {
  bg: string;
  text: string;
  border: string;
};

Returns: Color scheme object with background, text, and border colors.

Type Definitions

AGUIConfig

Configuration object for combined components.

interface AGUIConfig {
  backendUrl: string;
  parameters?: Record<string, any>;
  headers?: Record<string, string>;
  title?: string;
  subtitle?: string;
  showEventLog?: boolean;
  showParameterFields?: boolean;
}

EventLogEntry

Event log entry interface.

interface EventLogEntry {
  id: string;
  timestamp: Date;
  event: BaseEvent;
  eventType: string;
}

RunAgentCallbacks

Complete event callback interface.

interface RunAgentCallbacks {
  onRunStartedEvent?: ({ event }: { event: BaseEvent }) => void;
  onRunFinishedEvent?: ({ event }: { event: BaseEvent }) => void;
  onRunErrorEvent?: ({ event }: { event: BaseEvent }) => void;
  onStepStartedEvent?: ({ event }: { event: BaseEvent }) => void;
  onStepFinishedEvent?: ({ event }: { event: BaseEvent }) => void;
  onTextMessageStartEvent?: ({ event }: { event: BaseEvent }) => void;
  onTextMessageContentEvent?: ({ event }: { event: BaseEvent }) => void;
  onTextMessageEndEvent?: ({ event }: { event: BaseEvent }) => void;
  onToolCallStartEvent?: ({ event }: { event: BaseEvent }) => void;
  onToolCallArgsEvent?: ({ event }: { event: BaseEvent }) => void;
  onToolCallEndEvent?: ({ event }: { event: BaseEvent }) => void;
  onToolCallResultEvent?: ({ event }: { event: BaseEvent }) => void;
  onStateDeltaEvent?: ({ event }: { event: BaseEvent }) => void;
  onStateSnapshotEvent?: ({ event }: { event: BaseEvent }) => void;
  onRawEvent?: ({ event }: { event: BaseEvent }) => void;
  onCustomEvent?: ({ event }: { event: BaseEvent }) => void;
}

Type Imports:

import type {
  AGUIConfig,
  ChatPanelProps,
  EventLogProps,
  UseAgentChatOptions,
  UseAgentChatReturn,
  EventLogEntry,
  SendMessageOptions,
  SendMessageResult,
} from "agui-react-wrapper";

💡 Usage Examples

Example 1: Basic Chat with Event Log

import React from "react";
import { ChatWithEventLog, type AGUIConfig } from "agui-react-wrapper";

function App() {
  const config: AGUIConfig = {
    backendUrl: "http://localhost:8899/api/get_deviation_analysis",
    parameters: {
      application_id: "APP-002",
      user_email: "[e-mail]",
      subject: "Email subject",
      body: "Email body content",
    },
    title: "Deviation Analysis Chat",
    subtitle: "Analyze deviations with AI assistance",
    showEventLog: true,
    showParameterFields: true,
  };

  return <ChatWithEventLog config={config} />;
}

Example 2: Custom Layout with Separate Components

import React from "react";
import { ChatPanel, EventLog, useEventLog } from "agui-react-wrapper";
import { BaseEvent, EventType } from "@ag-ui/core";

function CustomChatApp() {
  const { eventLog, addEvent, clearEventLog } = useEventLog(true);

  const handleChatEvent = (event: BaseEvent) => {
    // Clear event log on new run start
    if (event.type === EventType.RUN_STARTED) {
      clearEventLog();
    }
    addEvent(event);
  };

  return (
    <div style={{ display: "flex", gap: "1.5rem", padding: "2rem" }}>
      <div style={{ flex: 1 }}>
        <ChatPanel
          backendUrl="http://localhost:8899/api/endpoint"
          parameters={{ application_id: "APP-002" }}
          onEvent={handleChatEvent}
          compact={true}
        />
      </div>
      <div style={{ flex: 1 }}>
        <EventLog events={eventLog} />
      </div>
    </div>
  );
}

Example 3: Using Hooks Directly

import React, { useState } from "react";
import {
  useAgentChat,
  MessageList,
  MessageInput,
} from "agui-react-wrapper";

function CustomChat() {
  const { messages, sendMessage, chatEndRef } = useAgentChat({
    backendUrl: "http://localhost:8899/api/endpoint",
    parameters: { application_id: "APP-002" },
    onEvent: (event) => {
      console.log("Event:", event);
    },
  });

  const [input, setInput] = useState("");

  return (
    <div>
      <MessageList messages={messages} chatEndRef={chatEndRef} />
      <input
        value={input}
        onChange={(e) => setInput(e.target.value)}
        onKeyDown={(e) => {
          if (e.key === "Enter") {
            sendMessage(input);
            setInput("");
          }
        }}
      />
    </div>
  );
}

Example 4: Standalone sendMessage Usage

import { sendMessage } from "agui-react-wrapper";

async function sendAgentMessage() {
  try {
    const result = await sendMessage({
      url: "http://localhost:8899/api/endpoint",
      input: "Analyze this data",
      parameters: {
        application_id: "APP-002",
        user_email: "[e-mail]",
      },
      headers: {
        Authorization: "Bearer your-token",
      },
      onEvent: (event) => {
        console.log("Event received:", event);
      },
    });

    console.log("Agent response:", result.answer);
    return result;
  } catch (error) {
    console.error("Error:", error);
    throw error;
  }
}

Example 5: Dynamic Parameters

import React, { useState } from "react";
import { ChatPanel } from "agui-react-wrapper";

function DynamicParamsExample() {
  const [params, setParams] = useState({
    application_id: "APP-002",
    user_email: "[e-mail]",
    priority: 1,
    description: "Long description text that will be rendered as a textarea",
  });

  return (
    <ChatPanel
      backendUrl="http://localhost:8899/api/endpoint"
      parameters={params}
      onParametersChange={(newParams) => {
        console.log("Parameters updated:", newParams);
        setParams(newParams);
      }}
      showParameterFields={true}
    />
  );
}

🔧 Advanced Patterns

Pattern 1: Multiple Chat Instances

import React from "react";
import { ChatPanel, useEventLog } from "agui-react-wrapper";

function MultiChatApp() {
  const chat1Events = useEventLog();
  const chat2Events = useEventLog();

  return (
    <div
      style={{ display: "grid", gridTemplateColumns: "1fr 1fr", gap: "1rem" }}
    >
      <ChatPanel
        backendUrl="http://localhost:8899/api/endpoint1"
        parameters={{ application_id: "APP-001" }}
        onEvent={chat1Events.addEvent}
      />
      <ChatPanel
        backendUrl="http://localhost:8899/api/endpoint2"
        parameters={{ application_id: "APP-002" }}
        onEvent={chat2Events.addEvent}
      />
    </div>
  );
}

Pattern 2: Conditional Event Log

import React, { useState } from "react";
import { ChatPanel, EventLog, useEventLog } from "agui-react-wrapper";

function ConditionalEventLog() {
  const [showLog, setShowLog] = useState(false);
  const { eventLog, addEvent } = useEventLog(showLog);

  return (
    <div>
      <button onClick={() => setShowLog(!showLog)}>
        {showLog ? "Hide" : "Show"} Event Log
      </button>
      <div style={{ display: "flex", gap: "1rem" }}>
        <ChatPanel
          backendUrl="http://localhost:8899/api/endpoint"
          onEvent={addEvent}
        />
        {showLog && <EventLog events={eventLog} />}
      </div>
    </div>
  );
}

Pattern 3: Custom Event Processing

import React from "react";
import { ChatPanel, useEventLog } from "agui-react-wrapper";
import { BaseEvent, EventType } from "@ag-ui/core";

function CustomEventProcessing() {
  const { eventLog, addEvent } = useEventLog();

  const handleEvent = (event: BaseEvent) => {
    // Custom processing
    if (event.type === EventType.TOOL_CALL_START) {
      console.log("Tool call started:", event);
      // Send analytics event
      analytics.track("tool_call_started", { tool: (event as any).tool });
    }

    // Add to event log
    addEvent(event);
  };

  return (
    <ChatPanel
      backendUrl="http://localhost:8899/api/endpoint"
      onEvent={handleEvent}
    />
  );
}

Pattern 4: Parameter Validation

import React, { useState } from "react";
import { ChatPanel } from "agui-react-wrapper";

function ValidatedParams() {
  const [params, setParams] = useState({
    application_id: "",
    user_email: "",
  });

  const handleParamsChange = (newParams: Record<string, any>) => {
    // Validate email
    if (newParams.user_email && !newParams.user_email.includes("@")) {
      alert("Invalid email address");
      return;
    }

    // Validate application ID
    if (newParams.application_id && newParams.application_id.length < 3) {
      alert("Application ID must be at least 3 characters");
      return;
    }

    setParams(newParams);
  };

  return (
    <ChatPanel
      backendUrl="http://localhost:8899/api/endpoint"
      parameters={params}
      onParametersChange={handleParamsChange}
    />
  );
}

🛠️ Development Guide

Building the Package

To build the package for distribution:

npm run build:lib

This command:

• Removes the existing dist directory
• Generates TypeScript declaration files (.d.ts)
• Builds the library in both ES module and CommonJS formats
• Creates source maps

Output Files:

• dist/index.js - CommonJS bundle
• dist/index.es.js - ES module bundle
• dist/index.d.ts - TypeScript declarations

Development Mode

For local development with hot reload:

npm run dev

Preview Build

To preview the built package:

npm run serve

Clean Build Artifacts

npm run clean

Publishing

Before publishing, ensure:

• ✅ Version is updated in package.json
• ✅ Build is successful: npm run build:lib
• ✅ Tests pass (if applicable)
• ✅ README is up to date

Then publish:

npm publish

The prepublishOnly script will automatically run build:lib before publishing.

🔍 Troubleshooting

Common Issues

Issue: Events not appearing in EventLog

Possible Causes:

• onEvent callback is not connected
• Events are not being emitted from the agent
• Event log state is not being updated

Solution:

// Ensure onEvent is connected
<ChatPanel
  backendUrl="..."
  onEvent={addEvent} // ✅ Make sure this is set
/>

Issue: Parameters not being sent

Possible Causes:

• Parameters object is not properly structured
• Backend endpoint doesn't accept parameters in request body
• CustomHttpAgent is not properly extending HttpAgent

Solution:

// Verify parameters structure
<ChatPanel
  backendUrl="..."
  parameters={{
    application_id: "APP-002", // ✅ Ensure proper structure
    user_email: "[e-mail]",
  }}
/>

Issue: Messages not streaming

Possible Causes:

• Backend doesn't support streaming responses
• Network issues with SSE connections
• onTextMessageContentEvent callbacks not working

Solution:

• Check network tab for SSE (Server-Sent Events) connections
• Verify backend supports streaming
• Ensure callbacks are properly configured

Issue: TypeScript errors

Possible Causes:

• React 18 types not installed
• Peer dependencies missing
• TypeScript version incompatible

Solution:

npm install --save-dev @types/react@^18.0.0 @types/react-dom@^18.0.0
npm install react@^18.0.0 react-dom@^18.0.0

📖 Reference

Peer Dependencies

Package	Version	Purpose
react	^18.0.0	React library
react-dom	^18.0.0	React DOM rendering

Runtime Dependencies

Package	Version	Purpose
@ag-ui/client	^0.0.41	AG-UI client library
@ag-ui/core	^0.0.41	AG-UI core types and utilities
rxjs	^7.0.0	Reactive extensions (used by AG-UI)

TypeScript Support

This package is written in TypeScript and includes full type definitions. All exports are typed, including:

• ✅ Component props
• ✅ Hook parameters and return types
• ✅ Utility function signatures
• ✅ Configuration interfaces
• ✅ Event types

Event Types

The package supports all AG-UI event types:

Event Type	Description
RUN_STARTED	Agent run started
RUN_FINISHED	Agent run completed
RUN_ERROR	Agent run error
STEP_STARTED	Step execution started
STEP_FINISHED	Step execution finished
TEXT_MESSAGE_START	Text message streaming started
TEXT_MESSAGE_CONTENT	Text message content delta
TEXT_MESSAGE_END	Text message streaming finished
TOOL_CALL_START	Tool call started
TOOL_CALL_ARGS	Tool call arguments
TOOL_CALL_END	Tool call finished
TOOL_CALL_RESULT	Tool call result
STATE_DELTA	State delta update
STATE_SNAPSHOT	State snapshot
RAW_EVENT	Raw event
CUSTOM	Custom event

Styling

The package uses inline styles and does not require any external CSS. All components are self-contained with their styling.

Design System:

• Modern gradient backgrounds
• Rounded corners (8-16px border radius)
• Subtle shadows and borders
• Responsive spacing
• Accessible color contrasts

Customization Options:

• Wrap components with your own styled containers
• Use CSS-in-JS libraries to override styles
• Fork and modify the component source code

Browser Support

This package supports all modern browsers that support:

• ✅ ES6+ JavaScript features
• ✅ React 18
• ✅ Fetch API
• ✅ EventSource/Server-Sent Events (for streaming)

Contributing

This is a published npm package. For contributions:

• Fork the repository
• Create a feature branch
• Make your changes
• Build and test: npm run build:lib
• Submit a pull request

📄 License

MIT

📞 Support

For issues, questions, or contributions, please refer to the package repository or contact the maintainers.

Version: 1.0.0
Last Updated: 2024

Made with ❤️ for the AG-UI community