concevent-ai-agent-sdk 1.0.0

package/README.md

@@ -0,0 +1,993 @@
+# concevent-ai-agent-sdk
+
+A framework-agnostic AI Agent SDK for building intelligent conversational agents with tool calling, automatic conversation summarization, and comprehensive event handling. Built on top of OpenAI-compatible APIs (including OpenRouter).
+
+## Features
+
+- 🤖 **AI Agent Framework** - Create intelligent agents with tool/function calling capabilities
+- 🔧 **Tool Execution** - Define and execute custom tools with typed parameters using Zod schemas
+- 💬 **Conversation Management** - Automatic history tracking with built-in summarization
+- ⚛️ **React Integration** - First-class React hooks and context providers
+- 📊 **Token Usage Tracking** - Monitor token consumption across conversations
+- 🔄 **Auto-Summarization** - Automatically summarize long conversations to stay within context limits
+- 🎯 **Event Callbacks** - Comprehensive event system for real-time updates
+- ⛔ **Abort Support** - Cancel ongoing requests with AbortController
+- 🔄 **Retry Logic** - Built-in retry mechanism for resilient operations
+- 📝 **Reasoning Support** - Access model reasoning/thinking outputs
+
+## Installation
+
+```bash
+npm install concevent-ai-agent-sdk
+# or
+yarn add concevent-ai-agent-sdk
+# or
+pnpm add concevent-ai-agent-sdk
+```
+
+## Quick Start
+
+```typescript
+import { createAgent } from "concevent-ai-agent-sdk";
+import type {
+  ToolDefinition,
+  ToolExecutorContext,
+} from "concevent-ai-agent-sdk";
+import { z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+
+// Define your tools
+const tools: ToolDefinition[] = [
+  {
+    declaration: {
+      name: "getWeather",
+      description: "Get current weather for a city",
+      parametersJsonSchema: zodToJsonSchema(
+        z.object({
+          city: z.string().describe("City name"),
+        })
+      ),
+    },
+    executor: async (args) => {
+      const city = args.city as string;
+      // Your weather API logic here
+      return { city, temperature: 22, condition: "sunny" };
+    },
+  },
+];
+
+// Create the agent
+const agent = createAgent({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  model: "anthropic/claude-3.5-sonnet",
+  systemPrompts: ["You are a helpful weather assistant."],
+  tools,
+});
+
+// Chat with the agent
+const result = await agent.chat("What's the weather in Tokyo?", {
+  userId: "user-123",
+  timezone: "Asia/Tokyo",
+});
+
+console.log(result.message);
+// "The weather in Tokyo is currently sunny with a temperature of 22°C."
+```
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+- [API Reference](#api-reference)
+  - [createAgent](#createagent)
+  - [Agent Interface](#agent-interface)
+  - [Tool Definitions](#tool-definitions)
+  - [Callbacks & Events](#callbacks--events)
+  - [Types](#types)
+- [React Integration](#react-integration)
+  - [useAgent Hook](#useagent-hook)
+  - [AgentProvider](#agentprovider)
+- [Advanced Usage](#advanced-usage)
+  - [Conversation Summarization](#conversation-summarization)
+  - [Error Handling](#error-handling)
+  - [Abort Requests](#abort-requests)
+
+---
+
+## Core Concepts
+
+### Agent
+
+An Agent is the main interface for interacting with AI models. It manages conversation history, executes tools, handles token usage tracking, and provides automatic summarization when context limits are reached.
+
+### Tools
+
+Tools (also known as functions) extend the agent's capabilities. Each tool has:
+
+- A **declaration** describing its name, purpose, and parameter schema
+- An **executor** function that performs the actual work
+
+### Conversation History
+
+The agent automatically maintains conversation history, including user messages, assistant responses, and tool calls. This history can be retrieved, set, or cleared as needed.
+
+---
+
+## API Reference
+
+### createAgent
+
+Creates a new agent instance with the specified configuration.
+
+```typescript
+import { createAgent } from 'concevent-ai-agent-sdk';
+
+const agent = createAgent(config: AgentConfig): Agent;
+```
+
+#### AgentConfig
+
+| Property          | Type                          | Required | Default             | Description                                              |
+| ----------------- | ----------------------------- | -------- | ------------------- | -------------------------------------------------------- |
+| `apiKey`          | `string`                      | ✅       | -                   | API key for the AI provider                              |
+| `model`           | `string`                      | ✅       | -                   | Model identifier (e.g., `'anthropic/claude-3.5-sonnet'`) |
+| `systemPrompts`   | `string[]`                    | ✅       | -                   | Array of system prompt messages                          |
+| `tools`           | `ToolDefinition[]`            | ✅       | -                   | Array of tool definitions                                |
+| `baseURL`         | `string`                      | ❌       | OpenRouter default  | Custom API base URL                                      |
+| `temperature`     | `number`                      | ❌       | `0.1`               | Sampling temperature (0-2)                               |
+| `reasoningEffort` | `'low' \| 'medium' \| 'high'` | ❌       | `'high'`            | Reasoning effort level for supported models              |
+| `maxIterations`   | `number`                      | ❌       | `20`                | Maximum tool execution iterations per chat               |
+| `summarization`   | `SummarizationConfig`         | ❌       | `{ enabled: true }` | Summarization settings                                   |
+| `errorMessages`   | `ErrorMessages`               | ❌       | Default messages    | Custom error messages                                    |
+
+#### SummarizationConfig
+
+```typescript
+interface SummarizationConfig {
+  enabled: boolean;
+  prompt?: string; // Custom summarization prompt
+  contextLimitTokens?: number; // Default: 100,000 tokens
+}
+```
+
+#### Example with Full Configuration
+
+```typescript
+const agent = createAgent({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  model: "anthropic/claude-3.5-sonnet",
+  baseURL: "https://openrouter.ai/api/v1",
+  temperature: 0.7,
+  reasoningEffort: "high",
+  maxIterations: 10,
+  systemPrompts: [
+    "You are a helpful assistant.",
+    "Always be concise and accurate.",
+  ],
+  tools: myTools,
+  summarization: {
+    enabled: true,
+    contextLimitTokens: 50000,
+    prompt: "Summarize the key points of this conversation...",
+  },
+  errorMessages: {
+    maxIterations: "Too many steps required. Please simplify your request.",
+    genericError: "Something went wrong. Please try again.",
+  },
+});
+```
+
+---
+
+### Agent Interface
+
+The agent instance returned by `createAgent` implements the following interface:
+
+```typescript
+interface Agent {
+  chat(
+    message: string,
+    context: ToolExecutorContext,
+    callbacks?: AgentCallbacks
+  ): Promise<AgentResult>;
+
+  abort(): void;
+  getHistory(): ChatMessage[];
+  setHistory(history: ChatMessage[]): void;
+  clearHistory(): void;
+  getTokenUsage(): UsageMetadata;
+}
+```
+
+#### agent.chat()
+
+Sends a message to the agent and receives a response. The agent may execute multiple tool calls before returning a final response.
+
+```typescript
+const result = await agent.chat(
+  message: string,
+  context: ToolExecutorContext,
+  callbacks?: AgentCallbacks
+): Promise<AgentResult>;
+```
+
+**Parameters:**
+
+| Parameter   | Type                  | Description                       |
+| ----------- | --------------------- | --------------------------------- |
+| `message`   | `string`              | The user's message                |
+| `context`   | `ToolExecutorContext` | Execution context passed to tools |
+| `callbacks` | `AgentCallbacks`      | Optional event callbacks          |
+
+**Returns:** `AgentResult`
+
+```typescript
+interface AgentResult {
+  message: string; // Final response message
+  reasoning?: {
+    // Model's reasoning (if available)
+    text?: string;
+    details?: ReasoningDetail[];
+    tokenCount?: number;
+  };
+  conversationHistory: ChatMessage[]; // Full conversation history
+  usageMetadata: UsageMetadata; // Token usage statistics
+  requestId?: string; // API request ID
+  iterations: number; // Number of iterations taken
+  summarized: boolean; // Whether summarization occurred
+}
+```
+
+**Example:**
+
+```typescript
+const result = await agent.chat(
+  "Calculate 25 * 4 and tell me the weather in Paris",
+  { userId: "user-123", timezone: "Europe/Paris" },
+  {
+    onToolCallStart: (calls) => {
+      console.log(
+        "Executing tools:",
+        calls.map((c) => c.name)
+      );
+    },
+    onMessage: (message) => {
+      console.log("Response:", message);
+    },
+  }
+);
+```
+
+#### agent.abort()
+
+Aborts the current chat request.
+
+```typescript
+agent.abort();
+```
+
+#### agent.getHistory()
+
+Returns the current conversation history.
+
+```typescript
+const history: ChatMessage[] = agent.getHistory();
+```
+
+#### agent.setHistory()
+
+Sets the conversation history (useful for restoring sessions).
+
+```typescript
+agent.setHistory(previousHistory);
+```
+
+#### agent.clearHistory()
+
+Clears all conversation history.
+
+```typescript
+agent.clearHistory();
+```
+
+#### agent.getTokenUsage()
+
+Returns cumulative token usage statistics.
+
+```typescript
+const usage: UsageMetadata = agent.getTokenUsage();
+console.log(`Total tokens used: ${usage.totalTokenCount}`);
+```
+
+---
+
+### Tool Definitions
+
+Tools extend the agent's capabilities by allowing it to perform actions or retrieve information.
+
+```typescript
+interface ToolDefinition {
+  declaration: FunctionDeclaration;
+  executor: ToolExecutor;
+}
+
+interface FunctionDeclaration {
+  name: string;
+  description: string;
+  parametersJsonSchema: JsonSchema7Type;
+}
+
+type ToolExecutor = (
+  args: Record<string, unknown>,
+  context: ToolExecutorContext
+) => Promise<unknown>;
+
+interface ToolExecutorContext {
+  userId: string;
+  timezone: string;
+  abortSignal?: AbortSignal;
+}
+```
+
+#### Creating Tools with Zod
+
+Using Zod for parameter validation is recommended:
+
+```typescript
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import type { ToolDefinition } from 'concevent-ai-agent-sdk';
+
+// Define parameter schema with Zod
+const searchSchema = z.object({
+  query: z.string().describe('Search query'),
+  limit: z.number().optional().default(10).describe('Maximum results'),
+});
+
+// Create the tool
+const searchTool: ToolDefinition = {
+  declaration: {
+    name: 'search',
+    description: 'Search for information in the database',
+    parametersJsonSchema: zodToJsonSchema(searchSchema),
+  },
+  executor: async (args, context) => {
+    const { query, limit } = args as z.infer<typeof searchSchema>;
+
+    // Access context information
+    console.log(`User ${context.userId} searching for: ${query}`);
+
+    // Perform search...
+    return { results: [...], total: 42 };
+  },
+};
+```
+
+#### Tool with Abort Support
+
+```typescript
+const longRunningTool: ToolDefinition = {
+  declaration: {
+    name: "processData",
+    description: "Process large dataset",
+    parametersJsonSchema: zodToJsonSchema(
+      z.object({
+        datasetId: z.string(),
+      })
+    ),
+  },
+  executor: async (args, context) => {
+    // Check for abort signal
+    if (context.abortSignal?.aborted) {
+      throw new Error("Operation cancelled");
+    }
+
+    // Pass abort signal to async operations
+    const response = await fetch(`/api/process/${args.datasetId}`, {
+      signal: context.abortSignal,
+    });
+
+    return response.json();
+  },
+};
+```
+
+---
+
+### Callbacks & Events
+
+The SDK provides a comprehensive callback system for real-time updates during agent execution.
+
+#### AgentCallbacks
+
+```typescript
+interface AgentCallbacks {
+  onThinking?: (thinking: string, details?: ReasoningDetail[]) => void;
+  onMessage?: (
+    message: string,
+    reasoning?: {
+      text?: string;
+      details?: ReasoningDetail[];
+      tokenCount?: number;
+    }
+  ) => void;
+  onToolCallStart?: (calls: ToolCallStartData[]) => void;
+  onToolResult?: (result: ToolResultData) => void;
+  onUsageUpdate?: (usage: UsageMetadata) => void;
+  onSummarizationStart?: (originalMessageCount: number) => void;
+  onSummarizationEnd?: (summary: string, tokensEstimate: number) => void;
+  onIterationStart?: (iteration: number, maxIterations: number) => void;
+  onError?: (error: {
+    code: string;
+    message: string;
+    recoverable: boolean;
+  }) => void;
+  onComplete?: (result: AgentResult) => void;
+  onAborted?: () => void;
+}
+```
+
+#### Callback Examples
+
+```typescript
+await agent.chat("Help me with my task", context, {
+  // Called when the model is "thinking" (for reasoning models)
+  onThinking: (thinking, details) => {
+    console.log("Model thinking:", thinking);
+  },
+
+  // Called when a final message is received
+  onMessage: (message, reasoning) => {
+    console.log("Assistant:", message);
+    if (reasoning?.text) {
+      console.log("Reasoning:", reasoning.text);
+    }
+  },
+
+  // Called before tool execution starts
+  onToolCallStart: (calls) => {
+    calls.forEach((call) => {
+      console.log(`Calling ${call.name} with:`, call.args);
+    });
+  },
+
+  // Called after each tool completes
+  onToolResult: (result) => {
+    if (result.error) {
+      console.error(`Tool ${result.functionName} failed:`, result.error);
+    } else {
+      console.log(`Tool ${result.functionName} returned:`, result.result);
+    }
+  },
+
+  // Called when token usage is updated
+  onUsageUpdate: (usage) => {
+    console.log(`Tokens used: ${usage.totalTokenCount}`);
+  },
+
+  // Called when summarization begins
+  onSummarizationStart: (messageCount) => {
+    console.log(`Summarizing ${messageCount} messages...`);
+  },
+
+  // Called when summarization completes
+  onSummarizationEnd: (summary, tokens) => {
+    console.log(`Summarized to ~${tokens} tokens`);
+  },
+
+  // Called at the start of each iteration
+  onIterationStart: (iteration, max) => {
+    console.log(`Iteration ${iteration}/${max}`);
+  },
+
+  // Called on errors
+  onError: (error) => {
+    console.error(`Error [${error.code}]:`, error.message);
+    if (!error.recoverable) {
+      // Handle fatal error
+    }
+  },
+
+  // Called when processing completes
+  onComplete: (result) => {
+    console.log(`Completed in ${result.iterations} iterations`);
+  },
+
+  // Called when request is aborted
+  onAborted: () => {
+    console.log("Request was cancelled");
+  },
+});
+```
+
+#### Event Types
+
+The SDK also exports event types and a `createEvent` helper for building event-driven systems:
+
+```typescript
+import { createEvent } from "concevent-ai-agent-sdk";
+import type { AgentEventType, AgentEvent } from "concevent-ai-agent-sdk";
+
+// Create typed events
+const messageEvent = createEvent("message", {
+  message: "Hello!",
+  reasoning: undefined,
+});
+
+const errorEvent = createEvent("error", {
+  code: "TOOL_EXECUTION_FAILED",
+  message: "Tool failed to execute",
+  recoverable: true,
+});
+
+// Event types available:
+// 'thinking' | 'message' | 'tool_call_start' | 'tool_result' |
+// 'usage_update' | 'summarization_start' | 'summarization_end' |
+// 'iteration_start' | 'error' | 'complete' | 'aborted'
+```
+
+---
+
+### Types
+
+#### ChatMessage
+
+```typescript
+interface ChatMessage {
+  role: "user" | "assistant" | "system" | "tool-call" | "tool-call-results";
+  content: string;
+  timestamp: Date;
+  toolCalls?: ToolCall[];
+  toolCallId?: string;
+  reasoning?: string;
+  reasoning_details?: ReasoningDetail[];
+  reasoningTokenCount?: number;
+}
+```
+
+#### UsageMetadata
+
+```typescript
+interface UsageMetadata {
+  promptTokenCount?: number;
+  candidatesTokenCount?: number;
+  totalTokenCount?: number;
+  cachedContentTokenCount?: number;
+  reasoningTokenCount?: number;
+}
+```
+
+#### ReasoningDetail
+
+```typescript
+interface ReasoningDetail {
+  id?: string;
+  type: string;
+  text?: string;
+  data?: string;
+  format: string;
+  index: number;
+}
+```
+
+#### ToolCallStartData & ToolResultData
+
+```typescript
+interface ToolCallStartData {
+  id: string;
+  name: string;
+  args: Record<string, unknown>;
+}
+
+interface ToolResultData {
+  id: string;
+  functionName: string;
+  result: unknown;
+  error?: string;
+}
+```
+
+---
+
+## React Integration
+
+The SDK provides React hooks and components for easy integration with React applications.
+
+### useAgent Hook
+
+A React hook that manages agent state and provides a convenient interface for chat interactions.
+
+```typescript
+import { useAgent } from "concevent-ai-agent-sdk/react";
+import type {
+  UseAgentReturn,
+  UseAgentOptions,
+} from "concevent-ai-agent-sdk/react";
+```
+
+#### Usage
+
+```tsx
+import { useAgent } from "concevent-ai-agent-sdk/react";
+import type { AgentConfig } from "concevent-ai-agent-sdk";
+
+function ChatComponent() {
+  const config: AgentConfig = {
+    apiKey: process.env.NEXT_PUBLIC_API_KEY!,
+    model: "anthropic/claude-3.5-sonnet",
+    systemPrompts: ["You are a helpful assistant."],
+    tools: [],
+  };
+
+  const {
+    chat,
+    abort,
+    history,
+    chatItems,
+    isLoading,
+    error,
+    tokenUsage,
+    clearHistory,
+    clearError,
+  } = useAgent(config, {
+    onMessage: (message) => console.log("New message:", message),
+    onError: (error) => console.error("Error:", error),
+  });
+
+  const handleSubmit = async (message: string) => {
+    const result = await chat(message, {
+      userId: "user-123",
+      timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+    });
+
+    if (result) {
+      console.log("Chat completed:", result.message);
+    }
+  };
+
+  return (
+    <div>
+      {chatItems.map((item) => (
+        <div key={item.id}>
+          {item.type === "message" && (
+            <p>
+              {item.message?.role}: {item.message?.content}
+            </p>
+          )}
+          {item.type === "function_call" && (
+            <p>🔧 {item.functionCall?.functionName}</p>
+          )}
+        </div>
+      ))}
+
+      {isLoading && <p>Thinking...</p>}
+      {error && <p>Error: {error.message}</p>}
+
+      <button onClick={abort} disabled={!isLoading}>
+        Cancel
+      </button>
+      <button onClick={clearHistory}>Clear Chat</button>
+    </div>
+  );
+}
+```
+
+#### UseAgentReturn
+
+```typescript
+interface UseAgentReturn {
+  chat: (
+    message: string,
+    context: ToolExecutorContext
+  ) => Promise<AgentResult | null>;
+  abort: () => void;
+  history: ChatMessage[]; // Raw conversation history
+  chatItems: ChatItem[]; // Formatted items for UI rendering
+  isLoading: boolean;
+  error: Error | null;
+  tokenUsage: UsageMetadata;
+  clearHistory: () => void;
+  clearError: () => void;
+}
+```
+
+#### UseAgentOptions
+
+```typescript
+interface UseAgentOptions {
+  onMessage?: (message: ChatMessage) => void;
+  onFunctionCall?: (call: FunctionCallDisplay) => void;
+  onError?: (error: Error) => void;
+}
+```
+
+#### ChatItem Type
+
+```typescript
+interface ChatItem {
+  id: string;
+  type: "message" | "function_call";
+  timestamp: Date;
+  message?: ChatMessage;
+  functionCall?: FunctionCallDisplay;
+}
+
+interface FunctionCallDisplay {
+  functionName: string;
+  args: Record<string, unknown>;
+  timestamp: Date;
+}
+```
+
+---
+
+### AgentProvider
+
+A React context provider for sharing an agent instance across components.
+
+```tsx
+import { AgentProvider, useAgentContext } from "concevent-ai-agent-sdk/react";
+```
+
+#### Usage
+
+```tsx
+import { AgentProvider, useAgentContext } from "concevent-ai-agent-sdk/react";
+import type { AgentConfig } from "concevent-ai-agent-sdk";
+
+const config: AgentConfig = {
+  apiKey: process.env.NEXT_PUBLIC_API_KEY!,
+  model: "anthropic/claude-3.5-sonnet",
+  systemPrompts: ["You are a helpful assistant."],
+  tools: myTools,
+};
+
+// Wrap your app with the provider
+function App() {
+  return (
+    <AgentProvider config={config}>
+      <ChatInterface />
+    </AgentProvider>
+  );
+}
+
+// Access the agent in child components
+function ChatInterface() {
+  const { agent, config } = useAgentContext();
+
+  const handleChat = async () => {
+    const result = await agent.chat("Hello!", {
+      userId: "user-123",
+      timezone: "UTC",
+    });
+    console.log(result.message);
+  };
+
+  return (
+    <div>
+      <p>Using model: {config.model}</p>
+      <button onClick={handleChat}>Send Message</button>
+    </div>
+  );
+}
+```
+
+#### AgentProviderProps
+
+```typescript
+interface AgentProviderProps {
+  config: AgentConfig;
+  children: ReactNode;
+}
+```
+
+---
+
+## Advanced Usage
+
+### Conversation Summarization
+
+When conversations become too long, the agent automatically summarizes them to stay within context limits.
+
+```typescript
+const agent = createAgent({
+  apiKey: process.env.API_KEY!,
+  model: "anthropic/claude-3.5-sonnet",
+  systemPrompts: ["You are a helpful assistant."],
+  tools: [],
+  summarization: {
+    enabled: true,
+    contextLimitTokens: 50000, // Summarize when approaching 50k tokens
+    prompt: `
+      Summarize this conversation, preserving:
+      1. Key user requests and questions
+      2. Important decisions made
+      3. Any data or numbers mentioned
+      4. Context needed to continue the conversation
+    `,
+  },
+});
+
+// Listen for summarization events
+await agent.chat("Continue our discussion...", context, {
+  onSummarizationStart: (messageCount) => {
+    console.log(`Summarizing ${messageCount} messages to save context...`);
+  },
+  onSummarizationEnd: (summary, tokensEstimate) => {
+    console.log(
+      `Conversation summarized. Estimated tokens saved: ${tokensEstimate}`
+    );
+  },
+});
+```
+
+### Error Handling
+
+The SDK provides typed errors and customizable error messages.
+
+```typescript
+import { createAgent } from "concevent-ai-agent-sdk";
+
+const agent = createAgent({
+  // ... config
+  errorMessages: {
+    apiKeyRequired: "Please provide an API key",
+    modelRequired: "Please specify a model",
+    emptyResponse: "No response received, please try again",
+    maxIterations: "Request too complex. Please simplify.",
+    toolExecutionFailed: "A tool failed to execute",
+    genericError: "Something went wrong",
+  },
+});
+
+// Handle errors via callbacks
+await agent.chat("Do something", context, {
+  onError: (error) => {
+    switch (error.code) {
+      case "MAX_ITERATIONS":
+        console.log("Too many iterations, simplify the request");
+        break;
+      case "TOOL_EXECUTION_FAILED":
+        console.log("Tool failed:", error.message);
+        break;
+      case "REQUEST_ABORTED":
+        console.log("Request was cancelled");
+        break;
+      default:
+        console.log("Error:", error.message);
+    }
+
+    if (!error.recoverable) {
+      // Handle fatal error
+    }
+  },
+});
+```
+
+#### Error Codes
+
+| Code                    | Description                 | Recoverable |
+| ----------------------- | --------------------------- | ----------- |
+| `API_KEY_REQUIRED`      | API key not provided        | No          |
+| `MODEL_REQUIRED`        | Model name not provided     | No          |
+| `EMPTY_RESPONSE`        | API returned empty response | No          |
+| `REQUEST_ABORTED`       | Request was aborted         | No          |
+| `NO_RESPONSE`           | No response from API        | No          |
+| `NO_RESPONSE_MESSAGE`   | Response missing message    | No          |
+| `MAX_ITERATIONS`        | Max iterations reached      | Yes         |
+| `TOOL_EXECUTION_FAILED` | Tool execution failed       | Yes         |
+| `SUMMARIZATION_FAILED`  | Summarization failed        | Yes         |
+| `GENERIC_ERROR`         | Unknown error occurred      | No          |
+
+### Abort Requests
+
+Cancel ongoing requests using the abort functionality.
+
+```typescript
+const agent = createAgent(config);
+
+// Start a chat
+const chatPromise = agent.chat("Process this large dataset", context, {
+  onAborted: () => {
+    console.log("Request cancelled by user");
+  },
+});
+
+// Cancel after 5 seconds
+setTimeout(() => {
+  agent.abort();
+}, 5000);
+
+try {
+  const result = await chatPromise;
+} catch (error) {
+  if (error.name === "AbortError") {
+    console.log("Chat was aborted");
+  }
+}
+```
+
+#### With Custom AbortSignal
+
+```typescript
+const abortController = new AbortController();
+
+// Pass abort signal in context
+agent.chat("Hello", {
+  userId: "user-123",
+  timezone: "UTC",
+  abortSignal: abortController.signal,
+});
+
+// Cancel from external source
+abortController.abort();
+```
+
+---
+
+## Exports Summary
+
+### Main Entry (`concevent-ai-agent-sdk`)
+
+```typescript
+// Functions
+export { createAgent } from "./core/agent";
+export { createEvent } from "./types/events";
+
+// Constants
+export { ENCRYPTED_REASONING_MARKER } from "./core/openrouter-utils";
+
+// Types
+export type {
+  Agent,
+  ReasoningDetail,
+  ChatMessage,
+  FunctionDeclaration,
+  ToolExecutorContext,
+  ToolDefinition,
+  AgentConfig,
+  UsageMetadata,
+  AgentResult,
+  ToolCallStartData,
+  ToolResultData,
+  AgentCallbacks,
+  AgentEventType,
+  ThinkingEventData,
+  UsageUpdateEventData,
+  ErrorEventData,
+  CompleteEventData,
+  AgentEvent,
+} from "./types";
+```
+
+### React Entry (`concevent-ai-agent-sdk/react`)
+
+```typescript
+// Hooks
+export { useAgent } from "./useAgent";
+export { useAgentContext } from "./AgentProvider";
+
+// Components
+export { AgentProvider } from "./AgentProvider";
+
+// Types
+export type {
+  UseAgentReturn,
+  AgentProviderProps,
+  ChatItem,
+  FunctionCallDisplay,
+  AgentState,
+  UseAgentOptions,
+} from "./types";
+```
+
+---
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines before submitting a pull request.