@kuntur/a2a-carbon-chat-adapter 0.1.17 → 1.0.0

package/README.md

@@ -1,19 +1,88 @@
 # @kuntur/a2a-carbon-chat-adapter
 
-A2A protocol adapter for Carbon AI Chat - connect any A2A agent to Carbon UI.
+[![npm version](https://img.shields.io/npm/v/@kuntur/a2a-carbon-chat-adapter.svg)](https://www.npmjs.com/package/@kuntur/a2a-carbon-chat-adapter)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Installation
+**Production-ready A2A protocol adapter for Carbon AI Chat** - Connect any Agent2Agent protocol agent to IBM Carbon Design System chat UI with full streaming support, multi-agent management, and extensible rendering.
+
+---
+
+## 📋 Table of Contents
+
+- [Overview](#overview)
+- [Why This Library?](#why-this-library)
+- [Quick Start](#quick-start)
+- [⚠️ Server Proxy Setup (Required)](#️-server-proxy-setup-required)
+- [Core Concepts](#core-concepts)
+- [API Reference](#api-reference)
+- [Advanced Usage](#advanced-usage)
+- [Examples](#examples)
+- [Architecture](#architecture)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Overview
+
+`@kuntur/a2a-carbon-chat-adapter` is a TypeScript library that bridges the [Agent2Agent (A2A) protocol](https://github.com/agentstack/a2a) with IBM's [Carbon AI Chat](https://github.com/carbon-design-system/carbon-for-ai) component. It provides:
+
+- **Protocol Translation**: Converts A2A streaming responses to Carbon AI Chat's message format
+- **Multi-Agent Support**: Built-in context provider for managing multiple agents
+- **Extension System**: Handles A2A UI extensions (citations, forms, errors)
+- **Server Utilities**: Ready-to-use API handlers for Next.js and other frameworks
+- **Type Safety**: Full TypeScript support with comprehensive type definitions
+
+This library is designed for production use in enterprise applications requiring AI agent integration with Carbon Design System.
+
+---
+
+## Why This Library?
+
+### The Problem
+
+Integrating A2A protocol agents with Carbon AI Chat requires:
+
+1. **Protocol Translation**: A2A uses Server-Sent Events (SSE) streaming; Carbon expects a specific message format
+2. **CORS Handling**: Browser security prevents direct agent connections
+3. **Extension Parsing**: A2A UI extensions need custom rendering logic
+4. **State Management**: Multi-agent scenarios require context management
+
+### The Solution
+
+This library provides:
+
+- ✅ **Drop-in Components**: `<A2AChat>` component with full A2A support
+- ✅ **Server Proxy**: Pre-built API handlers for streaming proxy setup
+- ✅ **Extension Renderers**: Built-in components for citations, forms, and errors
+- ✅ **Multi-Agent Context**: `AgentProvider` for seamless agent switching
+- ✅ **Programmatic API**: Hooks for custom implementations
+
+### Benefits
+
+- **Faster Development**: Skip protocol implementation, focus on your application
+- **Production Ready**: Battle-tested streaming, error handling, and state management
+- **Type Safe**: Full TypeScript support prevents runtime errors
+- **Extensible**: Custom renderers and hooks for advanced use cases
+- **Carbon Native**: Seamless integration with Carbon Design System
+
+---
+
+## Quick Start
+
+### Installation
 
 ```bash
 npm install @kuntur/a2a-carbon-chat-adapter @carbon/ai-chat react react-dom
 ```
 
-## Quick Start
+### Basic Usage
 
 ```tsx
 import { A2AChat } from '@kuntur/a2a-carbon-chat-adapter';
-import '@kuntur/a2a-carbon-chat-adapter/styles'; // Adapter layout styles
-import '@carbon/ai-chat/dist/styles.css';        // Carbon AI Chat styles (if not already imported)
+import '@kuntur/a2a-carbon-chat-adapter/styles';
+import '@carbon/ai-chat/dist/styles.css';
 
 function App() {
   return (
@@ -26,96 +95,223 @@ function App() {
 }
 ```
 
-## Multi-Agent Setup
+**⚠️ Important**: This requires a server proxy to work. See [Server Proxy Setup](#️-server-proxy-setup-required) below.
 
-```tsx
-import { AgentProvider, A2AChat, AgentSwitcher, useAgentContext } from '@kuntur/a2a-carbon-chat-adapter';
+---
 
-const agents = [
-  { id: 'research', name: 'Research Agent', url: 'https://research.example.com' },
-  { id: 'code', name: 'Code Agent', url: 'https://code.example.com' },
-];
+## ⚠️ Server Proxy Setup (Required)
 
-function App() {
-  return (
-    <AgentProvider agents={agents} defaultAgentId="research">
-      <ChatWithSwitcher />
-    </AgentProvider>
-  );
-}
+### Why You Need a Server Proxy
 
-function ChatWithSwitcher() {
-  const { agents, currentAgent, selectAgent } = useAgentContext();
+**Direct browser connections to A2A agents are blocked by CORS (Cross-Origin Resource Sharing) security policies.** Browsers prevent JavaScript from making requests to different domains unless the server explicitly allows it.
 
-  return (
-    <div>
-      <AgentSwitcher
-        agents={agents}
-        currentAgentId={currentAgent?.id}
-        onSelect={selectAgent}
-        variant="tabs"
-      />
-      <A2AChat />
-    </div>
-  );
-}
-```
+Most A2A agents:
+- Run on different domains than your frontend
+- Don't configure CORS headers for browser access
+- Use streaming protocols that require special handling
+
+**Solution**: Route agent requests through your backend server, which:
+1. Receives requests from your frontend (same origin = no CORS)
+2. Forwards them to the A2A agent (server-to-server = no CORS restrictions)
+3. Streams responses back to the frontend
 
-## Server Setup (Next.js)
+### Next.js Setup (Recommended)
+
+Create an API route that proxies requests to your A2A agent:
 
 ```typescript
 // app/api/agent/chat/route.ts
 import { createA2AHandler } from '@kuntur/a2a-carbon-chat-adapter/server';
 
 export const POST = createA2AHandler({
-  allowedAgentUrls: ['https://trusted-agent.example.com'],
+  // Security: Only allow requests to trusted agent URLs
+  allowedAgentUrls: [
+    'https://your-agent.example.com',
+    'https://another-agent.example.com',
+  ],
+  
+  // Optional: Set request timeout (default: 120000ms)
   timeout: 120000,
 });
 
+// Required for streaming responses
 export const runtime = 'nodejs';
 export const dynamic = 'force-dynamic';
 ```
 
-## Programmatic Usage with Hooks
+Then configure your frontend to use this proxy:
 
 ```tsx
-import { useA2AAgent } from '@kuntur/a2a-carbon-chat-adapter';
+import { A2AChat } from '@kuntur/a2a-carbon-chat-adapter';
+
+function App() {
+  return (
+    <A2AChat
+      agentUrl="https://your-agent.example.com"
+      agentName="My Agent"
+      // Point to your proxy endpoint
+      proxyUrl="/api/agent/chat"
+    />
+  );
+}
+```
+
+### Express.js Setup
 
-function MyComponent() {
-  const { sendMessage, isStreaming, state } = useA2AAgent({
-    agent: { id: 'my-agent', name: 'My Agent', url: 'https://...' },
-    onMessage: (message) => console.log('Received:', message),
-    onError: (error) => console.error('Error:', error),
+```typescript
+import express from 'express';
+import { createA2AHandler } from '@kuntur/a2a-carbon-chat-adapter/server';
+
+const app = express();
+
+// Create the handler
+const handler = createA2AHandler({
+  allowedAgentUrls: ['https://your-agent.example.com'],
+});
+
+// Mount as Express middleware
+app.post('/api/agent/chat', async (req, res) => {
+  const response = await handler(req);
+  
+  // Copy headers
+  response.headers.forEach((value, key) => {
+    res.setHeader(key, value);
   });
+  
+  // Stream response
+  const reader = response.body?.getReader();
+  if (reader) {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      res.write(value);
+    }
+  }
+  res.end();
+});
+```
 
-  const handleSend = async () => {
-    await sendMessage('Hello, agent!');
-  };
+### Other Frameworks
 
-  return (
-    <button onClick={handleSend} disabled={isStreaming}>
-      {isStreaming ? 'Sending...' : 'Send Message'}
-    </button>
-  );
+The `createA2AHandler` function returns a standard Web API `Response` object, making it compatible with:
+
+- **Remix**: Use in `action` functions
+- **SvelteKit**: Use in `+server.ts` endpoints
+- **Astro**: Use in API routes
+- **Cloudflare Workers**: Direct compatibility
+- **Vercel Edge Functions**: Direct compatibility
+
+Example for any framework:
+
+```typescript
+import { createA2AHandler } from '@kuntur/a2a-carbon-chat-adapter/server';
+
+const handler = createA2AHandler({
+  allowedAgentUrls: ['https://your-agent.example.com'],
+});
+
+// In your framework's request handler:
+export async function POST(request: Request) {
+  return handler(request);
 }
 ```
 
-## Components
+### Security Considerations
 
-### A2AChat
+**Always use `allowedAgentUrls`** to prevent your proxy from being used to access arbitrary URLs:
+
+```typescript
+createA2AHandler({
+  // ✅ Good: Whitelist specific agents
+  allowedAgentUrls: [
+    'https://trusted-agent.example.com',
+    'https://another-trusted-agent.example.com',
+  ],
+  
+  // ❌ Bad: Allows any URL (security risk!)
+  // allowedAgentUrls: undefined,
+});
+```
+
+---
+
+## Core Concepts
+
+### A2A Protocol
+
+The [Agent2Agent (A2A) protocol](https://github.com/agentstack/a2a) is a standard for AI agent communication. Key features:
+
+- **Streaming**: Real-time response delivery via Server-Sent Events (SSE)
+- **Context Management**: Maintains conversation state across requests
+- **UI Extensions**: Agents can request UI components (forms, citations, etc.)
+- **Task Management**: Supports long-running tasks with progress updates
+
+### Extension System
+
+A2A agents can send UI extension requests using special URIs:
+
+```
+agentstack://extension/{type}/{id}
+```
+
+This library automatically handles these extensions:
+
+- **Citations**: `agentstack://extension/citation/*` → Rendered inline with text
+- **Forms**: `agentstack://extension/form/*` → Interactive form components
+- **Errors**: `agentstack://extension/error/*` → Formatted error displays
+
+### Streaming Architecture
+
+```
+┌─────────────┐      ┌──────────────┐      ┌─────────────┐
+│   Browser   │─────▶│ Your Server  │─────▶│  A2A Agent  │
+│  (Frontend) │      │   (Proxy)    │      │             │
+└─────────────┘      └──────────────┘      └─────────────┘
+       │                     │                      │
+       │  1. POST request    │                      │
+       │────────────────────▶│                      │
+       │                     │  2. Forward request  │
+       │                     │─────────────────────▶│
+       │                     │                      │
+       │                     │  3. SSE stream       │
+       │                     │◀─────────────────────│
+       │  4. SSE stream      │                      │
+       │◀────────────────────│                      │
+       │                     │                      │
+```
+
+The library handles:
+1. Converting Carbon messages to A2A format
+2. Streaming A2A responses back to Carbon
+3. Parsing and rendering UI extensions
+4. Managing conversation context
+
+---
+
+## API Reference
+
+### Components
+
+#### `<A2AChat>`
 
 Main chat component that connects to A2A agents.
 
 ```tsx
+import { A2AChat } from '@kuntur/a2a-carbon-chat-adapter';
+
 <A2AChat
-  // Agent configuration (pick one)
-  agent={{ id: 'agent', name: 'Agent', url: '...' }}
+  // Agent Configuration (choose one)
+  agent={{ id: 'agent', name: 'Agent', url: 'https://...' }}
   // OR
-  agentId="agent" // with AgentProvider
+  agentId="agent" // Requires AgentProvider
   // OR
-  agentUrl="https://..." // simple URL-only
+  agentUrl="https://..." // Simple URL-only mode
+  agentName="Agent Name" // Optional display name
 
-  // Display options
+  // Server Proxy (required for CORS)
+  proxyUrl="/api/agent/chat"
+
+  // Display Options
   layout="fullscreen" // 'fullscreen' | 'sidebar' | 'float'
   className="my-chat"
 
@@ -125,23 +321,52 @@ Main chat component that connects to A2A agents.
   allowCancel={true}
 
   // Callbacks
-  onSend={(message) => {}}
-  onResponse={(response) => {}}
-  onError={(error) => {}}
+  onSend={(message) => console.log('Sent:', message)}
+  onResponse={(response) => console.log('Received:', response)}
+  onError={(error) => console.error('Error:', error)}
 
-  // Custom renderers
-  renderCitations={(citations, text) => <MyCitations ... />}
-  renderError={(error) => <MyError ... />}
+  // Custom Renderers
+  renderCitations={(citations, text) => <CustomCitations />}
+  renderError={(error) => <CustomError />}
+  renderForm={(form) => <CustomForm />}
 />
 ```
 
-### AgentProvider
+**Props:**
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `agent` | `AgentConfig` | No* | Full agent configuration object |
+| `agentId` | `string` | No* | Agent ID (requires `AgentProvider`) |
+| `agentUrl` | `string` | No* | Direct agent URL |
+| `agentName` | `string` | No | Display name for the agent |
+| `proxyUrl` | `string` | No | Server proxy endpoint (default: `/api/agent/chat`) |
+| `layout` | `'fullscreen' \| 'sidebar' \| 'float'` | No | Chat layout style |
+| `className` | `string` | No | Additional CSS classes |
+| `showThinking` | `boolean` | No | Show agent thinking indicators |
+| `showChainOfThought` | `boolean` | No | Show reasoning steps |
+| `allowCancel` | `boolean` | No | Allow canceling streaming responses |
+| `onSend` | `(message: string) => void` | No | Callback when message is sent |
+| `onResponse` | `(response: any) => void` | No | Callback when response received |
+| `onError` | `(error: Error) => void` | No | Callback on error |
+| `renderCitations` | `(citations, text) => ReactNode` | No | Custom citation renderer |
+| `renderError` | `(error) => ReactNode` | No | Custom error renderer |
+| `renderForm` | `(form) => ReactNode` | No | Custom form renderer |
+
+*One of `agent`, `agentId`, or `agentUrl` is required.
+
+#### `<AgentProvider>`
 
 Context provider for multi-agent applications.
 
 ```tsx
+import { AgentProvider } from '@kuntur/a2a-carbon-chat-adapter';
+
 <AgentProvider
-  agents={[...]}
+  agents={[
+    { id: 'research', name: 'Research Agent', url: 'https://...' },
+    { id: 'code', name: 'Code Agent', url: 'https://...' },
+  ]}
   defaultAgentId="research"
   persistSelection={true}
   storageKey="my-app-agent"
@@ -150,11 +375,22 @@ Context provider for multi-agent applications.
 </AgentProvider>
 ```
 
-### AgentSwitcher
+**Props:**
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `agents` | `AgentConfig[]` | Yes | Array of agent configurations |
+| `defaultAgentId` | `string` | No | Initially selected agent ID |
+| `persistSelection` | `boolean` | No | Save selection to localStorage |
+| `storageKey` | `string` | No | localStorage key (default: `selected-agent`) |
+
+#### `<AgentSwitcher>`
 
 UI component for switching between agents.
 
 ```tsx
+import { AgentSwitcher } from '@kuntur/a2a-carbon-chat-adapter';
+
 <AgentSwitcher
   agents={agents}
   currentAgentId={currentAgentId}
@@ -162,105 +398,693 @@ UI component for switching between agents.
   variant="dropdown" // 'dropdown' | 'tabs' | 'cards'
   showDescriptions={true}
   showIcons={true}
+  className="my-switcher"
 />
 ```
 
-## Hooks
+**Props:**
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `agents` | `AgentConfig[]` | Yes | Available agents |
+| `currentAgentId` | `string` | No | Currently selected agent ID |
+| `onSelect` | `(agentId: string) => void` | Yes | Selection callback |
+| `variant` | `'dropdown' \| 'tabs' \| 'cards'` | No | Display style |
+| `showDescriptions` | `boolean` | No | Show agent descriptions |
+| `showIcons` | `boolean` | No | Show agent icons |
+| `className` | `string` | No | Additional CSS classes |
+
+### Hooks
 
-### useA2AAgent
+#### `useA2AAgent`
 
-Programmatic agent interaction.
+Programmatic agent interaction without UI components.
 
 ```tsx
+import { useA2AAgent } from '@kuntur/a2a-carbon-chat-adapter';
+
 const {
   agent,           // Current agent config
-  state,           // { connectionState, error, taskId, contextId }
+  state,           // Connection state
   sendMessage,     // Send a message
   cancelStream,    // Cancel ongoing stream
-  disconnect,      // Disconnect
-  isStreaming,     // Boolean
-  isConnected,     // Boolean
-  error,           // Last error
-} = useA2AAgent(options);
+  disconnect,      // Disconnect from agent
+  isStreaming,     // Boolean: is currently streaming
+  isConnected,     // Boolean: is connected
+  error,           // Last error (if any)
+} = useA2AAgent({
+  agent: { id: 'agent', name: 'Agent', url: 'https://...' },
+  proxyUrl: '/api/agent/chat',
+  onMessage: (message) => console.log('Message:', message),
+  onError: (error) => console.error('Error:', error),
+  onStreamStart: () => console.log('Stream started'),
+  onStreamEnd: () => console.log('Stream ended'),
+});
+
+// Send a message
+await sendMessage('Hello, agent!');
+
+// Cancel streaming
+cancelStream();
+
+// Disconnect
+disconnect();
 ```
 
-### useMultiAgent
+**Options:**
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `agent` | `AgentConfig` | Yes | Agent configuration |
+| `proxyUrl` | `string` | No | Server proxy endpoint |
+| `onMessage` | `(message: any) => void` | No | Message received callback |
+| `onError` | `(error: Error) => void` | No | Error callback |
+| `onStreamStart` | `() => void` | No | Stream start callback |
+| `onStreamEnd` | `() => void` | No | Stream end callback |
+
+**Returns:**
 
-Manage multiple agents without AgentProvider.
+| Property | Type | Description |
+|----------|------|-------------|
+| `agent` | `AgentConfig` | Current agent configuration |
+| `state` | `AgentState` | Connection state object |
+| `sendMessage` | `(message: string) => Promise<void>` | Send message function |
+| `cancelStream` | `() => void` | Cancel streaming function |
+| `disconnect` | `() => void` | Disconnect function |
+| `isStreaming` | `boolean` | Currently streaming |
+| `isConnected` | `boolean` | Currently connected |
+| `error` | `Error \| null` | Last error |
+
+#### `useMultiAgent`
+
+Manage multiple agents without `AgentProvider`.
 
 ```tsx
+import { useMultiAgent } from '@kuntur/a2a-carbon-chat-adapter';
+
 const {
-  agents,          // All agents
-  currentAgent,    // Currently selected
-  switchAgent,     // Switch by ID
+  agents,          // All registered agents
+  currentAgent,    // Currently selected agent
+  switchAgent,     // Switch to agent by ID
   registerAgent,   // Add new agent
   unregisterAgent, // Remove agent
-} = useMultiAgent(options);
+} = useMultiAgent({
+  agents: [
+    { id: 'research', name: 'Research', url: 'https://...' },
+    { id: 'code', name: 'Code', url: 'https://...' },
+  ],
+  defaultAgentId: 'research',
+});
+
+// Switch agents
+switchAgent('code');
+
+// Add new agent
+registerAgent({ id: 'new', name: 'New Agent', url: 'https://...' });
+
+// Remove agent
+unregisterAgent('old');
 ```
 
-### useAgentContext
+#### `useAgentContext`
 
-Access AgentProvider context.
+Access `AgentProvider` context (must be used within `AgentProvider`).
 
 ```tsx
-const { currentAgent, agents, selectAgent, getAgent, hasAgent } = useAgentContext();
+import { useAgentContext } from '@kuntur/a2a-carbon-chat-adapter';
+
+const {
+  currentAgent,  // Currently selected agent
+  agents,        // All available agents
+  selectAgent,   // Select agent by ID
+  getAgent,      // Get agent by ID
+  hasAgent,      // Check if agent exists
+} = useAgentContext();
 ```
 
-## Renderers
+### Server Utilities
+
+#### `createA2AHandler`
+
+Create a server-side API handler for proxying A2A requests.
+
+```typescript
+import { createA2AHandler } from '@kuntur/a2a-carbon-chat-adapter/server';
 
-Built-in renderers for A2A UI extensions:
+const handler = createA2AHandler({
+  allowedAgentUrls: ['https://trusted-agent.example.com'],
+  timeout: 120000,
+});
 
-- `CitationRenderer` - Renders text with inline citations
-- `ErrorRenderer` - Renders error messages with optional stack trace
-- `FormRenderer` - Renders dynamic forms from agent requests
+// Returns a function: (request: Request) => Promise<Response>
+```
 
-## Exports
+**Options:**
 
-### From main package
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `allowedAgentUrls` | `string[]` | No | Whitelist of allowed agent URLs (security) |
+| `timeout` | `number` | No | Request timeout in ms (default: 120000) |
+
+**Returns:** `(request: Request) => Promise<Response>`
+
+### Renderers
+
+Built-in components for rendering A2A UI extensions.
+
+#### `CitationRenderer`
+
+Renders text with inline citations.
+
+```tsx
+import { CitationRenderer } from '@kuntur/a2a-carbon-chat-adapter';
+
+<CitationRenderer
+  text="This is cited text [1]."
+  citations={[
+    { id: '1', url: 'https://...', title: 'Source' }
+  ]}
+/>
+```
+
+#### `ErrorRenderer`
+
+Renders formatted error messages.
+
+```tsx
+import { ErrorRenderer } from '@kuntur/a2a-carbon-chat-adapter';
+
+<ErrorRenderer
+  error={{
+    message: 'Something went wrong',
+    code: 'ERROR_CODE',
+    stack: '...',
+  }}
+  showStack={true}
+/>
+```
+
+#### `FormRenderer`
+
+Renders dynamic forms from agent requests.
+
+```tsx
+import { FormRenderer } from '@kuntur/a2a-carbon-chat-adapter';
+
+<FormRenderer
+  form={{
+    fields: [
+      { name: 'email', type: 'email', label: 'Email', required: true },
+      { name: 'message', type: 'textarea', label: 'Message' },
+    ],
+  }}
+  onSubmit={(values) => console.log('Submitted:', values)}
+/>
+```
+
+### Types
+
+```typescript
+import type {
+  AgentConfig,
+  AgentState,
+  A2AChatProps,
+  AgentProviderProps,
+  AgentSwitcherProps,
+  ExtensionResult,
+  Citation,
+  FormField,
+  // ... more types
+} from '@kuntur/a2a-carbon-chat-adapter';
+```
+
+---
+
+## Advanced Usage
+
+### Multi-Agent Setup
 
 ```tsx
 import {
-  // Components
-  A2AChat,
   AgentProvider,
+  A2AChat,
   AgentSwitcher,
-  CitationRenderer,
-  ErrorRenderer,
-  FormRenderer,
-
-  // Hooks
-  useA2AAgent,
-  useMultiAgent,
   useAgentContext,
-  useAgentContextOptional,
+} from '@kuntur/a2a-carbon-chat-adapter';
 
-  // A2A Client
-  A2AClient,
-  EXTENSION_URIS,
+const agents = [
+  {
+    id: 'research',
+    name: 'Research Agent',
+    url: 'https://research.example.com',
+    description: 'Specialized in research and analysis',
+  },
+  {
+    id: 'code',
+    name: 'Code Agent',
+    url: 'https://code.example.com',
+    description: 'Specialized in code generation',
+  },
+];
 
-  // Translator
-  A2AToCarbonTranslator,
-  createTranslator,
+function App() {
+  return (
+    <AgentProvider
+      agents={agents}
+      defaultAgentId="research"
+      persistSelection={true}
+    >
+      <ChatWithSwitcher />
+    </AgentProvider>
+  );
+}
 
-  // Types
-  type AgentConfig,
-  type A2AChatProps,
-  // ... more types
-} from '@kuntur/a2a-carbon-chat-adapter';
+function ChatWithSwitcher() {
+  const { agents, currentAgent, selectAgent } = useAgentContext();
+
+  return (
+    <div className="app-container">
+      <AgentSwitcher
+        agents={agents}
+        currentAgentId={currentAgent?.id}
+        onSelect={selectAgent}
+        variant="tabs"
+        showDescriptions={true}
+      />
+      <A2AChat proxyUrl="/api/agent/chat" />
+    </div>
+  );
+}
 ```
 
-### From server subpath
+### Custom Citation Renderer
 
 ```tsx
-import { createA2AHandler } from '@kuntur/a2a-carbon-chat-adapter/server';
+import { A2AChat } from '@kuntur/a2a-carbon-chat-adapter';
+
+function CustomCitationRenderer({ citations, text }) {
+  return (
+    <div className="custom-citations">
+      <p>{text}</p>
+      <ul>
+        {citations.map((citation) => (
+          <li key={citation.id}>
+            <a href={citation.url} target="_blank" rel="noopener noreferrer">
+              [{citation.id}] {citation.title}
+            </a>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+
+function App() {
+  return (
+    <A2AChat
+      agentUrl="https://agent.example.com"
+      renderCitations={(citations, text) => (
+        <CustomCitationRenderer citations={citations} text={text} />
+      )}
+    />
+  );
+}
 ```
 
-### Styles (optional)
+### Programmatic Message Sending
 
 ```tsx
-import '@kuntur/a2a-carbon-chat-adapter/styles';
+import { useA2AAgent } from '@kuntur/a2a-carbon-chat-adapter';
+import { useState } from 'react';
+
+function CustomChat() {
+  const [messages, setMessages] = useState([]);
+  
+  const { sendMessage, isStreaming, error } = useA2AAgent({
+    agent: {
+      id: 'agent',
+      name: 'My Agent',
+      url: 'https://agent.example.com',
+    },
+    proxyUrl: '/api/agent/chat',
+    onMessage: (message) => {
+      setMessages((prev) => [...prev, message]);
+    },
+  });
+
+  const handleSend = async (text: string) => {
+    setMessages((prev) => [...prev, { role: 'user', content: text }]);
+    await sendMessage(text);
+  };
+
+  return (
+    <div>
+      <div className="messages">
+        {messages.map((msg, i) => (
+          <div key={i} className={`message ${msg.role}`}>
+            {msg.content}
+          </div>
+        ))}
+      </div>
+      {error && <div className="error">{error.message}</div>}
+      <input
+        type="text"
+        onKeyPress={(e) => {
+          if (e.key === 'Enter' && !isStreaming) {
+            handleSend(e.currentTarget.value);
+            e.currentTarget.value = '';
+          }
+        }}
+        disabled={isStreaming}
+      />
+    </div>
+  );
+}
+```
+
+### Extension URI Handling
+
+The library automatically handles A2A extension URIs:
+
+```typescript
+// Agent sends extension URI in response
+{
+  "content": "agentstack://extension/citation/abc123",
+  "metadata": {
+    "extensions": {
+      "abc123": {
+        "type": "citation",
+        "data": {
+          "url": "https://example.com",
+          "title": "Example Source"
+        }
+      }
+    }
+  }
+}
+
+// Library automatically:
+// 1. Detects extension URI
+// 2. Looks up extension data in metadata
+// 3. Renders using CitationRenderer
+// 4. Replaces URI with rendered component
+```
+
+### Error Handling
+
+```tsx
+import { A2AChat } from '@kuntur/a2a-carbon-chat-adapter';
+
+function App() {
+  const handleError = (error: Error) => {
+    // Log to error tracking service
+    console.error('Agent error:', error);
+    
+    // Show user-friendly message
+    if (error.message.includes('timeout')) {
+      alert('The agent is taking too long to respond. Please try again.');
+    } else if (error.message.includes('network')) {
+      alert('Network error. Please check your connection.');
+    } else {
+      alert('An error occurred. Please try again.');
+    }
+  };
+
+  return (
+    <A2AChat
+      agentUrl="https://agent.example.com"
+      onError={handleError}
+    />
+  );
+}
+```
+
+---
+
+## Examples
+
+For complete working examples, see the [examples repository](https://github.com/Xnvargas/a2a-carbon-chat-adapter-examples) (coming soon).
+
+Example applications include:
+
+- **Basic Chat**: Simple single-agent chat interface
+- **Multi-Agent**: Agent switching with tabs and dropdown
+- **Custom Renderers**: Custom citation and form renderers
+- **Programmatic API**: Using hooks without UI components
+- **Next.js Integration**: Full Next.js app with API routes
+- **Express.js Integration**: Express server with proxy setup
+
+---
+
+## Architecture
+
+### Protocol Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         Browser (Frontend)                       │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                   │
+│  ┌──────────────┐         ┌─────────────────────────────────┐  │
+│  │   A2AChat    │────────▶│  useA2AAgent Hook               │  │
+│  │  Component   │         │  - Manages connection state     │  │
+│  └──────────────┘         │  - Handles streaming            │  │
+│         │                 │  - Parses extensions            │  │
+│         │                 └─────────────────────────────────┘  │
+│         │                              │                        │
+│         ▼                              ▼                        │
+│  ┌──────────────┐         ┌─────────────────────────────────┐  │
+│  │  Renderers   │         │  A2AToCarbonTranslator          │  │
+│  │  - Citation  │         │  - Converts A2A → Carbon format │  │
+│  │  - Error     │         │  - Handles metadata transform   │  │
+│  │  - Form      │         └─────────────────────────────────┘  │
+│  └──────────────┘                      │                        │
+│                                        │                        │
+└────────────────────────────────────────┼────────────────────────┘
+                                         │
+                                         │ POST /api/agent/chat
+                                         │
+┌────────────────────────────────────────┼────────────────────────┐
+│                    Your Server (Proxy)  │                        │
+├────────────────────────────────────────┼────────────────────────┤
+│                                        │                        │
+│                          ┌─────────────▼──────────────┐         │
+│                          │  createA2AHandler          │         │
+│                          │  - Validates agent URL     │         │
+│                          │  - Forwards request        │         │
+│                          │  - Streams response        │         │
+│                          └─────────────┬──────────────┘         │
+│                                        │                        │
+└────────────────────────────────────────┼────────────────────────┘
+                                         │
+                                         │ POST /chat
+                                         │
+┌────────────────────────────────────────┼────────────────────────┐
+│                      A2A Agent          │                        │
+├────────────────────────────────────────┼────────────────────────┤
+│                                        │                        │
+│                          ┌─────────────▼──────────────┐         │
+│                          │  A2A Protocol Handler      │         │
+│                          │  - Processes message       │         │
+│                          │  - Generates response      │         │
+│                          │  - Streams via SSE         │         │
+│                          └────────────────────────────┘         │
+│                                                                  │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+### Package Structure
+
+```
+@kuntur/a2a-carbon-chat-adapter/
+├── dist/                    # Built output
+│   ├── index.js            # ESM main entry
+│   ├── index.cjs           # CJS main entry
+│   ├── index.d.ts          # TypeScript definitions
+│   ├── server.js           # ESM server utilities
+│   ├── server.cjs          # CJS server utilities
+│   ├── server.d.ts         # Server TypeScript definitions
+│   └── styles/
+│       └── index.css       # Component styles
+├── src/
+│   ├── components/         # React components
+│   │   ├── A2AChat.tsx
+│   │   ├── AgentProvider.tsx
+│   │   ├── AgentSwitcher.tsx
+│   │   └── renderers/      # Extension renderers
+│   ├── hooks/              # React hooks
+│   │   ├── useA2AAgent.ts
+│   │   ├── useMultiAgent.ts
+│   │   └── useAgentContext.ts
+│   ├── lib/
+│   │   ├── a2a/            # A2A protocol client
+│   │   └── translator/     # Protocol translation
+│   ├── server/             # Server utilities
+│   │   └── create-api-handler.ts
+│   └── types/              # TypeScript types
+└── package.json
+```
+
+---
+
+## Troubleshooting
+
+### CORS Errors
+
+**Problem**: Browser console shows CORS errors when connecting to agent.
+
+**Solution**: You must use a server proxy. See [Server Proxy Setup](#️-server-proxy-setup-required).
+
+```
+❌ Access to fetch at 'https://agent.example.com' from origin 'http://localhost:3000'
+   has been blocked by CORS policy
+```
+
+### Streaming Not Working
+
+**Problem**: Messages don't stream; they appear all at once.
+
+**Solution**: Ensure your server proxy is configured correctly:
+
+```typescript
+// Next.js: Add these exports
+export const runtime = 'nodejs';
+export const dynamic = 'force-dynamic';
+
+// Express: Ensure streaming is not buffered
+app.use(express.json({ limit: '50mb' }));
+```
+
+### Extension URIs Not Rendering
+
+**Problem**: Extension URIs appear as plain text instead of rendered components.
+
+**Solution**: Ensure the agent includes extension metadata:
+
+```json
+{
+  "content": "See citation [1]",
+  "metadata": {
+    "extensions": {
+      "1": {
+        "type": "citation",
+        "data": {
+          "url": "https://example.com",
+          "title": "Example"
+        }
+      }
+    }
+  }
+}
 ```
 
+### TypeScript Errors
+
+**Problem**: TypeScript can't find module declarations.
+
+**Solution**: Ensure `@carbon/ai-chat` is installed and types are available:
+
+```bash
+npm install @carbon/ai-chat @types/react @types/react-dom
+```
+
+### Agent Not Responding
+
+**Problem**: No response from agent after sending message.
+
+**Checklist**:
+1. ✅ Server proxy is running and accessible
+2. ✅ Agent URL is correct and agent is running
+3. ✅ Agent URL is in `allowedAgentUrls` (if configured)
+4. ✅ Network tab shows request reaching `/api/agent/chat`
+5. ✅ Check server logs for errors
+
+### Performance Issues
+
+**Problem**: Chat feels slow or laggy.
+
+**Solutions**:
+- Reduce `timeout` in `createA2AHandler` for faster failures
+- Implement message pagination for long conversations
+- Use `showThinking={false}` to reduce re-renders
+- Memoize custom renderers with `React.memo()`
+
+---
+
+## Contributing
+
+Contributions are welcome! Please follow these guidelines:
+
+### Development Setup
+
+```bash
+# Clone repository
+git clone https://github.com/Xnvargas/a2a-carbon-chat-adapter.git
+cd a2a-carbon-chat-adapter
+
+# Install dependencies
+npm install
+
+# Run development build (watch mode)
+npm run dev
+
+# Run type checking
+npm run typecheck
+
+# Run linting
+npm run lint
+
+# Build for production
+npm run build
+```
+
+### Submitting Changes
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Add tests if applicable
+5. Run `npm run typecheck` and `npm run lint`
+6. Commit your changes (`git commit -m 'Add amazing feature'`)
+7. Push to the branch (`git push origin feature/amazing-feature`)
+8. Open a Pull Request
+
+### Code Style
+
+- Use TypeScript for all new code
+- Follow existing code formatting (ESLint config)
+- Add JSDoc comments for public APIs
+- Update documentation for user-facing changes
+
+### Reporting Issues
+
+When reporting issues, please include:
+
+- Library version (`npm list @kuntur/a2a-carbon-chat-adapter`)
+- Framework and version (Next.js, React, etc.)
+- Minimal reproduction code
+- Expected vs actual behavior
+- Browser console errors (if applicable)
+
+---
+
 ## License
 
-MIT
+MIT © [Xavier Vargas](https://github.com/Xnvargas)
+
+See [LICENSE](LICENSE) file for details.
+
+---
+
+## Links
+
+- **GitHub**: https://github.com/Xnvargas/a2a-carbon-chat-adapter
+- **npm**: https://www.npmjs.com/package/@kuntur/a2a-carbon-chat-adapter
+- **Issues**: https://github.com/Xnvargas/a2a-carbon-chat-adapter/issues
+- **Examples**: https://github.com/Xnvargas/a2a-carbon-chat-adapter-examples (coming soon)
+- **A2A Protocol**: https://github.com/agentstack/a2a
+- **Carbon AI Chat**: https://github.com/carbon-design-system/carbon-for-ai
+
+---
+
+**Made with ❤️ for the AI agent community**