Frontend Integration Overview

Frontend integration connects your Helix Agents backend to user interfaces. The @helix-agents/ai-sdk package transforms Helix's streaming protocol into the Vercel AI SDK UI Data Stream format, enabling real-time chat UIs with useChat and other AI SDK hooks.

Why Frontend Integration Matters

AI agents produce:

• Streaming text - Token-by-token responses
• Tool invocations - Tools being called and their results
• Thinking/reasoning - Internal reasoning traces
• Custom events - Application-specific data
• Final outputs - Structured results

Frontend integration delivers these events to your UI in real-time, enabling:

• Progressive text rendering
• Tool call visualization
• Thinking/reasoning displays
• Status indicators
• Error handling

Architecture

┌───────────────────────────────────────────────────────────────────┐
│ Backend                                                            │
│                                                                    │
│  ┌─────────────────┐    ┌───────────────────┐    ┌─────────────┐  │
│  │ Agent Executor  │───▶│ Stream Manager    │───▶│ Frontend    │  │
│  │                 │    │                   │    │ Handler     │  │
│  │ Helix Chunks    │    │ Helix Chunks      │    │             │  │
│  └─────────────────┘    └───────────────────┘    │ Transform   │  │
│                                                   │      ↓      │  │
│                                                   │ AI SDK     │  │
│                                                   │ Events     │  │
│                                                   └─────────────┘  │
└───────────────────────────────────────────────────────────────────┘
                              │
                              │ SSE (Server-Sent Events)
                              ▼
┌───────────────────────────────────────────────────────────────────┐
│ Frontend                                                           │
│                                                                    │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │ useChat Hook (Vercel AI SDK)                                 │  │
│  │                                                              │  │
│  │  messages, input, handleSubmit, ...                         │  │
│  └─────────────────────────────────────────────────────────────┘  │
│                              │                                     │
│                              ▼                                     │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │ React Components                                             │  │
│  │                                                              │  │
│  │  - Message list                                              │  │
│  │  - Tool call displays                                        │  │
│  │  - Input form                                                │  │
│  └─────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────┘

Server-Sent Events (SSE)

SSE provides real-time, server-to-client streaming:

Server                          Client
   │                               │
   │──── text-delta: "Hello " ────▶│
   │──── text-delta: "world" ─────▶│
   │──── tool-input-available ────▶│
   │──── tool-output-available ───▶│
   │──── finish ──────────────────▶│
   │                               │

Benefits over WebSockets:

• Simpler (one-way communication)
• Automatic reconnection
• Works through proxies/CDNs
• Native browser support

Stream Protocol Transformation

Helix internal chunks are transformed to AI SDK UI events:

Helix Chunk	AI SDK Event	Notes
text_delta	text-delta	Token-by-token text
thinking	reasoning-delta	Reasoning traces
tool_start	tool-input-available	Tool call complete
tool_end	tool-output-available	Tool result
custom	data-{eventName}	Custom events
error	error	Error events
output	data-output	Final structured output

Quick Start

Backend Setup

import { createFrontendHandler } from '@helix-agents/ai-sdk';
import { JSAgentExecutor } from '@helix-agents/runtime-js';
import { InMemoryStateStore, InMemoryStreamManager } from '@helix-agents/store-memory';
import { VercelAIAdapter } from '@helix-agents/llm-vercel';

// Create stores and executor
const stateStore = new InMemoryStateStore();
const streamManager = new InMemoryStreamManager();
const executor = new JSAgentExecutor(stateStore, streamManager, new VercelAIAdapter());

// Create frontend handler
const handler = createFrontendHandler({
  streamManager,
  executor,
  agent: MyAgent,
  stateStore, // Optional: for getMessages()
});

// Use with your framework
// See Framework Examples for Express, Hono, etc.

Frontend Setup

import { useChat } from 'ai/react';

function ChatComponent() {
  const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
    api: '/api/chat',
  });

  return (
    <div>
      {messages.map((msg) => (
        <Message key={msg.id} message={msg} />
      ))}

      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} />
        <button type="submit" disabled={isLoading}>Send</button>
      </form>
    </div>
  );
}

Package Contents

The @helix-agents/ai-sdk package provides:

FrontendHandler

Main class that handles HTTP requests:

const handler = createFrontendHandler({
  streamManager,
  executor,
  agent: MyAgent,
});

// Two modes:
// POST - Execute new agent and stream response
// GET  - Stream existing execution (resume)
const response = await handler.handleRequest({
  method: 'POST',
  body: { message: 'Hello' },
});

StreamTransformer

Converts Helix chunks to AI SDK events:

import { StreamTransformer } from '@helix-agents/ai-sdk';

const transformer = new StreamTransformer();

for await (const chunk of helixStream) {
  const { events } = transformer.transform(chunk);
  for (const event of events) {
    yield event;
  }
}

Message Converter

Converts Helix messages to AI SDK v5 UIMessage format:

import { convertToUIMessages } from '@helix-agents/ai-sdk';

const helixMessages = await stateStore.getMessages(runId);
const uiMessages = convertToUIMessages(helixMessages.messages);

// Use as initialMessages in useChat
const { messages } = useChat({
  initialMessages: uiMessages,
});

Typed Errors

Structured error handling:

import {
  FrontendHandlerError,
  ValidationError,
  StreamNotFoundError,
  StreamFailedError,
} from '@helix-agents/ai-sdk';

try {
  await handler.handleRequest(req);
} catch (error) {
  if (error instanceof FrontendHandlerError) {
    return Response.json({ error: error.message, code: error.code }, { status: error.statusCode });
  }
  throw error;
}

Framework Compatibility

The handler produces framework-agnostic responses:

interface FrontendResponse {
  status: number;
  headers: Record<string, string>;
  body: ReadableStream<Uint8Array> | string;
}

This works with any HTTP framework:

• Express
• Hono
• Fastify
• Cloudflare Workers
• Vercel Functions
• AWS Lambda

Stream Resumability

SSE supports automatic reconnection. The handler uses event IDs for resumability:

// Client reconnects with Last-Event-ID header
// Handler resumes from that position
const response = await handler.handleRequest({
  method: 'GET',
  streamId: 'run-123',
  resumeAt: lastEventId, // From Last-Event-ID
});

This enables:

• Network resilience
• Client reconnection
• Page refresh handling

Next Steps

• AI SDK Package - Deep dive into the package
• React Integration - Building React UIs
• Framework Examples - Express, Hono, etc.