{"id":30964661,"url":"https://github.com/sourcewizard-ai/react-ai-agent-chat-sdk","last_synced_at":"2025-09-11T22:11:16.706Z","repository":{"id":312824697,"uuid":"1048904724","full_name":"sourcewizard-ai/react-ai-agent-chat-sdk","owner":"sourcewizard-ai","description":"Embeddable Agentic AI Chat based on Vercel AI SDK","archived":false,"fork":false,"pushed_at":"2025-09-10T20:33:53.000Z","size":183,"stargazers_count":2,"open_issues_count":3,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-11T00:28:05.074Z","etag":null,"topics":["agent","ai","ai-sdk","chat-sdk","react","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sourcewizard-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-02T07:46:15.000Z","updated_at":"2025-09-10T20:33:57.000Z","dependencies_parsed_at":null,"dependency_job_id":"e903ce1a-2c66-4365-9d9c-601114ed9128","html_url":"https://github.com/sourcewizard-ai/react-ai-agent-chat-sdk","commit_stats":null,"previous_names":["sourcewizard-ai/react-ai-agent-chat-sdk"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sourcewizard-ai/react-ai-agent-chat-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcewizard-ai%2Freact-ai-agent-chat-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcewizard-ai%2Freact-ai-agent-chat-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcewizard-ai%2Freact-ai-agent-chat-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcewizard-ai%2Freact-ai-agent-chat-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sourcewizard-ai","download_url":"https://codeload.github.com/sourcewizard-ai/react-ai-agent-chat-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcewizard-ai%2Freact-ai-agent-chat-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274713085,"owners_count":25335995,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-11T02:00:13.660Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","ai-sdk","chat-sdk","react","typescript"],"created_at":"2025-09-11T22:11:11.212Z","updated_at":"2025-09-11T22:11:16.699Z","avatar_url":"https://github.com/sourcewizard-ai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# React AI Agent Chat SDK\n\nA React library for building AI-powered chat interfaces with tool execution, configurable timeouts, retry logic, and custom renderers.\nCAUTION NOTE: This library is partially vibe coded, I'll iterate on it to make it more reasonable over time.\n\n## Quick Start\n\n### 1. Install the Package\n\n```bash\nnpm install react-ai-agent-chat-sdk\n# or\npnpm add react-ai-agent-chat-sdk\n```\n\n**Peer Dependencies:**\n```bash\nnpm install react react-dom zod\n```\n\n**AI Provider (choose one):**\n```bash\n# For Anthropic Claude models\nnpm install @ai-sdk/anthropic\n\n# For OpenAI models  \nnpm install @ai-sdk/openai\n```\n\n### 2. Define Your Tools\n\nCreate tools with Zod schemas for type-safe input validation:\n\n```typescript\nimport { z } from 'zod';\nimport { createTool } from 'react-ai-agent-chat-sdk/config-server';\n\nconst readFileSchema = z.object({\n  file_path: z.string().describe('The path to the file to read'),\n});\n\nconst tools = {\n  read_file: createTool({\n    description: 'Read the contents of a file',\n    display_name: \"Reading file\",\n    inputSchema: readFileSchema,\n    execute: async ({ file_path }) =\u003e {\n      const content = await fs.readFile(file_path, 'utf-8');\n      return { file_path, content };\n    }\n  })\n};\n```\n\n### 3. Define Server Configuration\n\nCreate server configuration for API routes and tool execution:\n\n```typescript\nimport { makeAgentChatRouteConfig } from 'react-ai-agent-chat-sdk/config-server';\nimport { anthropic } from '@ai-sdk/anthropic';\nimport { MemoryStorage } from 'react-ai-agent-chat-sdk/storage';\n\nconst agentChatRouteConfig = makeAgentChatRouteConfig({\n  system_prompt: `You are a helpful assistant with access to file management tools.`,\n  tools,\n  auth_func: async () =\u003e true, // Replace with your auth logic\n  storage: new MemoryStorage(), // Use your preferred storage\n  modelConfig: {\n    model: anthropic('claude-sonnet-4-20250514'),\n    temperature: 0.3\n  }\n});\n```\n\n### 4. Define Client Configuration\n\nCreate client configuration for the React UI:\n\n```typescript\nimport { makeAgentChatClientConfig } from 'react-ai-agent-chat-sdk/config-client';\n\nconst agentChatClientConfig = makeAgentChatClientConfig({\n  tools: {\n    read_file: {\n      display_name: \"Reading file\"\n    }\n  },\n  route: \"/api/chat\", // Your chat API endpoint\n  // Optional: custom tool renderers\n  toolRenderers: {\n    read_file: CustomFileRenderer\n  }\n});\n```\n\n### 5. Add Chat and History Routes\n\nCreate API routes for chat and history:\n\n**For Next.js App Router (`app/api/chat/route.ts`):**\n```typescript\nimport { chatRoute } from 'react-ai-agent-chat-sdk/api';\nimport { agentChatRouteConfig } from '@/lib/agent-config';\n\nexport async function POST(req: Request) {\n  return chatRoute(agentChatRouteConfig, req);\n}\n```\n\n**History Route (`app/api/chat/history/route.ts`):**\n```typescript\nimport { chatHistoryRoute } from 'react-ai-agent-chat-sdk/api';\nimport { agentChatRouteConfig } from '@/lib/agent-config';\n\nexport async function GET(req: Request) {\n  return chatHistoryRoute(agentChatRouteConfig, req);\n}\n```\n\n**For Express.js (`server.js`):**\n```javascript\nimport { AgentChatRoute } from 'react-ai-agent-chat-sdk/api';\nimport { agentChatRouteConfig } from './lib/agent-config.js';\n\nconst app = express();\n\n// Chat endpoint\napp.post('/api/chat', AgentChatRoute(agentChatRouteConfig));\n\n// History endpoint  \napp.get('/api/chat/history', AgentChatRoute({\n  ...agentChatRouteConfig,\n  method: 'GET'\n}));\n```\n\n### 6. Add AgentChat UI Element\n\nUse the chat component in your React app:\n\n```typescript\n'use client';\n\nimport { useEffect, useState } from 'react';\nimport { AgentChat } from 'react-ai-agent-chat-sdk';\nimport 'react-ai-agent-chat-sdk/agent-chat.css';\nimport { agentChatClientConfig } from '@/lib/agent-chat-client-config';\n\nexport default function ChatPage() {\n  const [conversationId, setConversationId] = useState\u003cstring\u003e('');\n  \n  useEffect(() =\u003e {\n    // Load or create conversation ID for persistence\n    let id = localStorage.getItem('current-conversation-id');\n    if (!id) {\n      id = `conv_${crypto.randomUUID()}`;\n      localStorage.setItem('current-conversation-id', id);\n    }\n    setConversationId(id);\n  }, []);\n  \n  if (!conversationId) {\n    return \u003cdiv\u003eLoading...\u003c/div\u003e;\n  }\n  \n  return (\n    \u003cAgentChat \n      config={agentChatClientConfig} \n      conversationId={conversationId} \n    /\u003e\n  );\n}\n```\n\n## Architecture Overview\n\nThe SDK now uses a **frontend/backend separation** architecture:\n\n- **Backend Configuration** (`config-server`): Handles tool execution, AI model configuration, authentication, and storage. Used in API routes.\n- **Frontend Configuration** (`config-client`): Handles UI rendering, tool display names, and custom renderers. Used in React components.\n- **Shared Types**: Both configurations share the same tool definitions and conversation structure.\n\n## Customization\n\n### Tool Renderers\n\nCreate custom renderers for specific tools:\n\n```typescript\nimport { ToolCall, ToolResult } from 'react-ai-agent-chat-sdk/config';\n\nexport function CustomFileRenderer({ toolCall, toolResult }: { \n  toolCall: ToolCall; \n  toolResult?: ToolResult \n}) {\n  const hasError = toolResult?.output?.__toolError;\n  const isTimeout = hasError \u0026\u0026 toolResult?.output?.__errorType === 'ToolTimeoutError';\n  \n  const getStatusText = () =\u003e {\n    if (isTimeout) return 'Timed out';\n    if (hasError) return 'Error';\n    if (toolResult?.output) return 'Completed';\n    return 'Running';\n  };\n\n  return (\n    \u003cdiv className={`custom-renderer ${hasError ? 'error' : ''}`}\u003e\n      \u003cdiv\u003e📁 {toolCall.toolName} - {getStatusText()}\u003c/div\u003e\n      {toolResult?.output \u0026\u0026 (\n        \u003cpre\u003e{JSON.stringify(toolResult.output, null, 2)}\u003c/pre\u003e\n      )}\n    \u003c/div\u003e\n  );\n}\n```\n\nAdd renderers to your configuration:\n\n```typescript\n// lib/agent-chat-client-config.ts\nimport { makeAgentChatClientConfig } from 'react-ai-agent-chat-sdk/config-client';\nimport { CustomFileRenderer } from './renderers';\n\nexport const agentChatClientConfig = makeAgentChatClientConfig({\n  tools: {\n    read_file: {\n      display_name: \"Reading file\"\n    }\n  },\n  route: \"/api/chat\",\n  toolRenderers: {\n    read_file: CustomFileRenderer,\n  }\n});\n```\n\n### Route Parameters\n\nCustomize API endpoints to fit your application structure:\n\n```typescript\n// Server config\nconst agentChatRouteConfig = makeAgentChatRouteConfig({\n  system_prompt: \"You are a helpful assistant.\",\n  tools,\n  auth_func: async () =\u003e true,\n  storage: new MemoryStorage()\n});\n\n// Client config\nconst agentChatClientConfig = makeAgentChatClientConfig({\n  tools: {\n    // Tool definitions for display\n  },\n  route: \"/api/v1/chat\", // Custom chat route\n  historyRoute: \"/api/v1/history\" // Custom history route (optional)\n});\n```\n\n### Retry Configurations\n\nConfigure timeouts and retries globally and per-tool:\n\n**Global Configuration:**\n```typescript\nconst agentChatRouteConfig = makeAgentChatRouteConfig({\n  system_prompt: \"You are a helpful assistant.\",\n  tools,\n  auth_func: async () =\u003e true,\n  storage: new MemoryStorage(),\n  toolExecutionConfig: {\n    timeoutMs: 30000, // 30 seconds default\n    retries: 3,\n    retryDelayMs: 1000 // 1 second initial delay\n  }\n});\n```\n\n**Per-Tool Configuration:**\n```typescript\nconst tools = {\n  slow_operation: createTool({\n    description: 'A slow operation that needs longer timeout',\n    display_name: \"Processing data\",\n    inputSchema: z.object({}),\n    execute: async () =\u003e {\n      // Long-running operation\n    },\n    executionConfig: {\n      timeoutMs: 60000, // 1 minute timeout\n      retries: 1, // Only 1 retry\n      retryDelayMs: 5000 // 5 second delay\n    }\n  })\n};\n```\n\n**Storage Configuration:**\n```typescript\nimport { MemoryStorage } from 'react-ai-agent-chat-sdk/storage';\n\n// For development\nconst storage = new MemoryStorage();\n\n// For production, implement ChatStorage interface\nclass MyStorage implements ChatStorage {\n  async saveMessage(conversationId: string, message: ChatMessage): Promise\u003cvoid\u003e {\n    // Save to your database\n  }\n  \n  async getConversation(conversationId: string): Promise\u003cConversation | null\u003e {\n    // Retrieve from your database\n  }\n}\n\nconst agentChatRouteConfig = makeAgentChatRouteConfig({\n  system_prompt: \"You are a helpful assistant.\",\n  tools,\n  auth_func: async () =\u003e true,\n  storage // Add storage for conversation persistence\n});\n```\n\n**Model Configuration:**\n```typescript\nimport { openai } from '@ai-sdk/openai';\nimport { messageCountIs } from 'ai';\n\nconst agentChatRouteConfig = makeAgentChatRouteConfig({\n  system_prompt: \"You are a helpful assistant.\",\n  tools,\n  auth_func: async () =\u003e true,\n  storage: new MemoryStorage(),\n  modelConfig: {\n    model: openai('gpt-4o'), // Use different AI models\n    temperature: 0.7,\n    stopWhen: messageCountIs(10), // Stop after 10 messages\n    onStepFinish: (step) =\u003e {\n      console.log('Step finished:', step.finishReason);\n    }\n  }\n});\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsourcewizard-ai%2Freact-ai-agent-chat-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsourcewizard-ai%2Freact-ai-agent-chat-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsourcewizard-ai%2Freact-ai-agent-chat-sdk/lists"}